2.4.1.1 X-Functions Overview

XFs-Overview

X-Functions provide a uniform way to access nearly all of Origin's capabilities from your LabTalk scripts. The best way to get started using X-Functions is to follow the many examples that use them, and then browse the lists of X-Functions accessible from script provided in the LabTalk-Supported X-Functions section.

Syntax

You can recognize X-Functions in script examples from their unique syntax:

xFunctionName [argument1:=<range,name or value> argument2:=<range,name or value> ... ][ -switch];

General Notes:

• The arguments can be input, output or parameters needed
• There can be multiple inputs, outputs, and parameters
• X-Function can be called with subset of arguments since usually there are default value for each argument

Notes on X-Function Argument OrderArgument Order:

• By default, X-Functions expect their input and output arguments to appear in a particular order. Run X-Function -h to view the Help
• If the arguments are supplied in the order specified by Origin, there is no need to type out the argument names.
• If the argument names are explicitly typed, arguments can be supplied in any order.
• You can mix handling of arguments as long as omitted arguments come first in the specified order, followed by explicitly typed arguments in any order.
• The argument name can be shortened by trimming characters from the end of the argument name, but the shortened name needs to be unique.

The following examples use the fitpoly X-Function to illustrate these points.

Examples

Run xfunctionname -hv to check the arguments and orders

fitpoly -hv; //will dump all variables
Variables:
  iy: [in] 
  polyorder: [in] 
  fixint: [in] 
  intercept: [in] 
  coef: [out] 
  oy: [out] 
  N: [out] 
  AdjRSq: [out] 
  RSqCOD: [out] 
  err: [out]

Origin would expect the arguments listed in Variables section when calling fitpoly

fitpoly iy:=XYrange polyorder:=int fixint:=int intercept:=double coef:=vector oy:=XYRange N:=int adjRSq:=double RSqCOD:=double err:=vector;

Follow the argument order and explicitly write argument names

fitpoly iy:=(1,2) polyorder:=4 fixint:=0 intercept:=0 coef:=3 oy:=(4,5) N:=100 AdjRSq:=adjr2 RSqCOD:=cod err:=6;

tells Origin to

• iy:=(1,2) - fit XY data (x in column 1 and y in column 2 in active sheet),
• polyorder:=4 - with 4th order,
• fixint:=0 - intercept not fixed,
• intercept:=0 - initial intercept value 0,
• coef:=3 - put coordinates in 3rd column in active sheet,
• oy:=(4,5) - put XY data after fit (x in column 4 and y in column 5 in active sheet),
• N:=100 - number of points in output XY data is 100
• AdjRSq:=adjr2 - put calculated AdjRSq value to variable adjr2,
• RSqCOD:=cod - put calculated RSqCOD value to variable cod,
• err:=6 - put Polynomial Coefficients Errors in column 6 in active sheet

Argument names can be skipped if following the argument order

fitpoly (1,2) 4 0 0 3 (4,5) 100 adjr2 cod 6;

The values will be assigned to corresponding arguments. E.g. (1,2) will be assigned to iy, 4 will be assigned to polyorder, and so on. values in parenthesis, e.g. (1,2) will be assigned to one argument.

Explicitly write argument names so no need to follow argument order

fitpoly coef:=3 N:=100 polyorder:=4 oy:=(4,5) iy:=(1,2);

for arguments not listed, will use default value, default values in X-Function definition will be used, e.g .

• intercept not fixed and starts with 0
• AdjRSq, RSqCOD, and Polynomial Coefficients Errors not output

Partly follow argument order

fitpoly (1,2) 4 oy:=(4,5) N:=100 coef:=3;

Beginning 2 arguments following definition order so argument names are skipped. Then explicitly writ argument names in random order. If an argument is not listed, default value is used.

Argument names shortened as long as it's unique in the argument list

The following will work since poly is short for polyorder, co for coef, and o for oy. They are all unique.

fitpoly iy:=(1,2) poly:=4 co:=3 o:=(4,5) N:=100;

The following will produce an error since there are two argument names (iy and intercept) that begin with letter i. Origin cannot tell which argument i refers to.

fitpoly i:=(1,2) poly:=4 co:=3 o:=(4,5) N:=100;

Write the X-Function call in multi-lines

fitpoly 
coef:=3 
N:=100 
polyorder:=4 
oy:=(4,5) 
iy:=(1,2);

The X-Function call can be written in multi-lines as long as the argument names are explicitly typed out.

Option Switches

Option switches such as -h or -d allow you to access alternate modes of executing X-functions from your scripts. They can be used with or without other arguments. The option switch (and its value, where applicable) can be placed anywhere in the argument list. This table summarizes the primary X-Function option switches:

For more on option switches, see the section X-Function Execution Options.

Generate Script from Dialog Settings

The easiest way to call an X-Function is with the -d option and then configures its settings using the graphical user interface (GUI).

In the GUI, once the dialog settings are done, you can generate the corresponding LabTalk script for the configuration by selecting the Generate Script item in the dialog theme fly-out menu. Then a script which matches the current GUI settings will be output to script window and you can copy and paste it into a batch OGS file or some other project for use.

Note: The Dialog Theme box and corresponding Generate Script fly-out menu item are not available from all X-Function dialogs that you open with the -d option (for instance, compare fitpoly -d with rnormalize -d).

The amount of information that is displayed using the Generate Script feature is controlled by a System Variable @GAS. By default, @GAS = 0 but this value may be changed via System Variables... in the Preferences menu.