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 input:=<range> argument:=<name/value> output:=<range> -switch;

General Notes:

• X-Functions can have multiple inputs, outputs, and arguments.
• X-Functions can be called with any subset of their possible argument list supplied.
• If not supplied a value, each required argument has a default value that is used.
• Each X-Function has a different set of input and output arguments.

Notes on X-Function Argument OrderArgument Order:

• By default, X-Functions expect their input and output arguments to appear in a particular order.
• Expected argument order can be found in the help file for each individual X-Function or from the Script window by entering XFunctionName -h.
• 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

The fitpoly X-Function has the following specific syntax, giving the order in which Origin expects the arguments:

fitpoly iy:=(inputX,inputY) polyorder:=n fixint:=(0=No/1=Yes) intercept:=value coef:=columnNumber oy:=(outputX,outputY) N:=numberOfPoints;

If given in the specified order, the X-Function call,

//Polynomial fit on XY data (X-column 1, Y-column 2), 
//Polynomial order = 4
// Not fix intercept value, Initial intercept Value is 0, 
//Output Coef in column 3, 
//Output X value in column 4, Output Y values in column 5, 
//Number of points of output XY =100
fitpoly (1,2) 4 0 0 3 (4,5) 100;

tells Origin to fit a 4th order polynomial with 100 points to the X-Y data in columns 1 and 2 of the active worksheet, putting the coefficients of the polynomial in column 3, and the X-Y pairs for the fit in columns 4 and 5 of the active worksheet.

In contrast, the command with all options typed out is a bit longer but performs the same operation:

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

In return for typing out the input and output argument names, LabTalk will accept them in any order, and still yield the expected result:

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

It is also permissible to omit some argument names, then follow with other named arguments in any order, as in the following script, which yields the same result as above.

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

You can also shorten the argument name if the shortened name is unique in the argument list, as in ...

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

... where poly is short for polyorder, and co for coef, and o for oy.

However, the following script will produce an error...

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

... because there are two argument names (iy and intercept) that begin with letter i. Here Origin cannot tell which argument i refers to; that is to say i is not unique.

Inputs and outputs can be placed on separate lines from each other and in any order, as long as they are explicitly typed out.

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

Notice that the semicolon ending the X-Function call comes only after the last parameter associated with that X-Function.

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).