5.5 Use X-Function in LabTalk

1 Summary
2 What You Will Learn
3 Steps

Summary

X-Functions provide a uniform way to access many of Origin's capabilities from your LabTalk scripts.

The syntax to call an X-Function is:

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

Option switches allow you to access alternate modes of executing X-functions from your scripts, such as use the -h switch to access its help file to output arguments and definitions:

xFunctionName -h;

X-Function operations are often associated with an option tree, which is accessible with the op_change X-Function. It is possible to use this op_change X-Function to make changes to some arguments and re-execute the X-Function operation.

If an X-Function generates report data, you can get the data and put it to a specific worksheet/column or a tree variable.

What You Will Learn

This tutorial will show you how to:

call X-Function with LabTalk script
generate script from dialog settings
manipulate tree node options for X-Function
get the operation tree, change settings and run X-Function again with new settings
send result data to tree variable or worksheet/column
use switch options when accessing X-Function

Steps

Call X-Function

Launch Origin and start with a new empty OPJ file. In Script window, call the X-Function newbook to create a new workbook.

//Create a new workbook with long name "Curves", short name saved to string variable bkn$
newbook name:="Curves" result:=bkn$;
//Check the string variable value
bkn$=;

Two ways to get the x-function help

<xfunctionname> -h will dump help in the Script window. E.g. newbook -h
help <xfunctionname> will open the corresponding help page, e.g. help newbook

Generate Script from X-Function Dialog

Generate Script context menu in X-Function dialog provides a GUI way to set input, output and parameters and generate corresponding script.

In Script window, run namebook function with -d switch

//newbook -d also works
newbook name:="Curves" result:=bkn$ -d;

In the x-Function that opens, set Number of Sheets to 5.
Click the triangle button next to the Dialog Theme, choose Generate Script in the fly-out menu, the LabTalk script for this operation will be typed to the script window for future use

newbook name:=Summary sheet:=5 result:=bkn$;

Cancel the X-Function dialog.

Call X-Functions with Options Tree

Some X-Function may have many parameters and related parameters are put in tree, e.g. ImpASC X-Function.

Run the following script to open the impASC X-Function dialog

//-d is the switch to open the x-function dialog
impASC -d;

Browse to select the file Polynomial Fit.dat under <Origin Exe Folder>\Samples\Curve Fitting\ path
Under the Import Options tree node, select No for Add Sparklines, and uncheck Rename Sheet with (Partial) Filename, Rename Book with (Partial) Filename and Append Filename to Workbook Comment.
Click the triangle button next to the Dialog Theme, choose Generate Script in the fly-out menu, the LabTalk script for this operation will be typed to the script window.
Click Cancel to exit the ImpASC dialog, and the script should be dumped in Script Window.

We write it into multi-lines so user can see how the settings are set in Options tree and subnode names

//Note: the file path may differ from your Origin EXE path

impASC fname:="C:\Program Files\OriginLab\Origin2023\Samples\Curve Fitting\Polynomial Fit.dat" 
options.Sparklines:=0 
options.names.FNameToSht:=0 
options.names.FNameToBk:=0
options.names.FNameToBkComm:=0;

If it's a one line script. Just put cursor on the line and press Enter to execute it. If it's in multiple lines, highlight them and press Enter to execute it. The "options" in the script above is a tree variable, which is used to set and store parameters for this X-Function.

Call X-Function Operation

Some X-Function does operation (e.g. fitting, statistics, data handling) on Origin objects (e.g. column, sheet, plot) and generates some output in other Origin objects, E.g. the fitpoly X-Function will do polynomial fit on XY range and put coefficients and fitted curve in other columns.

For such X-Functions, use -r switch to set the recalculation mode. Auto will auto trigger recalculation if input changes, while Manual will not trigger recalculation till user triggers it manually.

Run the following script to do 2nd order polynomial fit on XY data in 1st two columns in book named bkn$. Use -r 1 tswitch to set the operation's recalculation mode to "Auto"

fitpoly iy:=[%(bkn$)]!(1,2) polyorder:=2 
        coef:=<new> oy:=[<Input>]<new>!<new> 
        AdjRSq:=arsq RSqCOD:=rsq -r 1;
arsq=; //output AdjRSq value
rsq=; //output RSqCOD value

Sheet2 is created with XY value of fitted curve. Polynormial Coefficients are output to column D on Sheet1.
There are green locks on output which indicate it's an output of an operation. Mouse over the green lock to see operation info (fitpoly).

Change Parameter of the X-Function and Recalculate

Make Sheet2 active. Create a range variable which is output of the operation.
```
range r1 = [%(bkn$)]%(page.active$)!col(1); //column A of Sheet2
```
Use op_change X-Function to get the operation setting to a tree variable mytree.
```
op_change ir:=r1 tr:=mytree;
```
Output the mytree contents.

mytree.=;

You can now change operation settings using the mytree variable.

//Change the input data
mytree.xfGetN.iy.Range1.Y$ = "[%(bkn$)]1!C";
//Change the polynomial order
mytree.xfGetN.polyorder = 3;

You can run the script "mytree.=;" again to check the modified settings.
Now execute the operation again with the modified settings.

op_change ir:=r1 tr:=mytree op:=run;

Get Results from X-Functions

You can get report data from an X-Function operation and send it to a specific book/sheet/column location, or a tree variable.

Get result from auto generate object

Some X-Functions auto generate an output object same name as the xfunction. E.g. stats, fitLR, fitPoly, and fitMR, etc.

Run the following script to view fitpoly object

fitpoly.=;
range rStats=3; //set range variable rStats to 3rd column in active sheet
rStats[1]=fitpoly.N; 
rStats[2]=fitpoly.AdjRSq;
rStats[3]=fitpoly.RSqCOD;

N, AdjRSq, RSqCOD will be put to the cells in 3rd column

Run the following script to get basic statics of a column

 
stats [%(bkn$)]1!C; //do statistics on column C of 1st sheet in workbook named bkn$
stats.=; //check all properties of the created stats object

Put Result to a Tree Object

Create a new worksheet with the newsheet X-Function.

newsheet;
//Get the sheet name in string register %B
%B = page.active$;

Fill in some data in column A.

col(A) = {13.2, 14.1, 11.7, 23.9, 10.3};

Use the grubbs X-Function to detect if there is an outlier in column A.

//Output the report data into tree variable tr
//If tr does not exist yet, it will be created
grubbs ix:=col(A) rt:=tr;

Use the following script to get the tree structure and values.

tr.=;

Get result values from tree variable and pass to double or string variables.

//Get the row index for suspected outlier
double rindex = tr.Stats.Stats.C2;
//Get the conclusion string
string conclusion$ = tr.Stats.Footer$;
//Display the conclusion sentence right to the data cell of the suspected outlier
col(B)[$(rindex)]$ = conclusion$;
//Change column width to display all texts
wks.col2.width=40;

Put Result to a Worksheet

Run the grubbs x function again, but this time send the report data to a specified worksheet Result.

//Create the new worksheet "Result"
newsheet name:=Result;
//Send the report data to the Result worksheet
grubbs ix:=[%H]%B!col(A) rt:=[<Input>]Result!; 
//Note: the above newsheet script isn't necessary since if sheet with name Result doesn't exist, 
//it will be created automatically.