LabTalk Scripting Guide

Copyright © 2016 by OriginLab Corporation

All rights reserved. No part of the contents of this book may be reproduced or transmitted in any form
or by any means without the written permission of OriginLab Corporation.
OriginLab, Origin, and LabTalk are either registered trademarks or trademarks of OriginLab
Corporation. Other product and company names mentioned herein may be the trademarks of their
respective owners.

OriginLab Corporation
One Roundhouse Plaza
Northampton, MA 01060
USA
(413) 586-2013
(800) 969-7720
Fax (413) 585-0126
www.OriginLab.com
 Table of Contents
Table of Contents .....................................................................................................................iii
1 Getting Started with LabTalk ........................................................................................ 1
1.1 Hello World .................................................................................................................................... 1
1.2 Using = to Get Quick Output ......................................................................................................... 2
1.3 Other Ways to Execute Script ....................................................................................................... 2
1.4 Script Example .............................................................................................................................. 4
1.5 Where to Go from Here? ............................................................................................................... 6
2 Resources for Learning LabTalk .................................................................................. 7
2.1 Online Documentation ................................................................................................................... 7
2.2 Tutorials ......................................................................................................................................... 7
2.3 Script Examples ............................................................................................................................ 7
2.4 X-Function Script Examples .......................................................................................................... 7
2.5 LabTalk Forum .............................................................................................................................. 7
2.6 Training and Consulting ................................................................................................................ 7
3 Language Fundamentals .............................................................................................. 9
3.1 Language Fundamentals .............................................................................................................. 9
3.2 General Language Features ......................................................................................................... 9
3.3 Special Language Features ........................................................................................................ 44
3.4 LabTalk Script Precedence ......................................................................................................... 75
4 Calling X-Functions and Origin C Functions ..............................................................77
4.1 Calling X-Functions and Origin C Functions ............................................................................... 77
4.2 X-Functions ................................................................................................................................. 77
4.3 Origin C Functions ...................................................................................................................... 86
5 Running and Debugging LabTalk Scripts ...................................................................91
5.1 Running and Debugging LabTalk Scripts ................................................................................... 91
5.2 Running Scripts ........................................................................................................................... 91
5.3 Debugging Scripts ..................................................................................................................... 114
6 String Processing .......................................................................................................123
6.1 String Processing ...................................................................................................................... 123
6.2 String Variables and String Registers ....................................................................................... 123
6.3 String Processing ...................................................................................................................... 124
6.4 Converting Strings to Numbers ................................................................................................. 126
6.5 Converting Numbers to Strings ................................................................................................. 126
6.6 String Arrays.............................................................................................................................. 128
7 Workbooks Worksheets and Worksheet Columns ..................................................131
7.1 Workbooks Worksheets and Worksheet Columns.................................................................... 131
7.2 Workbooks ................................................................................................................................ 131
7.3 Worksheets ............................................................................................................................... 136
7.4 Worksheet Columns .................................................................................................................. 147
8 Matrix Books Matrix Sheets and Matrix Objects ......................................................159
8.1 Matrix Books Matrix Sheets and Matrix Objects ....................................................................... 159
8.2 Basic Matrix Book Operation..................................................................................................... 159
8.3 Matrix Sheets ............................................................................................................................ 161
8.4 Matrix Objects ........................................................................................................................... 162
9 Graphing .....................................................................................................................171
9.1 Graphing.................................................................................................................................... 171
9.2 Creating Graphs ........................................................................................................................ 171
9.3 Formatting Graphs .................................................................................................................... 174

iii
 LabTalk Scripting Guide

9.4 Managing Layers ....................................................................................................................... 177

9.5 Creating and Accessing Graphical Objects .............................................................................. 179
10 Importing.....................................................................................................................185
10.1 Importing ................................................................................................................................... 185
10.2 Importing Data ........................................................................................................................... 186
10.3 Importing Images ...................................................................................................................... 189
11 Exporting ....................................................................................................................193
11.1 Exporting ................................................................................................................................... 193
11.2 Exporting Worksheets ............................................................................................................... 193
11.3 Exporting Graphs ...................................................................................................................... 194
11.4 Exporting Matrices .................................................................................................................... 196
11.5 Exporting Videos ....................................................................................................................... 196
12 The Origin Project ......................................................................................................199
12.1 The Origin Project ..................................................................................................................... 199
12.2 Managing the Project ................................................................................................................ 199
12.3 Accessing Metadata .................................................................................................................. 202
12.4 Looping Over Objects ............................................................................................................... 207
12.5 Protecting Project Data ............................................................................................................. 211
13 Analysis and Applications .........................................................................................217
13.1 Analysis and Applications ......................................................................................................... 217
13.2 Mathematics .............................................................................................................................. 217
13.3 Statistics .................................................................................................................................... 224
13.4 Curve Fitting .............................................................................................................................. 231
13.5 Signal Processing ..................................................................................................................... 235
13.6 Peaks and Baseline .................................................................................................................. 239
13.7 Image Processing ..................................................................................................................... 240
14 User Interaction ..........................................................................................................245
14.1 User Interaction ......................................................................................................................... 245
14.2 Getting Numeric and String Input .............................................................................................. 245
14.3 Getting Points from Graph ........................................................................................................ 249
14.4 Bringing Up a Dialog ................................................................................................................. 252
15 Working with Excel.....................................................................................................255
16 Running R in Origin....................................................................................................257
16.1 Running R in Origin ................................................................................................................... 257
16.2 Examples: Perform Logistic regression in R by using LabTalk ................................................. 260
17 Working with Python ..................................................................................................263
17.1 Run Python in Origin ................................................................................................................. 263
17.2 Access Origin in Python ............................................................................................................ 265
17.3 A Note to Use Python Extensions ............................................................................................. 266
18 Automation and Batch Processing ...........................................................................269
18.1 Automation and Batch Processing ............................................................................................ 269
18.2 Analysis Templates ................................................................................................................... 269
18.3 Using Set Column Values to Create an Analysis Template ...................................................... 270
18.4 Batch Processing ...................................................................................................................... 270
19 Function Reference ....................................................................................................273
19.1 Function Reference ................................................................................................................... 273
19.2 LabTalk-Supported Functions ................................................................................................... 273
19.3 LabTalk-Supported X-Functions ............................................................................................... 352
20 Appendix .....................................................................................................................373
Index …………………………………………………………………………………………………375

iv
1 Getting Started with LabTalk

1.1 Hello World

We begin with a classic example to show you how to execute LabTalk script.
1. Open Origin, and from the Window menu, select the Script Window option. The Script

Window will open.

2. In this window, type the following text and then press Enter:

type "Hello World"

3. Here we used LabTalk command type. Commands can be abbreviated down to 2
characters, try:
ty "Hello World"
Origin will output the text Hello World directly beneath your command.

Note that when you press Enter, Origin adds a semicolon, ;, at the end of the line and
also executes that line of script.
To repeat the execution of a line of script, place the cursor anywhere within the line
and press Enter. If you place the cursor at the end of the line, you need to remove the
; before pressing Enter to execute that line of script.

Now let us see how to execute multiple lines of script from the script window:
1. With a workbook window active in Origin, open the Script Window

2. Type the following lines of script in the script window. At the end of each line, press Enter after

typing the ;. This will prevent execution of the line. We will later execute all lines together.

type "The current workbook is %h";

type "This book has $(page.nlayers) sheet(s)";
type "There are $(wks.ncols) columns in the active sheet";
3. Using the mouse, drag and select all lines of script. If using keyboard, place the cursor at the

beginning of the script, then hold down the Shift key, and use the arrow keys to highlight all

lines.

4. Press Enter to execute all selected lines of script. Depending on the workbook that was active,

the output in the script window will be similar to the following text:

The current workbook is Book1

This book has 1 sheet(s)
There are 2 columns in the active sheet

1
 LabTalk Scripting Guide

In the above example, we used the %H String Register that holds the currently active window name
(which could be a workbook, a matrix, or a graph). We then used the page and wks LabTalk Objects
to get the number of sheets in the book and the number of columns in the sheet. The $() is a
substitution notations which tells Origin to evaluate the expression within the () and return its value.

If you are typing in multiple lines of script in the Script Window, you can add a ; at the
end of a line and then press Enter to avoid execution of the line. This allows you to
type in multiple lines without executing each line. You can then select all lines and
press Enter to execute them all.

1.2 Using = to Get Quick Output

The script window can be used as a calculator to return results interactively. Type the following script
in the script window and press Enter:
3+5=
Origin computes the result and displays it in the next line:
3+5=8
The = character is typically used as an assignment operator, with a left- and right-hand side. When
the right-hand side is missing, the interpreter will evaluate the expression on the left of the =
character and print the result in the script window.
In the following example, we introduce the concept of variables in LabTalk. Entering the following
assignment statement in the script window:
double A = 2
creates a variable A and initializes its value to 2. Then you can perform some arithmetic on variable
A, such as multiplying by PI (a constant defined in Origin, ) and assign the result back to A:
A = A*PI
To display the current value of A, type:
A=
Press Enter and Origin responds with:
A = 6.2831853071796
In addition, there are List command to view a list of variables and their values. Type the following
command and press Enter:
list
Origin will open the LabTalk Variables and Functions dialog that lists all variables.
You can also get a dump of a specific type of variables, for example
list v
to list the numeric variables.

1.3 Other Ways to Execute Script

In previous examples, you saw how to execute script from the Script Window. Origin provides
several other ways to organize and execute LabTalk script. These are outlined in detail in the
Running and Debugging LabTalk Scripts chapter. Here we take a quick look at a few of the
methods to execute script: (1) from the Custom Routine toolbar button, (2) from a custom menu
item, and (3) from a button in a graph page.

1.3.1 Custom Routine Button

Origin provides a convenient way to save script and run it with the push of a toolbar button.
1. While holding down Ctrl+Shift on your keyboard, press the Custom Routine button ( )

located in the Standard Toolbar.

2
 Getting Started with LabTalk

2. This opens Code Builder, Origin's native script editor. The file being edited is called

Custom.ogs. The code has one section, [Main], and contains one line of script:

[Main]
type -b $General.Userbutton;
3. Replace that line with the following:
[Main]
type -b "Hello World";

4. Then press the Save ( ) button in the Code Builder window.

5. Now go back to the Origin application window and click the button.

Origin will again output the text Hello World, but this time, because of the -b switch used with the
type command, the text will be presented in a pop-up window.

1.3.2 Custom Menu Item

LabTalk script can be executed from a custom menu item.
1. Select the menu item Tools: Custom Menu Organizer... to open the Custom Menu

Organizer dialog.

2. Make the Add Custom Menu tab active. Then right-click inside the left panel and select New

Main Popup from the context menu.

3. In the right panel, enter a name for Popup Text, such as My Menu. then click outside of the

edit box.

4. Select My Menu from the left panel, and then right click on it, and select Add Item from the

context menu.

5. In the right panel, change the Item Text to Hello World, then add the following script to the

LabTalk Script text box:

type -b "Hello World";

6. Click the Close button, and in the window that pops up, press Yes to save the menu changes

as Default menu. In the file dialog that opens, press Save to save the file with the default name

to the default folder (User Files Folder).

3
 LabTalk Scripting Guide

7. A new menu named My Menu should now appear in the menu bar, to the left of the Window

menu. Click on this new menu item, and then click on the Hello World entry in the drop-down.

A Hello World dialog will pop up.

1.3.3 Button in a Graph

Origin also provides the ability to add a button to a graph or worksheet, and then execute LabTalk
script by pushing that button. This allows for script to be saved with a specific project or window.
1. Press the New Graph button ( ) located in the Standard Toolbar to create a new graph.

2. Press the Text Tool button ( ) in the Tools Toolbar, and then click on the newly created

graph and type the text My Button. Then click outside the text to finish editing the text.

3. Right click on the text to bring up the context menu, and then select Programming Control to

open the Programming Control dialog.

4. In the dialog, select Button Up from the Script, Run After: drop-down list, and then type the

following script in the edit box:

type -b "Hello World";

5. Click OK to close the dialog. Now the text label becomes a button. Click the button. A Hello

World dialog will pop up.

1.4 Script Example

We now present a script example that walks you through a particular scenario of importing and
processing data, and then saving the project. This example uses several LabTalk language features
such as Commands, Objects, and X-Functions. You will learn more details about these language
features in subsequent chapters.
NOTE: We will use the Script Window to execute these statements. To execute a single line of
code, make sure that you leave out the ; at the end before pressing Enter. For multiple lines of code,
at the end of each line, press Enter after the ; to continue entering the next line. After you have typed
in all lines, select them all and then press Enter to execute.
Let's start with a new project using the doc command and the -n switch. If the current project needs
saving, this command will prompt user to save.
doc -n
Now let's import a data file from the Samples folder. We will first use the dlgfile X-function to locate
the desired file:
dlgfile gr:=ASCII
Then select the file S15-125-03.dat from the \Samples\Import and Export sub folder located in your
Origin installation folder, and click Open.

4
 Getting Started with LabTalk

The above process will load the file path and name into a variable named fname$. You can examine
the value of this variable by typing:
fname$=
Now let's import this files into the active workbook. We will use the impasc X-Function with options to
control naming, so that the file name does not get assigned to the workbook:
impasc Options.Names.FNameToBk:=0
Now we want to perform some data processing of the Position column. We first define a range
variable to point to this column.:
range rpos = "Position"
Since the column we select is also the 4th column in the current worksheet, we can also use index
number to specify it.
range rpos = 4
You can check what range variables are currently defined, using this command:
list a
We now normalize the column so that the values go from 0 to 100. To check what X-Functions are
available for normalization, we can use the command:
lx *norm*
The above command will dump X-Functions where the name contains norm. There are several X-
Functions for normalizing data. For our current purpose we will use the rnormalize X-Function.
To get help on the syntax for this particular X-Function, you can type:
rnormalize -h
to dump the information, or type:
help rnormalize
to open the help file.
Let us now normalize the position column:
rnormalize irng:=rpos method:=range100 orng:=<input>
The normalized data will be placed in the same column, replacing the original data, as we set the
output range variable orng to be <input>.
When using X-Functions, you can leave out the variable names, if they are specified in the correct
order. The above line of code can therefore be written as:
rnormalize rpos range100 orng:=<input>
The reason we still specified the name orng is because there are other variables that precede this
particular variable, which are not relevant to our current calculation and were therefore not included in
the command.

Now let's do some changes to the folder in the project. There are several X-Functions for managing
project folders, and we will use some of them:
// Get the name of the current worksheet
string name$ = wks.name$;
// go to root folder
pe_cd ..;
// rename Folder1 to be the same as worksheet
pe_rename Folder1 name$;
Now let's list all the sub folders and workbooks under the root folder:
pe_dir
Finally, let's save the Origin Project to the User Files Folder. The location of the user files folder is
stored in the string register %Y. You can examine where your User Files Folder is by checking this
variable:
%Y =
Now let's use the save command to save our project to User Files Folder, with the name
MyProject.opj.
save %yMyProject
In the above command %Y will be replaced with the User Files Folder path, and thus our project will
be saved in the correct location.

5
 LabTalk Scripting Guide

1.5 Where to Go from Here?

The answer to this question is the subject of the rest of the LabTalk Scripting Guide. The examples
above only scratch the surface, but have hopefully provided enough information for you to get a quick
start and excited to learn more. The next chapter lists various resources available for learning
LabTalk.

6
2 Resources for Learning LabTalk
Besides the content provided in this guide, the following resources are available for learning LabTalk.

2.1 Online Documentation

Most up-to-date documentation for LabTalk, including updates to this guide, can be found online at
this location: http://www.originlab.com/doc/labtalk

2.2 Tutorials
Several LabTalk tutorials are shipped with Origin. These are accessible from the Help menu.

2.3 Script Examples

Various Script Examples are shipped with Origin. These are accessible from the Help menu, and are
contained in the sub folder: <Origin Installation Folder>\Samples\LabTalk Script Examples\.

2.4 X-Function Script Examples

Press the F11 key in Origin to open the XF Script Dialog. This dialog provides many script examples
specific to calling X-Functions, organized in various categories such as Import, Fitting, Signal
Processing, and Spectroscopy.

2.5 LabTalk Forum

Post your question on the LabTalk forum. Go to: http://www.originlab.com/forum and then select the
LabTalk Forum. Our forums are monitored by our technical staff, plus you may get ideas and
answers from other power users as well.

2.6 Training and Consulting

OriginLab and our distributors worldwide offer Training and Consulting services to help you with
advanced customization using LabTalk. Please contact us for further details.

7
3 Language Fundamentals

3.1 Language Fundamentals

In this chapter, we introduce various aspects of the LabTalk language structure. In the first section
you will learn about general language features such as data types, variables, operators, conditional
and loop structures, macros and functions. The second section covers features that are unique to
LabTalk, such as range and substitution notation, objects, methods and properties, and accessing X-
Functions.

This chapter covers the following topics:

 LT General Language Features

 LT Special Language Features

 LabTalk Script Precedence

3.2 General Language Features

3.2.1 General Language Features
These pages contain information on implementing general features of the LabTalk scripting language.
You will find these types of features in almost every programming language.

This section covers the following topics:

 Data Types and Variables

 Programming Syntax

 Operators

 Conditional and Loop Structures

 Macros

9
 LabTalk Scripting Guide

 Functions

3.2.2 Data Types and Variables

3.2.2.1 LabTalk Data Types

LabTalk supports 9 data types:
Type Comment

Double Double-precision floating-point number

Integer Integers

Constant Numeric data type that value cannot be changed once declared

Dataset Array of numeric values

String Sequences of characters

StringArray Array of strings

Range Refers to a specific region of Origin object (workbook, worksheet, etc.)

Tree Emulates data with a set of branches and leaves

Graphic Object Objects like labels, arrows, lines, and other user-created graphic elements

Numeric

LabTalk supports three numeric data types: double, int, and const.
1. Double: double-precision floating-point number; this is the default variable type in Origin.

2. Integer: integers (int) are stored as double in LabTalk; truncation is performed during

assignment.

3. Constant: constants (const) are a third numeric data type in LabTalk. Once declared, the value

of a constant cannot be changed. From Origin 2016, constant is auto-saved to orgvar.ogs

once declared. It means that the constant will be saved as "System Variable" and available

whenever a new Origin session is conducting.

// Declare a new variable of type double:

double dd = 4.5678;

10
 Language Fundamentals

// Declare a new integer variable:

int vv = 10;
// Declare a new constant:
const em = 0.5772157;
Note:
 For versions before 2016, to use a constant after open a new Origin session, you will need to

define the constant in ORGSYS.CNF.

 LabTalk does not have a complex datatype. A column can be set as Numeric Complex and

basic operations (+,-,*,/) work between columns or using literal values. While functions are

available for extracting real and imaginary parts of a complex column value or literal

expression, you should use Origin C if you need complex variables.

// Direct, literal expression:

(3-13i) / (7+2i) =;
// (3-13i) / (7+2i)=-0.094339622641509-1.8301886792453i
// Assign literal expression to complex column
col(A)[3] = (3-13i) * (7+2i);
// Get Real part of complex column or literal expression
dReal1 = imreal(col(A)[3]);
dReal2 = imreal((3-13i) + (7+2i));
// Get imaginary part of complex column or literal expression
dImag1 = imaginary(col(A)[3]);
dImag2 = imaginary((3-13i) - (7+2i));

Values such as 0.0, NANUM (missing value) and values between -1.0E-290 to 1.0E-
290 will be evaluated to be False in logic statement. For instance, LabTalk command
will return a value 0 (False) instead of 1 (True).
type $(-1e-290?1:0); // Returns 0 (False)
type $(1/0?1:0); // Returns 0 (False), where 1/0 == NANUM

Dataset

The Dataset data type is designed to hold an array of numeric values.

Temporary Loose Dataset

When you declare a dataset variable it is stored internally as a local, temporary loose dataset.
Temporary means it will not be saved with the Origin project; loose means it is not affiliated with a
particular worksheet. Temporary loose datasets are used for computation only, and cannot be used
for plotting.
The following brief example demonstrates the use of this data type (Dataset type declaration and $
Substitution Notation are used in this example):
// Declare a dataset 'aa' with values from 1-10,
// with an increment of 0.2:
dataset aa={1:0.2:10};
// Declare integer 'nSize',// and assign to it the length of the new array:
int nSize = aa.GetSize();

11
 LabTalk Scripting Guide

// Output the number of values in 'aa' to the Script Window:

type "aa has $(nSize) values";

Project Level Loose Dataset

When you create a dataset by vector assignment (without declaration) or by using the Create
(Command) it becomes a project level loose dataset, which can be used for computation or plotting.
Create a project-level loose dataset by assignment,
bb = {10:2:100}
Or by using the Create command:
create %(strWks$) -wdn 10 aa bb;
For more on project-level and local-level variables see the section below on Scope of Variables.
For more on working with Datasets, see Datasets.
For more on working with %( ), see Substitution Notation.

String

LabTalk supports string handling in two ways: string variables and string registers.

String Variables

String variables may be created by declaration and assignment or by assignment alone (depending
on the desired variable scope), and are denoted in LabTalk by a name comprised of continuous
characters (see Naming Rules below) followed by a $-sign (i.e., stringName$):
// Create a string with local/session scope by declaration and assignment

// Creates a string named "greeting",

// and assigns to it the value "Hello":
string greeting$ = "Hello";

// $ termination is optional in declaration, mandatory for assignment

string FirstName, LastName;
FirstName$ = Isaac;
LastName$ = Newton;

// Create a project string by assignment without declaration:

greeting2$ = "World";//project scope and saved with OPJ

// string variable can make use of string class methods

string str$ = Johann Sebastian Bach;
str.Find('Sebastian')=;

// Define literal strings

// The syntax <[< indicates the start of literal strings
// The syntax >]> indicates the end of literal strings
// Can be used to include special symbols like double quotation marks in a
string
string s1$ = <[<a"b'";"c">]>;
s1$=;
//Should return a"b'";"c"

//Use literal strings in X-Function arguments

// Fill in three rows in the current selected worksheet column
patternT text:=<[<"Sample A" "Sample B" "Sample C">]>;
For more information on working with string variables, see the String Processing section.

12
 Language Fundamentals

String Registers

Strings may be stored in String registers, denoted by a leading %-sign followed by a letter of the
alphabet (i.e., %A-%Z). String Registers are always global in scope.
/* Assign to the string register %A the string "Hello World": */
%A = "Hello World";

For current versions of Origin, we encourage the use of string variables for working
with strings, as they are supported by several useful built-in methods; for more, see
String(Object). If, however, you are already using string registers, see String Registers
for complete documentation on their use.

StringArray

The StringArray data type handles arrays of strings in the same way that the Datasets data type
handles arrays of numbers. Like the String data type, StringArray is supported by several built-in
methods; for more, see StringArray (Object).
The following example demonstrates the use of StringArray:
// Declare string array named "aa",
// and use built-in methods Add, and GetSize:
StringArray aa; // aa is an empty string array
aa.Add("Boston"); // aa now has one element: "Boston"
aa.Add("New York"); // aa has a second element: "New York"

/* Prints "aa has 2 strings in it:" then each string. */

type "aa has $(aa.GetSize()) strings in it:";
loop(ii,1,aa.GetSize())
{
ty aa.GetAt(ii)$;
}

Range

The range data type allows functional access to many data-related Origin objects, referring to a
specific region in a workbook, worksheet, graph, layer, or window.
The general syntax is:
range rangeName = [WindowName]LayerNameOrIndex!DataRange[subRange]
which can be made specific to data in a workbook, matrix, or graph:
range rangeName =
[BookName]SheetNameOrIndex!ColumnNameOrIndex[RowBegin:RowEnd]
range rangeName =
[MatrixBookName]MatrixSheetNameOrIndex!MatrixObjectNameOrIndex[CellBegin:CellEnd]
range rangeName =[GraphName]LayerNameOrIndex!DataPlotIndex[RowBegin:RowEnd]
The special syntax [??] is used to create a range variable to access a loose dataset.
For example:
// Access Column 3 on Book1, Sheet2:
range cc = [Book1]Sheet2!Col(3);
// Access second curve on Graph1, layer1:
range ll = [Graph1]Layer1!2;
// Access second matrix object on MBook1, MSheet1:
range mm = [MBook1]MSheet1!2;
// Access loose dataset tmpdata_a:

13
 LabTalk Scripting Guide

range xx = [??]!tmpdata_a;
Notes:
 CellRange can be a single cell, (part of) a row or column, a group of cells, or a non-contiguous

selection of cells.

 Worksheets, Matrix Sheets, and Graph Layers can each be referenced by name or index.

 You can define a range variable to represent an origin object, or use range directly as an X-

Function argument.

 Many more details on the range data type and uses of range variables can be found in the

Range Notation.

Tree

LabTalk supports the standard tree data type, which emulates a tree structure with a set of branches
and leaves. The branches contain leaves, and the leaves contain data. Both branches and leaves are
called nodes.
Leaf: A node that has no children, so it can contain a value
Branch: A node that has child nodes and does not contain a value
A leaf node may contain a variable that is of numeric, string, or dataset (vector) type.
Trees are commonly used in Origin to set and store parameters. For example, when a dataset is
imported into the Origin workspace, a tree called options holds the parameters which determine how
the import is performed.
Specifically, the following commands import ASCII data from a file called "SampleData.dat", and set
values in the options tree to control the way the import is handled. Setting the ImpMode leaf to a
value of 4 tells Origin to import the data to a new worksheet. Setting the NumCols leaf (on the Cols
branch) to a value of 3 tells Origin to only import the first three columns of the SampleData.dat file.
string str$ = system.path.program$ + "Samples\Graphing\Group.dat";
impasc fname:=str$
/* Start with new sheet */
options.ImpMode:=4
/* Only import the first three columns */
options.Cols.NumCols:=3;
Declare a tree variable named aa:
// Declare an empty tree
tree aa;
// Tree nodes are added automatically during assignment:
aa.bb.cc=1;
aa.bb.dd$="some string";

// Declare a new tree 'trb' and assign to it data from tree 'aa':
tree trb = aa;
Check the existence of a tree, and the existence of the leaf and branch on the tree
Tree tr;
exsit(tr)=; //will return 24 if this tree exists; Otherwise, return 0.
tr.a.b=1;
tr.a@=; /// get 2, for branch
tr.a.b@=; /// get 1, for leaf
tr.a.b1@=;/// get 0, not valid

14
 Language Fundamentals

The tree data type is often used in X-Functions as both an input and output data structure. For
example:
// Put import file info into 'trInfo'.
impinfo t:=trInfo;
Tree nodes can be strings. The following example shows how to copy a treenode with string data to
worksheet columns:
//Import the data file into worksheet
newbook;
string fn$=system.path.program$ + "\samples\statistics\automobile.dat";
impasc fname:=fn$;
tree tr;
//Perform statistics on a column and save results to a tree variable
discfreqs irng:=2 rd:=tr;
// Assign strings to worksheet column.
newsheet name:=Result;
col(1) = tr.freqcount1.data1;
col(2) = tr.freqcount1.count1;
Tree nodes can also be vectors. Prior to Origin 8.1 SR1 the only way to access a vector in a Tree
variable was to make a direct assignment, as shown in the example code below:
tree tr;
// If you assign a dataset to a tree node,
// it will be a vector node automatically:
tr.a=data(1,10);
// A vector treenode can be assigned to a column:
col(1)=tr.a;
// A vector treenode can be assigned to a loose dataset, which is
// convenient since a tree node cannot be used for direct calculations
dataset temp=tr.a;
// Perform calculation on the loose dataset:
col(2)=temp*2;
You can access elements of a vector tree node directly, with statements such as:
// Following the example immediately above,
col(3)[1] = tr.a[3];
that assigns the third element of vector tr.a to the first row of column 3 in the current worksheet.
You can also output analysis results to a tree variable, like the example below.
newbook;
//Import the data file into worksheet
string fn$=system.path.program$ + "\samples\Signal
Processing\fftfilter1.dat";
impasc fname:=fn$;
tree mytr;
//Perform FFT and save results to a tree variable
fft1 ix:=col(2) rd:=mytr;
page.active=1;
col(3) = mytr.fft.real;
col(4) = mytr.fft.imag;
More information on trees can be found in the chapter on Origin Projects,Accessing Metadata
section.

Graphic Objects

The new LabTalk variable type GObject allows the control of graphic objects in any book/layer.

15
 LabTalk Scripting Guide

The general syntax is:

GObject name = [GraphPageName]LayerIndex!ObjectName;
GObject name = [GraphPageName]LayerName!ObjectName;
GObject name = LayerName!ObjectName; // active graph
GObject name = LayerIndex!ObjectName; // active graph
GObject name = ObjectName; // active layer
You can declare GObject variables for both existing objects as well as for not-yet created objects.
For example:
GObject myLine = line1;
draw -n myLine -l {1,2,3,4};
win -t plot;
myLine.X+=2;
/* Even though myLine is in a different graph
that is not active, you can still control it! */
For a full description of Graphic Objects and their properties and methods, please see Graphic
Objects.

3.2.2.2 Variables
A variable is simply an instance of a particular data type. Every variable has a name, or identifier,
which is used to assign data to it, or access data from it. The assignment operator is the equal sign
(=), and it is used to simultaneously create a variable (if it does not already exist) and assign a value
to it.

Variable Naming Rules

Variable, dataset, command, and macro names are referred to generally as identifiers. When
assigning identifiers in LabTalk:
 Use any combination of letters and numbers, but note that:

o the identifier cannot be more than 25 characters in length.

o the first character cannot be a number.

o the underscore character "_" has a special meaning in dataset names and should be

avoided.

 Use the Exist (Function) to check if an identifier is being used to name a window, macro, tool,

dataset, or variable.

 Note that several common identifiers are reserved for system use by Origin, please see System

Variables for a complete list.

Handling Variable Name Conflicts

The @ppv system variable controls how Origin handles naming conflicts between project, session,
and local variables. Like all system variables, @ppv can be changed from script anytime and takes
immediate effect.
Variable Description

16
 Language Fundamentals

This is the DEFAULT option and allows both session variables and local variables to
@ppv=0 use existing project variable names. In the event of a conflict, session or local
variables are used.

This option makes declaring a session variable with the same name as an existing
project variable illegal. Upon loading a new project, session variables with a name
@ppv=1
conflict will be disabled until the project is closed or the project variable with the
same name is deleted.

This option makes declaring a local variable with the same name as an existing
project variable illegal. Upon loading of new project, local variables with a name
@ppv=2
conflict will be disabled until the project is closed or the project variable with the
same name is deleted.

This is the combination of @ppv=1 and @ppv=2. In this case, all session and local
@ppv=3 variables will not be allowed to use project variable names. If a new project is
loaded, existing session or local variables of the same name will be disabled.

Listing and Deleting Variables

Use the LabTalk commands list and del for listing variables and deleting variables, respectively.
/* Use the LabTalk command "list" with various options to list
variables; the list will print in the Script Window by default: */

list a; // List all the session variables

list v; // List all project and session variables
list vs; // List all project and session string variables
list vt; // List all project and session tree variables

// Use the LabTalk command "del" to delete variables:

del -al <variableName>; // Delete specific local or session variable

del -al *; // Delete all the local and session variables

// There is also a viewer for LabTalk variables:

// "ed" command can also open the viewer
list; // Open the LabTalk Variables Viewer
Please see the List (Command), and Del (Command) (in Language Reference: Command
Reference) for all listing and deleting options.
If no options are specified, running either the List or Edit command will open the LabTalk Variables
and Functions dialog and list all variables and functions.

3.2.2.3 Scope of Variables

The way a variable is declared determines its scope. Variables created without declaration (only
allowed for types double, string, and dataset) become Project variables and are saved with the
Origin Project file. Declared variables become Session or Local variables. Scope in LabTalk consists
of three (nested) levels of visibility:
 Project variables

 Session variables

 Local variables

17
 LabTalk Scripting Guide

In practical terms this means that (a) you can have multiple variables of the same name and (b) when
that is the case, the value returned at any given time is dependent upon the current scope (see
Session and Local variables, below).

Project Variables

 Project variables are saved with the Origin Project (*.OPJ). Project variables are said to have

Project scope.

 Project variables are automatically created without declaration for variables of type double,

string, and dataset as in:

// Define a project (project scope) variable of type double:

myvar = 3.5;
// Define a loose dataset (project scope):
temp = {1,2,3,4,5};
// Define a project (project scope) variable of type string:
str$ = "Hello";

 All other variable types must be declared, which makes their default scope either Session or

Local. Note that you can make Local variables available as Session variables, using the @glob

system variable, as described below.

Session Variables

 Session variables are not saved with the Origin Project, and are available in the current Origin

session across projects. Thus, once a Session variable has been defined, they exist until the

Origin application is terminated or the variable is deleted. Session variables are defined with

variable declarations:

// Defines a variable of type double:

double var1 = 4.5;
// Define loose dataset:
dataset mytemp = {1,2,3,4,5};
You can have a Project variable and a Session variable of the same name. In such cases, the
Session variable takes precedence:
aa = 10;
type "First, aa is a project variable equal to $(aa)";
double aa = 20;
type "Then aa is a session variable equal to $(aa)";
del -al aa;
type "Now aa is project variable equal to $(aa)";
And the output is:

18
 Language Fundamentals

First, aa is a project variable equal to 10

Then aa is a session variable equal to 20
Now aa is project variable equal to 10

Local Variables

Local variables exist only within the current scope of a particular script.
Script-level scope exists for scripts:
 enclosed in curly braces {},

 in separate *.OGS files or individual sections of *.OGS files,

 inside the Set Column/Matrix Values Dialog, or

 behind a custom button (Button Script).

Local variables are declared and assigned values in the same way as Session variables:
loop(i,1,10){
double a = 3.5;
const e = 2.718;
// some other lines of script...
}
// "a" and "e" exist only inside the code enclosed by {}
It is possible to have Local variables with the same name as Session variables or Project variables. In
this case, the Local variable takes precedence over the Session or Project variable of the same
name, within the scope of the script. For example, if you run the following script (Please refer to Run
LabTalk Script From Files for details on how to run such script):
[Main]
double aa = 10;
type "In the main section, aa equals $(aa)";
run.section(, section1);
run.section(, section2);

[section1]
double aa = 20;
type "In section1, aa equals $(aa)";

[section2]
// This section does not declare a local variable named 'aa'.
// A variable named 'aa' will be searched for in the following order:
// If a Session variable named 'aa' exists then it will be used.
// Else if a Project variable named 'aa' exists then it will be used.
// Else if this section is called from another section and the caller
// section declared a local variable named 'aa' then it will be used.
// Else 'aa' will be a missing value.
type "In section2, aa equals $(aa)";
Origin will output:
In the main section, aa equals 10
In section1, aa equals 20
In section2, aa equals 10

Making Local Variables and Functions Available in the Session

19
 LabTalk Scripting Guide

At times you may want to define variables or functions in a *.OGS file, but then be able to use them
from the Script Window, in a text label, etc. (normally, the Local variable or function ceases to exist
when the OGS runs to completion). To do so, set the value of the @glob system variable to 1
(default value is 0). This makes Local variables and functions in the OGS file available in the Session:
[Main]
@glob = 1;
// the following declarations become available in the session
range a = 1, b= 2;
if(a[2] > 0)
{
// begin a local scope
range c = 3; // this declaration is still available in the session
}
Upon exiting the *.OGS, the @glob variable is automatically restored to its default value, 0.
Note that one can also control a block of code by placing @glob at the beginning and end, as in:
@glob=1;
double alpha=1.2;
double beta=2.3;
Function double myPeak(double x, double x0)
{
double y = 10*exp(-(x-x0)^2/4);
return y;
}
@glob=0;
double gamma=3.45;
In the above script, variables alpha, beta, and the user-defined function myPeak will be available in
the session. The variable gamma will not be available because it was declared after @glob was
returned to its default value of 0.

Summary Table: Scope of Variables

Data Declared
Where Defined Example Lifetime
Type ?

 Script Window

 Command

Window
While Origin runs.
const av =
Constan consta Yes All constants are
 OGS File 6.022×10
2
t nt (const) 3 saved in
;
orgvar.ogs.
 Various GUI

dialogs

 Script Window While the OPJ is

double, av =
Project 2 open.
string, No 6.022×10
Variable  Command 3 Saved with the
dataset ;
OPJ.

20
 Language Fundamentals

Window

 OGS File

 Various GUI

dialogs

 Script Window
double av While the session
 Command
Session all = runs.
Yes 2
Variable types 6.022×10 NOT saved with
Window 3
; the OPJ.

 OGS file
double av
 Various GUI
Local all = While the script
Yes 2
Variable types 6.022×10 runs.
dialogs 3
;

 OGS file
While the session
Local @glob=1;
runs.
Variable  Various GUI double av
all Can be saved with
as Yes =
types 2 the OPJ (see
Session dialogs 6.022×10
3 ProjectEvents.OG
Variable ;
S).

3.2.3 Programming Syntax

3.2.3.1 Programming Syntax
A LabTalk script is a single block of code that is received by the LabTalk interpreter. A LabTalk script
is composed of one or more complete programming statements, each of which performs an action.
Each statement in a script should end with a semicolon, which separates it from other statements.
However, single statements typed into the Script window for execution should not end with a
semicolon.
Each statement in a script is composed of words. Words are any group of text separated by white
space. Text enclosed in parentheses is treated as a single word, regardless of white space. For
example:
type This is a statement; // Single LabTalk statement

ty s1; ty s2; ty s3; // Three statements

Parentheses are used to create long words containing white space. For example, in the script:
menu 3 (Long Menu Name);

21
 LabTalk Scripting Guide

the open parenthesis signifies the beginning of a single word, and the close parenthesis signifies the
end of the word.

This section covers the following topics:

 Statement Types

 Using Semicolons in LabTalk

 Extending a Statement over Multiple Lines

 Comments

 Order of Evaluation in Statements

3.2.3.2 Statement Types

Statement Types

LabTalk supports five types of statements:

 Assignment Statements

 Macro Statements

 Command Statements

 Arithmetic Statement

 Function Statements

Assignment Statements

The assignment statement takes the general form:

LHS = expression ;
expression (RHS, right-hand side) is evaluated and put into LHS (left-hand side). If LHS does not
exist, it is created if possible, otherwise an error will be reported.
When a new data object is created with an assignment statement, the object created is:
 A string variable if LHS ends with a $ as in stringVar$ = "Hello."

 A numeric variable if expression evaluates to a scalar.

 A dataset if expression evaluates to a range.

When new values are assigned to an existing data object, the following conventions apply:
 If LHS is a dataset and expression is a scalar, every value in LHS is set equal to expression.

22
 Language Fundamentals

 If LHS is a numeric variable, then expression must evaluate into a scalar. If expression

evaludate into a dataset, LHS retrieves the first element of the dataset.

 If both LHS and expression represent datasets, each value in LHS is set equal to the

corresponding value in expression.

 If LHS is a string, then expression is assumed to be a string expression.

 If the LHS is the object.property notation, with or without $ at the end, then this notation is

used to set object properties, such as the number of columns in a worksheet, like wks.ncols=3;

Examples of Assignment Statements

Assign the variable B equal to 2.
B = 2;
Assign Test equal to B raised to the third power.
Test = B^3;
Assign %A equal to Austin TX.
%A = Austin TX;
Assign every value in Book1_B to 4.
Book1_B = 4;
Assign each value in Book2_B to the corresponding position in Book1_B.
Book1_B = Book2_B;
Sets the row heading width for the Book1 worksheet to 100, using the worksheet object's rhw
property. The doc -uw command refreshes the window.
Book1!wks.rhw = 100; doc -uw;
The calculation is carried out for the values at the corresponding index numbers in more and
yetmore. The result is put into myData at the same index number.
myData = 3 * more + yetmore;
Note: If a string register to the left of the assignment operator is enclosed in parentheses, the string
register is substitution processed before assignment. For example:
%B = DataSet;
(%B) = 2 * %B;
The values in DataSet are multiplied by 2 and put back into DataSet. %B still holds the string
"DataSet".
Similar to string registers, the assignment statement is also used for string variables, like:
fname$=fdlg.path$+"test.csv";
In this case, the expression is a string expression which can be string literals, string variables, or a
concatenation of multiple strings with the + character.

Macro Statements

Macros provide a way to alias a script, that is, to associate a given script with a specific name. This
name can then be used as a command that invokes the script.
For more information on macros, see Macros

Command Statements

The third statement type is the command statement. LabTalk offers commands to control or modify
most program functions.
Each command statement begins with the command itself, which is a unique identifier that can be
abbreviated to as little as two letters (as long as the abbreviation remains unique, which is true in
most cases). Most commands can take options (also known as switches), which are single letters that

23
 LabTalk Scripting Guide

modify the operation of the command. Options are always preceded by the dash "-" character.
Commands can also take arguments. Arguments are either a script or a data object. In many cases,
options can also take their own arguments.
Command statements take the general form:
command [option] [argument(s)];
The brackets [] indicate that the enclosed component is optional; not all commands take both options
and arguments. The brackets are not typed with the command statement (they merely denote an
optional component).
Methods (Object) are another form of command statement. They execute immediate actions relating
to the named object. Object method statements use the following syntax:
ObjectName.Method([options]);
For example:
The following script adds a column named new to the active worksheet and refreshes the window:
wks.addcol(new);
doc -uw;
The following examples illustrate different forms of command statements:
Integrate the dataset myData from zero.
integ myData;
Adding the -r option and its argument, baseline, causes myData to be integrated from a reference
curve named baseline.
integ -r baseline myData;
The repeat command takes two arguments to execute:
1. the number of times to execute, and

2. a script, which indicates the instruction to repeat.

This command statement prints "Hello World" in a dialog box three times.
repeat 3 {type -b "Hello World"}

Arithmetic Statement

The arithmetic statement takes the general form:

dataObject1 operator dataObject2;
where
 dataObject1 is a dataset or a numeric variable.

 dataObject2 is a dataset, variable, or a constant.

 operator can be +, -, *, /, or ^.

The result of the calculation is put into dataObject1. Note that dataObject1 cannot be a function. For
example, col(3) + 25 is an illegal usage of this statement form.
The following examples illustrate different forms of arithmetic statements:
If myData is a dataset, this divides each value in myData by 10.
myData / 10;
Subtract otherData from myData, and put the result into myData. Both datasets must be Y or Z
datasets (see Note).
myData - otherData;
If A is a variable, increment A by 1. If A is a dataset, increment each value in A by 1.
A + 1;

24
 Language Fundamentals

Note: There is a difference between using datasets in arithmetic statements versus using datasets in
assignment statements. For example, data1_b + data2_b is computed quite differently from data1_b
= data1_b + data2_b. The latter case yields the true point-by-point sum without regard to the two
datasets' respective X-values. The former statement, data1_b + data2_b, adds the two data sets as
if each were a curve in the XY-plane. If therefore, data1_b and data2_b have different associated X-
values, one of the two series will require interpolation. In this event, Origin interpolates based on the
first dataset's (data1_b in this case) X-values.

Function Statements

The function statement begins with the characteristics of a function -- an identifier -- followed by a
quantity, enclosed by parentheses, upon which the function acts.
An example of a function statement is:
sum(dataset);
For more on functions in LabTalk, see Functions.

3.2.3.3 Using Semicolons in LabTalk

Separate Statements with a Semicolon

Like the C programming language, LabTalk uses semicolons to separate statements. In general,
every statement should end with a semicolon. However, the following rules clarify semicolon usage:
 Do not use a semicolon when executing a single statement script in the Script window.

o An example of the proper syntax is: type "hello" (ENTER).

o The interpreter automatically places a semicolon after the statement to indicate that it

has been executed.

 Statements ending with { } block can skip the semicolon.

 The last statement in a { } block can also skip the semicolon.

In the following example, please note the differences between the three type command:
if (m>2) {type "hello";} else {type "goodbye"}
type "the end";
The above can also be written as:
if (m>2) {type "hello"} else {type "goodbye"}
type "the end";
or
if (m>2) {type "hello"} else {type "goodbye"};
type "the end";

Leading Semicolon for Delayed Execution

You can place a ';' in front of a script to delay its execution. This is often needed when you need to
run a script inside a button that will delete the button itself, like to issue window closing or new project
commands. For example, placing the following script inside a button will possibly lead to a crash
// button to close this window
type "closing this window";
win -cn %H;

25
 LabTalk Scripting Guide

To fix this, the script should be written as

// button to close this window
type "closing this window";
;win -cn %H;
The leading ';' will place all scripts following it to be delayed when executed. Sometimes you may
want a specific group of statements delayed, then you can put them inside {script} with a leading ';',
for example:
// button to close this window
type "closing this window";
;{type "from delayed execution";win -cn %H;}
type "actual window closing code will be executed after this";

3.2.3.4 Extending a Statement over Multiple Lines

There are times when, for the sake of readability, you want to extend a single statement over more
than one line. One way to do this is with braces {}. When an "open brace", {, is encountered in a
script file, Origin searches for a "closed brace" , }, and executes the entire block of text as one
statement. For example, the following macro statement:
def openDialog {layer -s 1; axis x;};
can also be written:
def openDialog {
layer -s 1;
axis x;
};
Both scripts are executed as a single statement, even though the second statement spans multiple
lines.
Note: There is a limit to the length of script that can be included between a set of braces {}. The
scripts between the {} are translated internally and the translated scripts must be less than 1140
bytes (after substitution). In place of long blocks of LabTalk code, programmers can use LabTalk
macros or the run.section() and run.file() object methods. To learn more, see Passing Arguments.

3.2.3.5 Comments
LabTalk script accepts two comment formats:
Use the "//" character to ignore all text from // to the end of the line. For example:
type "Hello World"; //Place comment text here.
Use the combination of "/*" and "*/" character pairs to begin and end, respectively, any block of code
or text that you do not want executed. For example:
type Hello /* Place comment text here,
or a line of code:
and even more ... */
World;
Note: Use the "#!" characters to begin debugging lines of script. The lines are only executed if
system.debug = 1.

3.2.3.6 Order of Evaluation in Statements

When a script is executed, it is sent to the LabTalk interpreter and evaluated as follows:
The script is broken down into its component statements
Statements are identified by type using the following recognition order: assignment, macro,
command, arithmetic, and function. The interpreter first looks for an exposed (not hidden in
parentheses or quotation marks) assignment operator. If none is found, it looks to see if the first word
is a macro name. It then checks if the first word is a command name. The interpreter then looks for
an arithmetic operation, and finally, the interpreter checks whether the statement is a function.

26
 Language Fundamentals

The recognition order can have significant effect on script functions. For example, the following
assignment statement:
type = 1;
assigns the value 1 to the variable type. This occurs even though type is (also) a LabTalk command,
since assignments come before commands in recognition order. However, since commands precede
arithmetic expressions in recognition order, in the following statement:
type + 1;
the command is carried out first, and the string, + 1, prints out.
The statements are executed in the order received, using the following evaluation priority
 Assignment statements: String variables to the left of the assignment operator are not

expressed unless enclosed by parentheses. Otherwise, all string variables are expressed, and

all special notation ( %() and $()) is substitution processed.

 Macro statements: Macro arguments are substitution processed and passed.

 Command statements: If a command is a raw string, it is not sent to the substitution processor.

Otherwise, all special notation is substitution processed.

 Arithmetic statements: All expressions are substitution processed and expressed.

3.2.4 Operators
3.2.4.1 Introduction
LabTalk supports assignment, arithmetic, logical, relational, and conditional operators:
Arithmetic Operators + - * / ^ & |

String Concatenation +

Assignment Operators = += -= *= /= ^=

Logical and Relational Operators > >= < <= == != && ||

Conditional Operator ?:
These operations can be performed on scalars and in many cases they can also be performed on
vectors (datasets). Origin also provides a variety of built-in numeric, trigonometric, and statistical
functions which can act on datasets.
When evaluating an expression, Origin observes the following precedence rules:
1. Exposed assignment operators (not within brackets) are evaluated.

2. Operations within brackets are evaluated before those outside brackets.

3. Multiplication and division are performed before addition and subtraction.

4. The (>, >=, <, <=) relational operators are evaluated, then the (== and !=) operators.

5. The logical operators || is prior to &&.

6. Conditional expressions (?:) are evaluated.

27
 LabTalk Scripting Guide

3.2.4.2 Arithmetic Operators

Origin recognizes the following arithmetic operators:
Operator Use

+ Addition

- Subtraction

* Multiplication

/ Division

^ Exponentiate (X^Y raises X to the Yth power) (see note below)

& Bitwise And operator. Acts on the binary bits of a number.

| Bitwise Or operator. Acts on the binary bits of a number.

Note: For 0 raised to the power n (0^n), if n > 0, 0 is returned. If n < 0, a missing value is returned. If
n = 0, then 1 is returned (if @ZZ = 1) or a missing value is returned (if @ZZ = 0).
These operations can be performed on scalars and on vectors (datasets). For more information on
scalar and vector calculations, see Performing Calculations below.
The following example illustrates the use of the exponentiate operator: Enter the following script in
the Command window:
1.3 ^ 4.7 =
After pressing ENTER, 3.43189 is printed in the Command window. The next example illustrates the
use of the bitwise and operator. Enter the following script in the Command window:
if (27&41 == 9)
{type "Yes!"}
After pressing ENTER, Yes! is displayed in the Command window.
Note: 27&41 == 9 because
27 = 0000000000011011
41 = 0000000000101001
with bitwise & yields:
0000000000001001 (which is equal to 9)
Note: Multiplication must be explicitly included in an expression. For example, 2*X must be used
instead of 2X to indicate the multiplication of the variable X by the constant 2.

Define a constant

We can also define global constants in the ORGSYS.CNF file:

const pi = 3.141592653589793

A Note about Logarithmic Conversion

 To convert a dataset to a logarithmic scale, use the following syntax:

col(c) = log(col(c));

 To convert a dataset back to a linear scale, use the following syntax:

28
 Language Fundamentals

col(c) = 10^(col(c));

3.2.4.3 String Concatenation

Very often you need to concatenate two or more strings of either the string variable or string register
type. All of the code segments in this section return the string "Hello World."
The string concatenation operator is the plus-sign (+), and can be used to concatenate two strings:
aa$ ="Hello";
bb$="World";
cc$=aa$+" "+bb$;
cc$=;
To concatenate two string registers, you can simply place them together:
%J="Hello";
%k="World";
%L=%J %k;
%L=;
If you need to work with both a string variable and a string register, follow these examples utilizing %(
) substitution:
aa$ ="Hello";
%K="World";
dd$=%(aa$) %K;
dd$=;
dd$=%K;
dd$=aa$+" "+dd$;
dd$=;
%M=%(aa$) %K;
%M=;

3.2.4.4 Assignment Operators

Origin recognizes the following assignment operators:
Operator Use

= Simple assignment.

+= Addition assignment.

-= Subtraction assignment.

*= Multiplication assignment.

/= Division assignment.

^= Exponential assignment.
These operations can be performed on scalars and on vectors (datasets). For more information on
scalar and vector calculations, see Performing Calculations in this topic.
The following example illustrates the use of the -= operator.
In this example, 5 is subtracted from the value of A and the result is assigned to A:
A -= 5;
In the next example, each value in Data1_B is divided by the corresponding value in Book1_A, and
the resulting values are assigned to Book1_B.
Book1_B /= Book1_A;

29
 LabTalk Scripting Guide

In addition to these assignment operators, LabTalk also supports the increment and decrement
operators for scalar calculations (not vector).
Operator Use

++ Add 1 to the variable contents and assign to the variable.

-- Subtract 1 from the variable contents and assign to the variable.

The following for loop expression illustrates a common use of the increment operator ++. The script
prints the data stored in the second column of the current worksheet to the Command window:
for (ii = 1; ii <= wks.maxrows; ii++)
{type ($(col(2)[ii])); }

3.2.4.5 Logical and Relational Operators

Origin recognizes the following logical and relational operators:
Operator Use

> Greater than

>= Greater than or equal to

< Less than

<= Less than or equal to

== Equal to

!= Not equal to

&& And

|| Or
An expression involving logical or relational operators evaluates to either true (non-zero) or false
(zero). Logical operators are almost always found in the context of Conditional and Loop Structures.

Numeric Comparison

The most common comparison is between two numeric values. Generally, at least one is a variable.
For instance:
if aa<3 type "aa<3";
Or, both items being compared can be variables:
if aa<=bb type "aa<=bb";
It is also possible, using parentheses, to make multiple comparisons in the same logical statement:
if (aa<3 && aa<bb) type "aa is lower";

String Comparison

You can use the == and != operators to compare two strings. String comparison (rather than numeric
comparison) is indicated by open and close double quotations (" ") either before, or after, the
operator. The following script determines if the %A string is empty:

30
 Language Fundamentals

if (%A == ""){type "empty"};

The following examples illustrates the use of the == operator:
x = 1; // variable x is set to 1
%a = x; // string a is set to "x"
if (%a == 1);
type "yes";
else
type "no";
The result will be yes, because Origin looks for the value of %a (the value of x), which is 1. In the
following script:
x = 1; // variable x is set to 1
%a = x; // string a is set to "x"
if ("%a" == 1)
type "yes";
else
type "no";
The result will be no, because Origin finds the quotation marks around %a, and therefore treats it as
a string, which has a character x, rather than the value 1.

3.2.4.6 Conditional Operator (?:)

The ternary operator or conditional operator (?:) can be used in the form:
Expression1 ? Expression2 : Expression3
This expression first evaluates Expression1. If Expression1 is true (non-zero), Expression2 is
evaluated. The value of Expression2 becomes the value for the conditional expression. If
Expression1 is false (zero), then Expression3 is evaluated and Expression3 becomes the value for
the entire conditional expression. Note that Expressions1 and Expressions2 can themselves be
conditional operators. The following example assigns the value which is greater (m or n), to variable:
m = 2;
n = 3;
variable = (m>n?m:n);
variable =
LabTalk returns: variable = 3
In this example, the script replaces all column A values between 5.5 and 5.9 with 5.6:
col(A) = col(A)>5.5&&col(A)<5.9?5.6:col(A);
Note: A Threshold Replace function treplace(dataset, value1, value2 [, condition]) is also available for
reviewing values in a dataset and replacing them with other values based on a condition. In the
treplace(dataset, value1, value2 [, condition]) function, each value in the dataset is compared to
value1 according to the condition. When the comparison is true, the value may be replaced with
Value2 or -Value2 depending on the value of condition. When the comparison is false, the value is
retained or replaced with a missing value depending on the value of condition. The treplace() function
is much faster than the ternary operator.

3.2.4.7 Performing Calculations

You can use LabTalk to perform both
 scalar calculations (mathematical operations on a single variable), and

 vector calculations (mathematical operations on entire datasets).

Scalar Calculations

31
 LabTalk Scripting Guide

You can use LabTalk to express a calculation and store the result in a numeric variable. For example,
consider the following script:
inputVal = 21;
myResult = 4 * 32 * inputVal;
The second line of this example performs a calculation and creates the variable, myResult. The value
of the calculation is stored in myResult.
When a variable is used as an operand, and will store a result, shorthand notation can be used. For
example, the following script:
B = B * 3;
could also be written:
B *= 3;
In this example, multiplication is performed with the result assigned to the variable B. Similarly, you
can use +=, -=, /=, and ^=. Using shorthand notation produces script that executes faster.

Vector Calculations

In addition to performing calculations and storing the result in a variable (scalar calculation), you can
use LabTalk to perform calculations on entire datasets as well.
Vector calculations can be performed in one of two ways: (1) strictly row-by-row, or (2) using linear
interpolation.

Row-by-Row Calculations

Vector calculations are always performed row-by-row when you use the two general notations:
datasetB = scalarOrConstant <operator> datasetA;
datasetC = datasetA <operator> datasetB;
This is the case even if the datasets have a different numbers of elements. Suppose there are three
empty columns in your worksheet: A, B, and C. Run the following script:
col(a) = {1, 2, 3};
col(b) = {4, 5};
col(c) = col(a) + col(b);
The result in column C will be {5, 7, --}. That is, Origin outputs a missing value for rows in which one
or both datasets do not contain a value.
Vector calculations can also involve a scalar. In the above example, type:
col(c) = 2 * col(a);
Column A is multiplied by 2 and the results are put into the corresponding rows of column C.
Instead, execute the following script (assuming newData does not previously exist):
newData = 3 * Book1_A;
A temporary dataset called newData is created and assigned the result of the vector operation.

Calculations Using Interpolation

Origin supports interpolation through range notation and X-Functions such as interp1 and interp1xy.
Please refer to Interpolation for more details.

3.2.5 Conditional and Loop Structures

The structure of the LabTalk language is similar to C. LabTalk supports:
 Loops, which allow the program to repetitively perform a set of actions.

 Decision structures, which allow the program to perform different sets of actions depending on

the circumstances.

32
 Language Fundamentals

3.2.5.1 Loop Structures

All LabTalk loops take a script as an argument. These scripts are executed repetitively under
specified circumstances. LabTalk provides four loop commands:
Command Syntax

repeat repeat value {script};

loop loop (variable, startVal, endVal) {script};

doc -e doc -e object {script};

for for (expression1; expression2; expression3) {script};

The LabTalk for-loop is similar to the for loop in other languages. The repeat, loop, and doc -e loops
are less familiar, but are easy to use.

Repeat

The repeat loop is used when a set of actions must be repeated without any alterations.
Syntax: repeat value {script};
Execute script the number of times specified by value, or until an error occurs, or until the break
command is executed.
For example, the following script types the string three times:
repeat 3 { type "line of output"; };

Loop

The loop loop is used when a single variable is being incremented with each successive loop.
Syntax: loop (variable, startVal, endVal) {script};
A simple increment loop structure. Initializes variable with the value of starVal. Executes script.
Increments variable and tests if it is greater than endVal. If it is not, executes script and continues to
loop.
For example, the following script outputs numbers from 1 to 4:
loop (ii, 1, 4) {type "$(ii)";};
Note: The loop command provides faster looping through a block of script than does the for
command. The enhanced speed is a result of not having to parse out a LabTalk expression for the
condition required to stop the loop.
Doc -e
The doc -e loop is used when a script is being executed to affect objects of a specific type, such as
graph windows. The doc -e loop tells Origin to execute the script for each instance of the specified
object type.
Syntax: doc -e object {script};
The different object types are listed in the document command.
For example, the following script prints the windows title of all graph windows in the project:
doc -e P {%H=}

For

The for loop is used for all other situations.

Syntax: for (expression1; expression2; expression3) {script};
In the for statement, expression1 is evaluated. This specifies initialization for the loop. Second,
expression2 is evaluated and if true (non-zero), the script is executed. Third, expression3, often
incrementing of a counter, is executed. The process repeats at the second step. The loop terminates

33
 LabTalk Scripting Guide

when expression2 is found to be false (zero). Any expression can consist of multiple statements,
each separated by a comma.
For example, the following script output numbers from 1 to 4:
for(ii=1; ii<=4; ii++)
{
type "$(ii)";
}
Note: The loop command provides faster looping through a block of script.

3.2.5.2 Decision Structures

Decision structures allow the program to perform different sets of actions depending on the
circumstances. LabTalk provides three decision-making structures: if, if-else, and switch.
 The if command is used when a script should be executed in a particular situation.

 The if-else command is used when one script must be executed if a condition is true (non-

zero), while another script is executed if the condition is false (zero).

 The switch command is used when more than two possibilities are included in a script.

If, If-Else

Syntax:
1. if (testCondition) sentence1; [else sentence2;]

2. if (testCondition) {script1} [else {script2}]

Evaluate testCondition and if true, execute script1. Expressions without conditional operators are
considered true if the result of the expression is non-zero.
If the optional else is present and testCondition is false (zero), then execute script2. There should be
a space after the else. Strings should be quoted and string comparisons are not case sensitive.
Single statement script arguments should end with a semicolon. Multiple statement script arguments
must be surrounded by braces {}. Each statement within the braces should end with a semicolon. It is
not necessary to follow the final brace of a script with a semicolon.
For example, the following script opens a message box displaying "Yes!":
%M = test;
if (%M == "TEST") type -b "Yes!";
else type -b "No!";
The next script finds the first point in column A that is greater than -1.95:
newbook;
col(1)=data(-2,2,0.01);
val = -1.95;
get col(A) -e numpoints;
for(ii = 1 ; ii <= numpoints ; ii++)
{
// This will terminate the loop early if true
if (Col(A)[ii] > val) break;
}
if(ii > numpoints - 1)
ty -b No number exceeds $(val);
else
type -b The index number of first value > $(val) is $(ii)

34
 Language Fundamentals

The value is $(col(a)[ii]);

It is possible to test more than one condition with a single if statement, for instance:
if(a>1 && a<3) b+=1; // If true, increment b by 1
The && (logical And) operator is one of several logical operators supported in LabTalk.

Switch

The switch command is used when more than two possibilities are included in a script. For example,
the following script returns b:
ii=2;
switch (ii)
{
case 1:
type "a";
break;
case 2:
type "b";
break;
case 3:
type "c";
break;
default:
type "none";
break;
}

Break and Progress Bars

LabTalk provides a break command. When executed, this causes an exit from the loop and,
optionally, the script. This is often used with a decision structure inside a loop. It is used to protect
against conditions which would invalidate the loop test conditions. The break command can be used
to display a progress status dialog box (progress bar) to show the current progress through the loop.

Exit

The exit command prompts an exit from Origin unless a flag is previously set to prevent the exit.

Continue

The continue command can be used within loops. When executed, the remainder of the loop is
ignored and the interpreter jumps to the next iteration of the loop. This is often used with a decision
structure inside a loop and can exclude illegal values from being processed by the loop script.
For example, in the following for loop, continue skips the type statement when ii is less than zero.
for (ii = -10; ii <= 10; ii += 2)
{
if (ii < 0)
continue;

type "$(sqrt(ii))";
}

3.2.5.3 Sections in a Script File

35
 LabTalk Scripting Guide

In addition to entering the script in the Label Control dialog, you can also save it as an Origin Script
(OGS) file. An Origin script file is an ASCII text file which consists of a series of one or more LabTalk
statements. Often, you can divide the statements into sections. A section is declared by a section
name surrounded by square brackets on its own line of text:
[SectionName]
Scripts under a section declaration belong to that section until another section declaration is met. A
framework for a script with sections will look like the following:
...
Scripts;
...
[Section 1]
...
Scripts;
...
[Section 2]
...
Scripts;
...
Scripts will be run in sequence until a new section flag is encountered, a return statement is executed
or an error occurs. To run a script in sections, you should use the
run.section(FileName, SectionName)
command. When filename is not included, the current running script file is assumed, for example:
run.section(, Init)
The following script illustrates how to call sections in an OGS file:
type "Hello, we will run section 2";
run.section(, section2);

[section1]
type "This is section 1, End the script.";

[section2]
type "This is section 2, run section 1.";
run.section(, section1);
To run the script, you can save it to your Origin user folder as test.ogs, and type the following in the
command window:
run.section(test);
If code in a section could cause an error condition which would prematurely terminate a section, you
can use a variable to test for that case, as in:
[Test]
SectionPassed = 0;
// Here is where code that could fail can be run
...
SectionPassed = 1;
If the code failed, then SectionPassed will still have a value of 0. If the code succeeded, then
SectionPassed will have a value of 1.

3.2.6 Macros
3.2.6.1 Definition of the Macros
The command syntax,
define macroName {script}

36
 Language Fundamentals

defines a macro called macroName, and associates it with the given script. MacroName can then be
used like a command, and invokes the given script.
For example, the following script defines a macro that uses a loop to print a text string three times.
def hello
{
loop (ii, 1, 3)
{ type "$(ii). Hello World"; }
};
Once the hello macro is defined, typing the word hello in the Script window results in the printout:
1. Hello World
2. Hello World
3. Hello World
Once a macro is defined, you can also see the script associated with it by typing
define macroName;

3.2.6.2 Passing Arguments to Macros

Macros can take up to five arguments. The %1-%5 syntax is used within the macro to access the
value of each argument. A macro can accept a number, string, variable, dataset, function, or script as
an argument. Passing arguments to a macro is similar to passing arguments to a script.
If arguments are passed to a macro, the macro can report the number of arguments using the
macro.nArg object property.
For example, the following script defines a macro named myDouble that expects a single numeric
argument. The given argument is then multiplied by 2, and the result is printed.
def myDouble { type "$(%1 * 2)"; };
If you define this macro and then type the following in the Script window:
myDouble 5
Origin outputs the result to the Script Window:
10
You could modify this macro to take two arguments:
def myDouble { type "$(%1 * %2)"; };
Now, if you type the following in the Script window:
myDouble 5 4
Origin outputs:
20

3.2.6.3 Macro Property

The macro object contains one property which stores the number of arguments passed to the macro.
Property Access Description

Read only, This property stores the number of arguments passed to

Macro.nArg
numeric the macro.
For example:
The following script defines a macro called TypeArgs. If three arguments are passed to the TypeArgs
macro, the macro types the three arguments to the Script window.
Def TypeArgs
{
if (macro.narg != 3)
{
type "Error! You must pass 3 arguments!";

37
 LabTalk Scripting Guide

}
else
{
type "The first argument passed was %1.";
type "The second argument passed was %2.";
type "The third argument passed was %3.";
}
};
If you define the TypeArgs macro as in the example, and then type the following in the Script window:
TypeArgs One;
Origin returns the following to the Script window:
Error! You must pass 3 arguments!
If you define the TypeArgs macro as in the example, and then type the following in the Script window:
TypeArgs One (This is argument Two) Three;
Origin returns the following to the Script window:
The first argument passed was One.
The second argument passed was This is argument Two.
The third argument passed was Three.

3.2.7 Functions
Functions are the core of almost every programming language; the following introduces function
syntax and use in LabTalk.

3.2.7.1 Built-In Functions

LabTalk supports many operations through built-in functions, a listing and description of each can be
found in Function Reference. Functions are called with the following syntax:
outputVariable = FunctionName(Arg1, Arg2, ..., Arg N);
Below are a few examples of built-in functions in use.
The Count (Function) returns an integer count of the number of elements in a vector.
// Return the number of elements in Column A of the active worksheet:
int cc = count(col(A));
The Ave (Function) performs a group average on a dataset, returning the result as a range variable.
range ra = [Book1]Sheet1!Col(A);
range rb = [Book1]Sheet1!Col(B);
// Return the group-averaged values:
rb = ave(ra, 5); // 5 = group size
The Sin (Function) returns the sine of the input angle as type double (the units of the input angle are
determined by the value of system.math.angularunits):
system.math.angularunits=1; // 1 = input in degrees
double dd = sin(45); // ANS: DD = 0.7071

3.2.7.2 User-Defined Functions

Support for multi-argument user-defined functions has been supported in LabTalk since Origin 8.1.
The syntax for user-defined functions is:
function dataType funcName(Arg1, Arg2, ..., ArgN) {script;}
Minimum Origin Version Required: 8.6 SR0
Note:
1. The function name should be less than 42 characters.

38
 Language Fundamentals

2. Both arguments and return values support string, double, int, dataset, and tree data types.

The default argument type is double. The default return type is int.

3. By default, arguments of user-defined functions are passed by value, meaning that argument

values inside the function are NOT available outside of the function. However, passing

arguments by reference, in which changes in argument values inside the function WILL be

available outside of the function, is possible with the keyword REF.

Here are some simple cases of numeric functions:

// This function calculates the cube root of a number
function double dCubeRoot(double dVal)
{
double xVal;
if(dVal<0) xVal = -exp(ln(-dVal)/3);
else xVal = exp(ln(dVal)/3);
return xVal;
}
// As shown here
dcuberoot(-8)=;
The function below calculates the geometric mean of a dataset:
function double dGeoMean(dataset ds)
{
double dG = ds[1];
for(int ii = 2 ; ii <= ds.GetSize() ; ii++)
dG *= ds[ii]; // All values in dataset multiplied together
return exp(ln(dG)/ds.GetSize());
}
// Argument is anything returning a datset
dGeoMean(col("Raw Data"))=;
This example defines a function that accepts a range argument and returns the mean of the data in
that range:
// Calculate the mean of a range
function double dsmean(range ra)
{
stats ra;
return stats.mean;
}
// Pass a range that specifies all columns ...
// in the first sheet of the active book:
range rAll = 1!(1:end);
dsMean(rAll)=;
This example defines a function that counts the occurrences of a particular weekday in a Date
dataset:
function int iCountDays(dataset ds, int iDay)
{
int iCount = 0;
for(int ii = 1 ; ii <= ds.GetSize() ; ii++)
{
if(weekday(ds[ii], 1) == iDay) iCount++;
}
return iCount;

39
 LabTalk Scripting Guide

}
// Here we count Fridays
iVal = iCountDays(col(1),6); // 6 is Friday in weekday(data, 1) sense
iVal=;
Functions can also return datasets ..
// Get only negative values from a dataset
function dataset dsSub(dataset ds1)
{
dataset ds2;
int iRow = 1;
for(int ii = 1 ; ii <= ds1.GetSize() ; ii++)
{
if(ds1[ii] < 0)
{
ds2[iRow] = ds1[ii];
iRow++;
}
}
return ds2;
}
// Assign all negative values in column 1 to column 2
col(2) = dsSub(col(1));
or strings ..
// Get all values in a dataset where a substring occurs
function string strFind(dataset ds, string strVal)
{
string strTest, strResult;
for( int ii = 1 ; ii <= ds.GetSize() ; ii++ )
{
strTest$ = ds[ii]$;
if( strTest.Find(strVal$) > 0 )
{
strResult$ = %(strResult$)%(CRLF)%(strTest$);
}
}
return strResult$;
}
// Gather all instances in column 3 where "hadron" occurs
string MyResults$ = strFind(col(3),"hadron")$; // Note ending '$'
MyResults$=;

Passing Arguments by Reference

This example demonstrates a function that returns a tree node value as an int (one element of a tree
variable). In addition, passing by reference is illustrated using the REF keyword.
// Function definition:
Function int GetMinMax(range rr, ref double min, ref double max) {
stats rr;
//after running the stats XF, a LabTalk tree variable with the
//same name is created/updated
min = stats.min;
max = stats.max;
return stats.N;
}

40
 Language Fundamentals

// Call function GetMinMax to find min max for an entire worksheet:

double y1,y2;
int nn = getminmax(1:end,y1, y2);
type "Worksheet has $(nn) points, min=$(y1), max=$(y2)";
See this detailed example on using tree variables in LabTalk functions and passing variables by
reference.
Another example of passing string argument by reference is given below that shows that the $
termination should not be used in the function call:
//return range string of the 1st sheet
//actual new book shortname will be returned by Name$
Function string GetNewBook(int nSheets, ref string Name$)
{
newbook sheet:= nSheets result:=Name$;
string strRange$ = "[%(Name$)]1!";
return strRange$;
}
When calling the above function, it is very important that the Name$ argument should not have the $,
as shown below:
string strName$;
string strR$ = GetNewBook(1, strName)$;
strName$=;
strR$=;

3.2.7.3 Dataset Functions

Origin also supports defining mathematical functions that accept arguments of type double and return
type double. The general syntax for such functions is:
funcName(X) = expressionInvolvingX.
We call these dataset functions because when they are defined, a dataset by that name is created.
This dataset, associated with the function, is then saved as part of the Origin project. Once defined, a
dataset function can be referred to by name and used as you would a built-in LabTalk function.
For example, enter the following script in the Script window to define a function named Salary:
Salary(x) = 52 * x
Once defined, the function may be called anytime as in,
Salary(100)=
which yields the result Salary(100)=5200. In this case, the resulting dataset has only one element.
But if a vector (or dataset) were passed as an input argument, the output would be a dataset
containing the same number of elements as the input.
As with other datasets, user-defined dataset functions are listed in dialogs such as Plot Setup (and
can be plotted like any other dataset), and in the Available Data list in dialogs such as Layer n.
If a 2D graph layer is the active layer when a function is defined, then a dataset of 100 points is
created using the X axis scale as the X range and the function dataset is automatically added to the
plot layer.
The Function Graph Template (FUNCTION.OTP, accessible from the Standard Toolbar or the File:
New menu) also creates and plots dataset functions.
Origin's Function Plots feature allows new dataset functions to be easily created from any
combination of built-in and user-defined functions. In addition, the newly created function is
immediately plotted for your reference.
Access this feature in either of two ways:
1. Click on the New Function button in the Standard toolbar,

2. From the Origin drop-down menus, select File: New and select Function from the list of

choices, and click OK.

41
 LabTalk Scripting Guide

From there, in the Function tab of the Plot Details dialog that opens, enter the function definition,
such as, F1(x) = 5*sin(x)+1 and press OK. The function will be plotted in the graph.
You may define another function by clicking on the New Function button in the graph and adding
another function in Plot Details. Press OK, and the new function plot will be added to the graph.
Repeat if more functions are desired.

3.2.7.4 Fitting Functions

In addition to supporting many common functions, Origin also allows you to create your own fitting
functions to be used in non-linear curve fitting. User-defined fitting functions can also be used to
generate new datasets, but calling them requires a special syntax:
nlf_FitFuncName(ds, p1, p2, ..., pn)
where the fitting function is named FitFuncName, ds is a dataset to be used as the independent
variable, and p1--pn are the parameters of the fitting function.
As a simple example, if you defined a simple straight-line fitting function called MyLine that expected
a y-intercept and slope as input parameters (in that order), and you wanted column C in the active
worksheet to be the independent variable (X), and column D to be used for the function output, enter:
// Intercept = 0, Slope = 4
Col(D) = nlf_MyLine(Col(C), 0, 4)

3.2.7.5 Scope of Functions

As with user-defined variables, user-defined functions have a scope that can be controlled. User-
defined functions can be accessed from anywhere in the Origin project where LabTalk script is
supported, provided the scope of definition is applicable to such usage. Thus for example, a function
defined with preceding assignment @glob=1 that returns type double or dataset, can be used in the
Set Values dialog Column Formula panel. For more on scope, see Data Types and Variables.
 You can associate functions with a project by defining them in the project's ProjectEvents.OGS

file. Using @glob=1, your function becomes available any time the project is opened (see this

example, below).

 The scope of a function can be expanded for general use any time that Origin runs by defining

the function using @glob=1, saving the function to an .ogs file in the User Files Folder (UFF),

and calling the .ogs file from the [Startup] section of Origin.ini (also in the UFF), as discussed

here.

Examples: Scope of Functions

Using @glob=1 to call the function anywhere.

[Main]
@glob=1; // promote the following function to session level
function double dGeoMean(dataset ds)
{
double dG = ds[1];
for(int ii = 2 ; ii <= ds.GetSize() ; ii++)
dG *= ds[ii]; // All values in dataset multiplied together
return exp(ln(dG)/ds.GetSize());
}
// can call the function in [main] section

42
 Language Fundamentals

dGeoMean(col(1))=;
[section1]
// the function can be called in this section too
dGeoMean(col(1))=;
If the function is defined in a section of a *.ogs file without @glob=1, then it can only be called in its
own section.
[Main]
function double dGeoMean(dataset ds)
{
double dG = ds[1];
for(int ii = 2 ; ii <= ds.GetSize() ; ii++)
dG *= ds[ii]; // All values in dataset multiplied together
return exp(ln(dG)/ds.GetSize());
}
// can call the function in [main] section
dGeoMean(col(1))=;
[section1]
// the function can NOT be called in this section
dGeoMean(col(1))=; // an error: Unknown function
If the function is defined in a block without @glob=1, it can not be called outside this block.
[Main]
{ // define the function between braces
function double dGeoMean(dataset ds)
{
double dG = ds[1];
for(int ii = 2 ; ii <= ds.GetSize() ; ii++)
dG *= ds[ii]; // All values in dataset multiplied together
return exp(ln(dG)/ds.GetSize());
}
}
// can Not call the function outside the braces
dGeoMean(col(1))=; // an error: Unknown function

3.2.7.6 Tutorial: Using Multiple Function Features

The following mini tutorial shows how to add a user-defined function at the Origin project level and
then use that function to create function plots.
1. Start a new Project and use View: Code Builder menu item to open Code

Builder.

2. Expand the Project branch on the left panel tree and double-click to open the

ProjectEvents.OGS file. This file exists by default in any new Project.

3. Under the [AfterOpenDoc] section, add the following lines of code:

@glob=1;

Function double myPeak(double x, double x0)

43
 LabTalk Scripting Guide

double y = 10*exp(-(x-x0)^2/4);

return y;

4. Save the file and close Code Builder.

5. In Origin, save the Project to a desired folder location. The OGS file is saved

with the Project, so the user-defined function is available for use in the Project.

6. Open the just saved project again. This will trigger the [AfterOpenDoc] section

to be executed and thus our myPeak function to be defined.

7. Click on the New Function button in the Standard toolbar

8. In the Function tab of Plot Details dialog that opens, enter the function

definition:

F1(x) = myPeak(x, 3)

and press OK. The function will be plotted in the graph.

9. Click on the New Function button in the graph and add another function in Plot

Details using the expression:

F2(x) = myPeak(x, 4)

and press OK.

10. The second function plot will be added to the graph.

11. Now save the Project again and re-open it. The two function plots will still be

available, as they refer to the user-defined function saved with the Project.

12. You can assure yourself that the above really works by first exiting Origin,

reopening Origin, and running the project again, checking that the myPeak

function is defined upon loading the project.

3.3 Special Language Features

3.3.1 Special Language Features

44
 Language Fundamentals

These pages contain information on implementing advanced features of the LabTalk scripting
language. Some of the concepts and features in this section are unique to Origin.

This section covers the following topics:

 Range Notation

 Substitution Notation

 LabTalk Objects

 Origin Objects

 String registers

 X-Functions Introduction

3.3.2 Range Notation

3.3.2.1 Introduction to Range
Inside your Origin Project, data exists in four primary places: in the columns of a worksheet, in a
matrix, in a loose dataset, or in a graph. In any of these forms, the range data type allows you to
access your data easily in a standard way.
Once a range variable is created, you can work with the range data directly; reading and writing to the
range. Examples below demonstrate the creation and use of many types of range variables.
Before Origin Version 8.0, data were accessed via datasets as well as cell(), col(), and wcol()
functions. The cell(), col(), and wcol() functions are still very effective for data access, provided that
you are working with the active sheet in the active book. The Range notation essentially expanded
upon these functions to provide general access to any book, sheet, or plot inside an Origin Project.
Note : Not all X-Functions can handle complexities of ranges such as multiple columns or
noncontiguous data. Where logic or documentation does not indicate support, a little experimentation
is in order.
Note : Data inside a graph are in the form of Data Plots and they are essentially references to
columns, matrix or loose datasets. There is no actual data stored in graphs.

Declaration and Syntax

Similar to other data types, you can declare a Range variable using the following syntax:
range [-option] RangeName = RangeString
The left-hand side of the range assignment is uniform for all types of range assignments. Note that
the square brackets indicate that the option switch is an optional parameter and for different data type
the available option switches are different, please view the Types of Range Data section for details.
Range names follow Origin variable naming rules; please note that system variable names should be
avoided.

45
 LabTalk Scripting Guide

The right-hand side of the range assignment, RangeString, changes depending on what type of
object the range points to. Individual Range Strings are defined in the sections below on Types of
Range Data.

Range notation is used exclusively to define range variables. It cannot be used as a

general notation for data access on either side of an expression.

Accessing Origin Objects

A range variable can be assigned to the following types of Origin Objects:

 column

 worksheet

 page

 graph layer

 loose dataset

Once assigned, the range will represent that object so that you can access the object properties and
methods using the range variable.
range rA = [Book1]Sheet1!Col(A);
rA.name$=;
rA.lname$=;
rA.unit$=;
rA.index=;
rA.nRows=;
To determine which object properties and methods are accessible, open the Script Window and type
the following:
rangeVariable.=;
... where rangeVariable is the name of your range variable.

A range may consist of some subset or some combination of standard Origin Objects. Examples
include:
 column subrange

 block of cells

 XY range

 XYZ range

 composite range

3.3.2.2 Types of Range Data

Worksheet Data

For worksheet data, RangeString takes the form:

46
 Language Fundamentals

[WorkBookName]SheetNameOrIndex!ColumnNameOrIndex[CellIndex]
Note: The WorkBookName andSheetName above used their corresponding Short Name since
Short Name is the default programming name. To use Long Name in range notation for workbook or
worksheet, you have to put Long Name in double quotes such as ["MyBook"]"MySheet"!; whereas
ColumnName can be either the Long Name or the Short Name of the column.
In any RangeString, a span of continuous sheets, columns, or rows can be specified by providing
pairs of sheet, column, or row indices (respectively), separated by a colon, as in index1:index2. The
keyword end can replace index2 to indicate that Origin should pick up all of the indicated objects. For
example:
range rs = [Book1]4:end! // Get sheets 4 through last
range rd = [Book2]Sheet3!5:10; // Get columns 5 through 10
range rr = ["MyBook"]Sheet1!A; // Get column A in sheet 1 with workbook Long
Name
// as MyBook
In the case of rows the indices must be surrounded by square brackets, so a full range assignment
statement for several rows of a worksheet column looks like:
range rc1 = [Book1]Sheet2!Col(3)[10:end]; // Get rows 10 through last
range rc2 = [Book1]Sheet2!Col(3)[10:20]; // Get rows 10 through 20
The old way of accessing cell contents, via the Cell function is still supported.
If you wish to access column label rows using range, please see Accessing Metadata and the
Column Label Row Reference Table.

Column

When declaring a range variable for a column on the active worksheet, the book and sheet part can
be dropped, such as:
range rc = Col(3)
You can further simplify the notation, as long as the actual column can be identified, as shown below:
range aa=1; // col(1) of the active worksheet
range bb=B; // col(B) of the active worksheet
range cc="Test A"; // col with Long Name ("Test A"), active worksheet
Note: the quotation mark used in the range string expression always refers to long name, even
though the long name is identical to an expression of worksheet (e.g. 1!), the range string "1!" refers
to the column with long name 1!. This behavior could be turned off by using the system variable
@RPQ, for details please refer to this table.
Multiple range variables can be declared on the same line, separated by comma. The above example
could also have been written as:
range aa = 1, bb = B, cc = "Test A";
Or if you need to refer to a different book sheet, and all in the same sheet, then the book sheet
portion can be combined as follows:
range ["MyBook"]Sheet3 aa=1, bb=B, cc="Test A"; //Book Long Name is MyBook
Because Origin does not force a column's Long Name to be unique (i.e., multiple columns in a
worksheet can have the same Long Name), the Short Name and Long Name may be specified
together to be more precise:
range dd = D"Test 4"; // Assign Col(D), Long Name 'Test 4', to a range
Once you have a column range, use it to access and change the parameters of a column:
range rColumn = [Book1]1!2; // Range is a Column
rColumn.digitMode = 1; // Use Set Decimal Places for display
rColumn.digits = 2; // Use 2 decimal places
Or perform computations:

47
 LabTalk Scripting Guide

// Point to column 1 of sheets 1, 2, and 3 of the active workbook:

range aa = 1!col(1);
range bb = 2!col(1);
range cc = 3!col(1);
cc = aa+bb;

When performing arithmetic on data in different sheets, you need to use range
variables. Direct references to range strings are not yet supported. For example, the
script Sheet3!col(1) = Sheet1!col(1) + Sheet2!col(1); will not work! If you really need
to write in a single line without having to declare range variables, then use Dataset
Substitution.

Page and Sheet

Besides a single column of data, a range can be used to access any portion of a page object:
Use a range variable to access an entire workbook:
// 'rPage' points to the workbook named 'Book1'
range rPage = [Book1];

// Set the Long Name of 'Book1' to "My Analysis Worksheets"

rPage.LongName$ = My Analysis Worksheets;
Use a range variable to access a worksheet:
range rSheet = ["MyBook"]"MySheet"!; // Range is a Worksheet (WKS
object) with
// book Long Name MyBook, sheet
Long Name
// MySheet
rSheet.name$ = "Statistics"; // Rename Sheet1 to "Statistics".
rSheet.AddCol(StdDev); // Add a column named StdDev

Column Subrange

Use a range variable to address a column subrange, such as

// A subrange of col(a) in MyBook (Long Name) sheet2
range cc = ["MyBook"]sheet2!col(a)[3:10];
Or if the desired workbook and worksheet are active, the shortened notation can be used:
// A subrange of col(a) in book1 sheet2
range cc = col(a)[3:10];
Using range variables, you can perform computation or other operations on part of a column. For
example:
range r1=1[5:10];
range r2=2[1:6];
r1 = r2; // copy values in row 1 to 6 of column 2 to rows 5 to 10 of column 1
r1[1]=;
// this should output value in row 5 of column 1, which equates to row 1 of
column 2

Block of Cells

Use a range to access a single cell or block of cells (may span many rows and columns) as in:
range aa = 1[2]; // cell(2,1), row2 of col(1)
range bb = 1[1]:3[10]; // cell(1,1) to cell(10,3)

48
 Language Fundamentals

Note: A range variable representing a block of cells can be used as an X-Function argument only,
direct calculations are not supported.

Option Switch -v

Minimum Origin Version: 9.1 SR0

For worksheet data, you can use the -v switch to define a single block as a range and store its values
in a temporary vector, so that the data assignment between blocks with same size but different block
shape is possible (e.g. assign values from a row to a column would be possible).
The following example illustrates how this option switch can be used.
//Import a sample data into a new book
fname$=system.path.program$ + "\Samples\Statistics\automobile.dat";
newbook;
impasc;
//Define a block as column B to C,all rows
range -v r1 = B[1]:C[end];
// Create a new sheet
newsheet;
//Define a block as column A to B sized
range -v r2 = 1[1]:2[r1.GetSize()/2]; // size of block is 2 columns x rows
//Assign the values in the first block to the second block
r2 = r1;
The vector stores data in column order and fills the destination block regardless of the 'shape':
// Import sample data into a new book
fname$=system.path.program$ + "\Samples\Statistics\abrasion_raw.dat";
newbook;
impasc;
// Define a block as column A & B, all rows
range -v ra1 = 1[1]:2[end];
// Create a new sheet
newsheet;
// Define a block as one column, using the ra1 block size
range -v ra2 = 1[1:ra1.GetSize()];
// Assign the values in the first block to the second block
ra2 = ra1;
col(1)[L]$ = Combined;
Note: The columns defined by the target block must exist before the assignment is made.

Matrix Data

For matrix data, the RangeString is

[MatrixBookName]MatrixSheetNameOrIndex!MatrixObject
Note: The MatrixBookName andMatrixSheetName above used their corresponding Short Name
since Short Name is the default programming name. To use Long Name in range notation for
matrixbook or matrixsheet, you have to put Long Name in double quotes such as
["MyMatrixBook"]"MyMatrixSheet"!.
Variable assignment can be made using the follow syntax:
// Second matrix object on MBook1, MSheet1
range mm = [MBook1]MSheet1!2;
// Matrix object with Long Name MatObject1 on matrix sheet MatSheet1 (Long
Name)
// on matrix book MatBook1 (Long Name)
range mo = ["MatBook1"]"MatSheet1"!Mat("MatObject1");

49
 LabTalk Scripting Guide

Access the cell contents of a matrix range using the notation RangeName[row, col]. For example:
range mm=[MBook1]1!1;
mm[2,3]=10;
If the matrix contains complex numbers, the string representing the complex number can be
accessed as below:
string str$;
str$ = mm[3,4]$;

Graph Data

For graph data, the RangeString is

[GraphWindowName]LayerNameOrIndex!DataPlot
An example assignment looks like
range ll = [Graph1]Layer1!2; // Second curve on Graph1, Layer1

Option Switches -w, -wx, -wy and -wz

For graph windows, you can use range -w and range -wx, range -wy, range -wz options to get the
worksheet column range of a plotted dataset.
range -w always gets the worksheet range of the most dependent variable - which is the Y value for
2D plots and the Z value or matrix object for 3D plots. And since Origin 9.0 SR0, multiple ranges are
supported for range -w.
range -wx, range -wy, and range -wz will get the worksheet range of the corresponding X, Y and Z
values, respectively.
range -wx, range -wz Require Version: 9.0 SR0
// Make a graph window the active window ...
// Get the worksheet range of the Y values of first dataplot:
range -w rW = 1;

// Get the worksheet range of the corresponding X-values:

range -wx rWx = 1;

//Get the worksheet range of the corresponding Y-values:

range -wy rWy = 1;

//Get the worksheet range of the corresponding Z-values:

range -wz rWz = 1;

// Get the graph range of the first dataplot:

range rG = 1;

// Get the current selection (%C); will resolve data between markers.
range -w rC = %C;
Note that in the script above, rW = [Book1]Sheet1!B while rG = [Graph1]1!1.

Data Selector Ranges on a Graph

You can use the Data Selector tool to select one or more ranges on a graph and to refer to them from
LabTalk. For a single selected range, you can use the MKS1, MKS2 system variables. Starting with
version 8.0 SR6, a new X-Function, get_plot_sel, has been added to get the selected ranges into a
string that you can then parse. The following example shows how to select each range on the current
graph:
string strRange;
get_plot_sel str:=strRange;

50
 Language Fundamentals

StringArray sa;
sa.Append(strRange$,"|"); // Tokenize it
int nNumRanges = sa.GetSize();
if(nNumRanges == 0)
{
type "there is nothing selected";
return;
}
type "Total of $(nNumRanges) ranges selected for %C";
for(int ii = 1; ii <= nNumRanges; ii++)
{
range -w xy = sa.GetAt(ii)$;
string strWks$ = "Temp$(ii)";
create %(strWks$) -wdn 10 aa bb;
range fitxy = [??]!(%(strWks$)_aa, %(strWks$)_bb);
fitlr iy:=xy oy:=fitxy;
plotxy fitxy p:=200 o:=<active> c:=color(red) rescale:=0 legend:=0;
type "%(xy) fit linear gives slope=$(fitlr.b)";
}
// clear all the data markers when done
mark -r;
Additional documentation is available for the the Create (Command) (for creating loose datasets), the
[??] range notation (for creating a range from a loose dataset), the fitlr X-Function, and the
StringArray (Object) (specifically, the Append method, which was introduced in Origin 8.0 SR6).

Specifying Subrange Using X Values

When working with an XY range, you can specify a subrange using the X values. The syntax is as
follows:
1. From Worksheet
[WorkBookName]SheetNameOrIndex!YColumnNameOrIndex[xX1:X2]
Example:
// Using Columns 1 and 2 for X and Y, specify subrange from x=0.15 to 0.2
range rxy = (1, 2)[x0.15:0.2];

1. From Graph
[GraphWindowName]LayerNameOrIndex!DataPlot[xX1:X2]
Example:
// XY subrange of the 2nd curve on Graph1, Layer1
range rxy2 = [Graph1]Layer1!2[x5:20];
The following example uses the plotxy X-Function to plot a graph, and then the smooth X-Function to
smooth a subrange of the data.
// Import data into a new book
newbook;
fname$ = system.path.program$ + "\Samples\Signal Processing\EMG
Recording.dat";
impasc;

// Define XY subrange, X from 5 to 5.5, and from 9.3 to 9.8

range rxy1 = (1, 2)[x5:5.5];
range rxy2 = 2[x9.3:9.8];
plotxy rxy1 plot:=200; // Plot line for the 1st XY subrange
smooth -r 2 rxy2 method:=le; // Smooth the 2nd XY subrange by Loess method

51
 LabTalk Scripting Guide

When specifying a subrange based on X values, the X data needs to be monotonic.

Loose Dataset

Loose Datasets are similar to columns in a worksheet but they don't have the overhead of the book-
sheet-column organization. They are typically created with the create command, or automatically
created from an assignment statement without Dataset declaration.
The RangeString for a loose dataset is:
[??]!LooseDatasetName
Assignment can be performed using the syntax:
range xx = [??]!tmpdata_a; // Loose dataset 'tmpdata_a'
To show how this works, we use the plotxy X-Function to plot a graph of a loose dataset.
// Create 2 loose datasets
create tmpdata -wd 50 a b;
tmpdata_a=data(50,1,-1);
tmpdata_b=normal(50);
// Declare the range and explicitly point to the loose dataset
range aa=[??]!(tmpdata_a, tmpdata_b);
// Make a scatter graph with it:
plotxy aa;

Loose datasets belong to a project, so they are different from a Dataset variable,
which is declared, and has either session or local scope. Dataset variables are also
internally loose datasets but they are limited to use in calculations only; they cannot be
used in making plots, for example.

3.3.2.3 Methods of Range

Once a range variable is created, the following methods can be used by this range
Method Description

Return the size of the range. This method works for a dataset range,
such as column, matrix object, graph plot, block of cells, loose
range.getSize()
dataset, etc. Note that, for a block of cells, it only returns the size of
the first sub column specified in the range declaration.

Set the size of the range. This method works for a dataset range,
such as column, matrix object, graph plot, block of cells, loose
range.setSize()
dataset, etc. If the range is block of cells, it only set the size for the
first sub column specified in the range declaration.

If the range has an attached layer (graph layer, worksheet, or matrix

layer), this method will return the uid of the layer, to get the name of
range.getLayer()
the layer, you need the $ sign after the method, such as
"rng.getLayer()$ = ".

If the range has an attached page (graph page, workbook, or

range.getPage()
matrixbook), this method will return the uid of the page, to get the

52
 Language Fundamentals

name of the page, you need the $ sign after the method, such as
"rng.getPage()$ = ".

This method is used to get a subrange from a data range by either

specifying a name or index. This method is only useful for virtual
matrix. For example, with a virtual matrix named as ztitle, you could
range.sub(name/index) use such expression ztitle.sub(y);(by name) or ztitle.sub(1); (by index)
to return a dataset for the Y values, in addition, you may use such
expression ztitle.sub(y)[3]=; or ztitle.sub(y)[3]$=; to return the 3rd
value in this dataset.

This method works for a dataset range, such as column, matrix

object, graph plot, block of cells, loose dataset, etc. It will reverse the
range.reverse() data order of the range. If the range is block of cells, it only reverses
the data order of the first sub column specified in the range
declaration. The X-Function, colReverse, will do the same thing.

3.3.2.4 Unique Uses of Range

Manipulating Range Data

A column range can be used to manipulate data directly. One major advantage of using a range
rather than the direct column name, is that you do not need to be concerned with which page or layer
is active.
For example:
// Declare two range variables, v1 and v2:
range [Book1]Sheet1 r1=Col(A), r2=Col(B);

// Same as col(A)=data(1,30) if [book1]sheet1 is active:

r1 = data(1,30);
r2 = uniform(30);

// Plot creates new window so [Book1]Sheet1 is NOT active:

plotxy 2;
sec -p 1.5; // Delay
r2/=4; // But our range still works; col(A)/=4 does NOT!
sec -p 1.5; // Delay
r2+=.4;
sec -p 1.5; // Delay
r1=10+r1/3;
Direct calculations on a column range variable that addresses a range of cells is supported. For
example:
range aa = Col(A)[10:19]; // Row 10 to 19 of column A
aa += 10; // All elements in aa increase by 10
Support for sub ranges in a column has expanded.
// Range consisting of column 1, rows 7 to 13 and column 2, rows 3 to 4
// Note use of parentheses and comma separator:
range rs = (1[7:13], 2[3:4]);
del rs; // Supported since 8.0 SR6

// Copying between sub ranges

range r1 = 1[85:100];
range r2 = 2;

53
 LabTalk Scripting Guide

// Copy r1 to top of column 2

r2 = r1; // Supported in 8.1
// 8.1 also complete or incomplete copying to sub range
range r2 = 2[17:22];
r2 = r1; // Only copies 6 values from r1
range r2 = 3[50:200];
r2 = r1; // Copies only up to row 65 since source has only 16 values

Dynamic Range Assignment

Sometimes it is beneficial to be able to create a new range in an automated way, at runtime, using a
variable column number, or the name of another range variable.

Define a New Range Using an Expression for Column Index

The wcol() function is used to allow runtime resolution of actual column index, as in
int nn = 2;
range aa=wcol(2*nn +1);

Define a New Range Using an Existing Range

The following lines of script demonstrate how to create one range based on another using the %( )
substitution notation and wks (object) methods. When the %( ) substitution is used on a range
variable, it always resolves it to a [Book]Sheet! string, regardless of the type:
range rwks = sheet3!;
range r1= %(rwks)col(a);
in this case, the new range r1 will resolve to Sheet3!Col(A).
This method of constructing new range based on existing range is very useful because it allows code
centralization to first declare a worksheet range and then to use it to declare column ranges. Lets
now use the rwks variable to add a column to Sheet 3:
rwks.addcol();
And now define another range that resolves to the last (rightmost) column of range rwks; that is, it
will point to the newly made column:
range r2 = %(rwks)wcol( %(rwks)wks.ncols );
With the range assignments in place it is easy to perform calculations and assignments, such as:
r2=r1/10;
which divides the data in range r1 by 10 and places the result in the column associated with range r2.

X-Function Argument

Many X-functions use ranges as arguments. For example, the stats X-Function takes a vector as
input and calculates descriptive statistics on the specified range. So you can type:
stats [Book1]Sheet2!(1:end); // stats on the second sheet of book1
stats Col(2); // stats on column 2 of active worksheet

// stats on block of cells, col 1-2, row 5-10

stats 1[5]:2[10];
Or you can use a range variable to do the same type of operation:
/* Defines a range variable for col(2) of 1st and 2nd sheet,
rows 3-5, and runs the stats XF on that range: */
range aa = (1,2)!col(2)[3:5]; stats aa;
The input vector argument for this X-Function is then specified by a range variable.

54
 Language Fundamentals

Some X-Functions use a special type of range called XYRange, which is essentially a composite
range containing X and Y as well as error bar ranges.
The general syntax for an XYRange is
(rangeX, rangeY)
but you can also skip the rangeX portion and use the standard range notation to specify an XYRange,
in which case the default X data is assumed.
The following two notations are identical for XYRange,
(, rangeY)
rangeY
For example, the integ1 X-Function takes both input and output XYRange,
// integrate col(1) as X and col(2) as Y,
// and put integral curve into columns 3 as X and 4 as Y
integ1 iy:=(1,2) oy:=(3,4);

// same as above except result integral curve output to col(3) as Y,

// and sharing input's X of col(1):
integ1 iy:=2 oy:=3;

3.3.2.5 Listing, Deleting, and Converting Range Variables

Listing Range Variables

Use the list LabTalk command to print a list of names and their defined bodies of all session
variables including the range variables. For example:
list a; // List all session variables
If you issue this command in the Command Window, it prints a list such as:
Session:
1 MYRANGE [book1]sheet1!col(b)
2 MYSTR "abc"
3 PI 3.1415926535898
As of Origin 8.1, more switches have been added (given below) to list particular session variables:
Option What Gets Listed Option What Gets Listed

a All session variables aa String arrays (session)

ac Constants (session) af Local Function (session)

afc Local Function Full Content (session) afp Local Function Prototype (session)

ag Graphic objects (session) ar Range variables (session)

as String variables (session) at Tree variables (session)

av Numeric variables (session) -- --

Deleting Range Variables

To delete a range variable, use the del LabTalk command with the -ra switch. For example:
range aa=1; // aa = Col(1) of the active worksheet
range ab=2; // ab = Col(2) of the active worksheet
range ac=3; // ac = Col(3) of the active worksheet

55
 LabTalk Scripting Guide

range bb=4; // bb = Col(4) of the active worksheet

list a; // list all session variables; will include aa, ab, ac, bb
del -ra a*; // delete all range variables beginning with the letter "a"

// The last command will delete aa, ab, and ac.

The table below lists options for deleting variables.
Option What Gets Deleted/Cleared Option What Gets Deleted/Cleared

ra Any Local/Session variable al same as -ra

rar Range variable ras String variable

rav Numeric variable rac Constant

rat Tree variable raa String array

rag Graphic object raf Local/Session Function

Converting Range to UID

Each Origin Object has a short name, long name, and universal identifier (UID). You can convert
between range variables and their UIDs as well as obtain the names of pages and layers using the
functions range2uid, uid2name, and uid2range. See LabTalk Objects for examples of use.

3.3.2.6 Special Notations for Range

XY and XYZ Range

Designed as inputs to particular X-Functions, an XY Range is an ordered pair designating two

worksheet columns as XY data. And the XY subrange is able to be specified by using X values.
Similarly, an (XYZ Range) is an ordered triple containing three worksheet columns representing XYZ
data.

For instance, the fitpoly X-Function takes an XY range for both input and output:
// Fit a 2nd order polynomial to the XY data in columns 1 and 2;
// Put the coefficients into column 3 and the XY fit data in cols 4 and 5:
fitpoly iy:=(1,2) polyorder:=2 coef:=3 oy:=(4,5);

XY Range using # and ? for X

There are two special characters '?' and '#' introduced in (8.0 SR3) for range as an X-Function
argument. '?' indicates that the range is forced to use worksheet designation, and will fail if the range
designation does not satisfy the requirement. '#' means that the range ignores designations and uses
row number as the X designation. However, if the Y column has even sampling information, that
sampling information will be used to provide X.
For example:
plotxy (?, 5); // if col(5) happens to be X column call fails
plotxy (#, 3); // plot col(3) as Y and use row number as X
These notations are particularly handy in the plotxy X-Function, as demonstrated here:
// Plot all columns in worksheet using their column designations:
plotxy (?,1:end);

56
 Language Fundamentals

Tag Notations in Range Output

Many X-Functions have an output range that can be modified with tags, including template, name,
and index. Here is an example that can be used by the Discrete Frequency X-Function, discfreqs
discfreqs irng:=1 freq:=1 rd:="[Result]<new template:=table.otw index:=3>";
The output is directed to a Workbook named Result by loading a template named TABLE.OTW as
the third sheet in the Result book.
Support of tag notation depends on the particular X-Function, so verify tag notation is supported
before including in production code.

Composite Range

A Composite Range is a range consisting of multiple subranges. You can construct composite ranges
using the following syntax:
// Basic combination of three ranges:
(range1, range2, range3)

// Common column ranges from multiple sheets:

(sheet1,sheet2,sheet3)!range1

// Common column ranges from a range of sheets

(sheet1:sheetn)!range1
To show how this works, we will use the wcellcolor X-Function to show range and plotxy to show
XYRange. Assuming we are working on the active book/sheet, with at least four columns filled with
numeric data:
// color several different blocks with blue color
wcellcolor (1[1]:2[3], 1[5]:2[5], 2[7]) color(blue);

// set font color as red on some of them

wcellcolor (1[3]:4[5], 2[6]:3[7]) color(red) font;
To try plotxy, we will put some numbers into the first sheet, add a new sheet, and put more numbers
into the second sheet.
// plot A(X)B(Y) from both sheets into the same graph.
plotxy (1:2)!(1,2);

// Activate workbook again and add more sheets and fill them with data.
// Plot A(X)B(Y) from all sheets between row2 and row10:
plotxy (1:end)!(1,2)[2:10];
Note: There exists an inherent ambiguity between a composite range, composed of ranges r1 and r2
as in (r1,r2), and an XY range composed of columns named r1 and r2, i.e., (r1,r2). Therefore, it is
important that one keep in mind what type of object is assigned to a given range variable!

3.3.3 Substitution Notation

3.3.3.1 Introduction
When a script is executed, it is sent to the LabTalk interpreter. Among other tasks, the interpreter
searches for special substitution notations, which are identified by their initial characters, % or $.
When a substitution notation is found, the interpreter replaces the original string with another string,
as described in the following section. The value of the substituted string is unknown until the
statement is actually executed. Thus, this procedure is called a run-time string substitution.

57
 LabTalk Scripting Guide

There are three types of substitutions described below:

 String register substitution, %A - %Z

 %( ) Substitution, a powerful notation to resolve %(str$), %(range), worksheet info and column

dataset names, worksheet cells, legend and etc.

 $( ) Substitution, where $(expression) resolves the numeric expression and formats the result

as a string

3.3.3.2 %A - %Z
Using a string register is the simplest form of substitution. String registers are substituted by their
contents during script execution, for example
FDLOG.Open(A); // put file name into %A from dialog
%B=FDLOG.path$; // file path put into %B
doc -open %B%A; // %B%A forms the full path file name
String registers are used more often in older scripts, before the introduction of string variables (Origin
8), which allows for more reliable codes. To resolve string variables, %( ) substitution is used, and is
discussed in the next section.

3.3.3.3 %( ) Substitution

String Expression Substitution

While LabTalk commands often accept numeric expressions as arguments, none accept a string
expression. So if a string is needed as an argument, you have to pass in a string variable or a string
expression using the %( ) substitution to resolve run-time values. The simplest form of a string
expression is a single string variable, like in the example below:
string str$ = "Book2";
win -o %(str$) {wks.ncols=;}

Keyword Substitution

The %( ) substitution notation is also used to insert non-printing characters (also called control
characters), such as tabs or carriage returns into strings. Use LabTalk keywords to access these non-
printing characters. For example,
// Insert a carriage-return, line-feed (CRLF) into a string:
string ss$ = "Hello%(CRLF)Goodbye";
ss$=; // ANS: 'Hello', 'Goodbye' printed on separate lines
// Can be typed directly
type ss$;
// But use %() substitution when mixed with literals
ty I say %(ss$) you say;

Worksheet Column and Cell Substitution

The following notation allows you to access worksheet cells as a string as well as to get the column
dataset name from any workbook sheet. Before Origin 8, each book had only one sheet so you could
refer to its content with the book name only. Since Origin 8 supports multiple worksheets, we
recommend that you use [workbookname]sheetname to refer to a specific sheet, unless you are

58
 Language Fundamentals

certain that the workbook contains only one sheet.

To return individual cell contents, use the following syntax:
 This notation references the active sheet in the named book

%(workbookName, column, row)

 New Origin 8 notation that specifies book and sheet

%([workbookname]sheetname, column, row[,format])

For example, if the third cell in the fourth column in the active worksheet of Book1 contains the value
25, then entering the following statement in the Script window will set A to 25 and put double that
value in another sheet in Book1.
A = %(Book1, 4, 3);
%([Book1]Results, 1, 4) = 2 * A;
To return the contents of a text cell, use a string variable:
string strVar$ = %(Book1, 2, 5); // Note : No end '$' needed here
strVar$ = ;

Before 8.1, you must use column and row index and numeric cell will always return full precision.
Origin 8.1 has added support for column to allow both index and name, and row will also support
Label Row Characters such as L for longname.
There is also an optional format argument that you can use to further specify numeric cell format
when converting to string. Assuming Book2, sheet3 col(Signal)[3] has a numeric value of
12.3456789, but only 2 decimal places are displayed (this setting needs be done in the Column
Properties dialog).
//format string W to use current column format
//Should return 12.34
type "Col(Signal)[3] displayed value is %([Book2]Sheet3,Signal,3,W)";
//full precision if format not specified
A=%([Book2]Sheet3,Signal,3);
A=;// shows 12.3456789
//Or use other format notations
type "Showing 3 decimal places:%([Book2]Sheet3,Signal,3,.3)";
Another syntax can be used to maintain the cell format of the data, for customizations made either in
the Format Cells dialog or the Column Properties dialog:
%([workbookName]sheetName, @WL, column[row], W)
A similar example is shown below:
//Or use another expression with @WL option to keep the display format
type "Col(Signal)[3] displayed value is %([Book2]Sheet3, @WL, Signal[3], W)";
//full precision if format not specified
B=%([Book2]Sheet3,@WL, Signal[3]);
B=;// shows 12.3456789

Note: The format character W is introduced in 9.1 SR0 to replace the usage of C in previous
versions. However, Origin maintains support for the use of %([workbookName]sheetName,
column, row,C) to return the value of the current column format.
To return a dataset name, use the following syntax:
 Older notation for active sheet of named book

%(workbookName, column)
 New Origin 8 book sheet notation

%([workbookName]sheetName, column)
 You can also use index

59
 LabTalk Scripting Guide

%([workbookName]SheetIndex, column)
where column must be an index prior to Origin 8.1 which added support for column name.
For example:
%A = %(%H, 2); // Column 2 of active sheet of active book
type %A;
%B = %([Book1]Sheet3,2); // Column 2 of Book1, Sheet3
type %B;
In the above example, the name of the dataset in column 2 in the active worksheet is substituted for
the expression on the right, and then assigned to %A and %B. In the second case, if the named book
or sheet does not exist, no error occurs but the substitution will be invalid.
Note: You can use parentheses to force assignment to be performed on the dataset whose name is
contained in a string register variable instead of performing the assignment on the string register
variable itself.
%A = %(Book1,2); // Get column 2 dataset name
type %A; // Types the name of the dataset
(%A) = %(Book1,1); // Copy column 1 data to column 2

Calculation Involving Datasets from Another Sheet

The ability to get a dataset name from any book or sheet (Dataset Substitution) can be very useful in
doing calculations involving columns in different sheets, like:
// Sum col(1) from sheet2 and 3 and place the result into col(1) of the
active sheet
col(1)=%([%H]sheet2, 1) + %([%H]sheet3, 1);

// subtract by col "signal" in the 1st sheet of book2 and

// put result into the active book's sheet3, "calibrated" col
%([%H]sheet3, "calibrated")=col(signal) - %([Book2]1,signal);
The column name should be quoted if using long name. If not quoted, then Origin will first assume
short name, if not found, then it will try using long name. So in the example above,
%([%H]sheet3, "calibrated")
will force a long name search, while
%([Book2]1,signal)
will use long name only if there is no column with such a short name.

Worksheet Information Substitution

Similar to worksheet column and cell access with substitution notation, the @ Substitution (worksheet
info substitution) make uses of the @ character to differentiate from a column index or name in the
2nd argument to specify various options to provide access to worksheet info and meta data.
The following syntax can be used for worksheet information substitution and is still supported for the
active sheet:
%(workbookName, @option, columnNumber)
It is recommended that you use the newer notation introduced in Origin 8:
%([workbookName]worksheetName, @option, columnNumber)
Here, option can be one of the following:
Option Return Value

@# Returns the total number of worksheet columns. ColumnNumber can be omitted.

@CS Returns the column index of the first selected column to the right of (and including) the

60
 Language Fundamentals

columnNumber column, regardless of column designation.

If columnNumber = 1, returns the number of Y error columns in the worksheet. If

@E# columnNumber = 2, returns the number of Y error columns in the current selection
range. If columnNumber is omitted, columnNumber is assumed to be 1.

If columnNumber = 1, returns the number of X error columns in the worksheet. If

@H# columnNumber = 2, returns the number of X error columns in the current selection
range. If columnNumber is omitted, columnNumber is assumed to be 1.

Use with %H to return the Project Explorer (PE) path of the active window (%(%H,
@P
@P)).

@PC Page Comments

@PCn Page Comments, the nth line only

@PL Page Long Name

@PN Page short Name

@SN Sheet Name

@SC Sheet Comments

Returns the offset from the left-most selected Y column to the columnNumber column
@OY
in the current selection.

Returns the offset from the left-most selected Y column to the columnNumber Y
@OYX
column counting on Y columns in the current selection.

Returns the offset from the left-most selected Y column to the columnNumber X
@OYY
column counting on X columns in the current selection.

Returns the column type. 1 = Y , 2 = disregarded, 3 = Y error, 4 = X , 5 = label, 6 = Z,

@T
and 7 = X error.

Returns the index number of the worksheet's first X column. Columns are enumerated
@X
from left to right, starting from 1. Use the syntax: %(worksheetName, @X);

Returns the column short name of the worksheet's first X column. Use the syntax:
@Xn
%(worksheetName, @Xn);

Returns the offset from the left-most selected column to the columnNumber column in
@Y
the current selection.

Returns the column number of the first Y column to the left. Returns columnNumber if
@Y- the column is a Y column, or returns 0 when the Y column doesn't exist. Use the
syntax: %(worksheetName, @Y-, ColumnNumber);

If columnNumber = 1, returns the number of Y columns in the worksheet. If

@Y# columnNumber = 2, returns the number of Y columns in the current selection range. If
columnNumber is omitted, columnNumber is assumed to be 1.

61
 LabTalk Scripting Guide

Returns the column number of the first Y column to the right. Returns columnNumber
@Y+ if the column is a Y column, or returns 0 when the Y column doesn't exist. Use the
syntax: %(worksheetName, @Y+, ColumnNumber);

Returns the number of the first selected Y column to the right of (and including) the
@YS
columnNumber column.

If columnNumber = 1, returns the number of Z columns in the worksheet. If

@Z# columnNumber = 2, returns the number of Z columns in the current selection range. If
columnNumber is omitted, columnNumber is assumed to be 1.
The options in this table are sometimes identified as @ options or @ variables. The @Options in the
Text Label Options page can also be used in worksheet information substitution.

Information Storage and Imported File Information

The @W variables access metadata stored within Origin workbooks, worksheets, and columns, as
well as information stored about imported files.
Use a similar syntax as above, replacing column number with variable or node information:
%([workbookName]worksheetName!columnName, @option, varOrNodeName)
Option Return Value

Returns the information in varOrNodeName; the variable is understood to be located

@W at the workbook level, which can be seen in workbook Origanizer. When it is used,
there is no need to specify worksheetName!ColumnName.

Returns the information in varOrNodeName for the nth imported file. The variable can
@WFn
be seen in the workbook Organizer.

Returns the information in varOrNodeName; the variable is understood to be located

@WS at the worksheet level, which can be seen in workbook Organizer. When it is used,
there is no need to specify ColumnName.

Returns the information in varOrNodeName; the variable is understood to be located

@WC
at the column level, which can be seen in the Column Properties dialog.

Examples of @ Substitution

This script returns the column name of the first column in the current selection range (for information
on the selc1 numeric system variable, see System Variables):
%N = %(%H, @col, selc1); %N =;
This script returns the Project Explorer path of the active window:
%P = %(%H, @P); %P=;
The following line returns the active page's long name to a string variable:
string PageName$ = %(%H, @PL);
The script below returns the column type for the fourth column in Book 2, Sheet 3:
string colType$ = %([Book2]Sheet3, @T, 4);
colType$=;

62
 Language Fundamentals

An import filter can create a tree structure of information about the imported file that gets stored with
the workbook. Here, for a multifile import, we return the number of points in the 3rd dataset imported
into the current book:
%z=%(%H,@WF3,variables.header.noofpoints);
%z=
If the currently active worksheet window has six columns (XYYYYY) and columns 2, 4, and 5 are
selected, then the following script shows the number of the first selected Y column to the right of (and
including) the column whose index is equal to columnNumber (the third argument):
loop(ii,1,6)
{
type -l %(%H, @YS, ii),;
}
type;
This outputs:
2,2,4,4,5,0,

Legend and Axis Title Substitution

Graph legends and axis titles also employ the %( ) substitution notation. The first argument must be
an integer to differentiate it from other %( ) notations, where the first argument is a worksheet
specifier. The legend and axis title substitution syntax is:
%(PlotIndex[, @option])
where PlotIndex is the index of the data plot in the current layer or a questions mark ?. The variable
PlotIndex might be followed by more options, such as a plot designation character (X, Y or Z)
associated with the data plot; when not specified this is assumed to be Y. The @option parameter is
an optional argument that controls the legend contents. For example:
// In the legend of the current graph layer ...
// display the Long Name for the first dependent dataset.
legend.text$ = %(1Y, @LL)

// Equivalent command (where, Y, the default, is understood):

legend.text$ = %(1, @LL)
Alternatively, to display the Short Name for the second independent (i.e., X) dataset in the legend,
use:
legend.text$ = %(2X, @LS)
The %(?Y) for Axis title is a special syntax that allows the text label to default to a pre-specified data
plot index (which can be set in Plot Details: Legends/Titles: Data Plot Index for Auto Axis Titles),
instead of an index (1, 2, ... n) that you supply. To display Y data long name followed by units in <>
as left Y axis title, use:
yl.text$ = %(?Y,@(@LL<@LU>));

You can refer to the legend substitution notation page for further information and the text label
options page for a complete list of @options.
Note: This style of legend modification is limited in that it only changes a single legend entry, but the
syntax is good to understand, as it can be used in the Plot Details dialog.

The legendupdate X-Function provides an easier and more comprehensive way to

modify or redraw a legend from Script!

3.3.3.4 $( ) Substitution

63
 LabTalk Scripting Guide

The $() notation is used for numeric to string conversion. This notation evaluates the given
expression at run-time, converts the result to a numeric string, and then substitutes the string for
itself.
The notation has the following form:
$(expression [, format])
where expression can be any mathematical expression, but typically a single number or
variable(dataset and data range), and format can be either an Origin output format or a C-language
format.
If expression is a dataset or range variable, it returns a value list separated by space. (Minimum
Version: 9.1 SR0)
For example:
//Define a dataset
dataset ds1 = {1, 3, 5, 7};
//Output the result of substitution notation
type $(ds1);//ANS:1 3 5 7;
type $(ds1, *2);//ANS: 1.0 3.0 5.0 7.0

//Pass the values in the first column to range variable rx

range rx = col(1);
//Output the result of substitution notation
type $(rx);

Default Format

The square brackets indicate that format is an optional argument for the $() substitution notation. If
format is excluded Origin will carry expression to the number of decimal digits or significant digits
specified by the @SD system variable (which default value is 14). For example:
double aa = 3.14159265358979323846;
type $(aa); // ANS: 3.1415926535898

Origin Formats

Minimum Origin Version Required: 9.1 SR0

Origin has several native options to format your output.
Format Description

*n Display n significant digits

.n Display n decimal places

2.n Display n decimal places, in power of 2 format

*n* Display n significant digits, truncating trailing zeros

Display thousand separator for the integer portion and specify n

.n,
decimal places

P*n Display n significant digits in scientific notation of the form 10^3

S*n Display n significant digits in scientific notation of the form 1E3

Display n decimal places, in scientific notation of the form 1E3.

S.n[#]
The optional pound symbol "#" (square brackets indicate an

64
 Language Fundamentals

optional flag) modifies the notation to display only the coefficient.

E*n Display n significant digits, in engineering format (e.g. 1.000k)

E.n Display n decimal places, in engineering format

L.n Display n decimal places, in power of e format

Display in custom date format, using these date and time format
D<format>
specifiers

Display date in format n from the Display drop down list of the
Dn
Column Properties dialog box (indexed from "0")

Display in custom time format, using these date and time format
T<format>
specifiers

Display time in format n from the Display drop down list of the
Tn
Column Properties dialog box (indexed from "0")

#n Display an integer to n places, zero padding where necessary

Display a number by specifying a separator (<sep>) between

digits and optionally add prefix(<prefix>) and/or suffix (<suffix>).
<prefix>##<sep>###<suffix> One # symbol indicates one digit. The last # in this expression
always refers to the unit digit. The numbers of # in both first and
second parts can be varied.
This block of script demonstrates several examples of Origin formats:
xx = 1.23456;
type "xx = $(xx, *2)"; // ANS: 1.2
type "xx = $(xx, .2)"; // ANS: 1.23

yy = 1.10001;
type "yy = $(yy, *4)"; // ANS: 1.100
type "yy = $(yy, *4*)"; // ANS: 1.1

zz = 203465987;
type "zz = $(zz, E*3)"; // ANS: 203M
type "zz = $(zz, S*3)"; // ANS: 2.03E+08

type "$(date(7/20/2009), D1)"; // ANS: Monday, July 20, 2009

type "$(date(7/20/2009), Dyyyy'-'MM'-'dd)"; // ANS: 2009-07-20

type "$(time(14:31:04), T4)"; // ANS: 02 PM

type "$(time(14:31:04), Thh'.'mm'.'ss)"; // ANS: 02.31.04

type "$(45, #5)"; // ANS: 00045

type "$(56000, ##+###)"; //ANS: 56+000

type "$(4000, ##+##M)"; //ANS: 40+00M

65
 LabTalk Scripting Guide

type "$(10000, .0,)"; //ANS: 10,000

Note: For dates and times n starts from zero.

C-Language Formats

The format portion of the $() notation also supports C-language formatting statements.
Option Un/Signed Output Input Range

Integer values (of decimal or integer

d, i SIGNED -2^31 -- 2^31 -1
value)

f, e, E, g, +/-1e290 -- +/-1e-
SIGNED Decimal, scientific, decimal-or-scientific
G 290

Octal, Integer, hexadecimal,

o, u, x, X UNSIGNED -2^31 -- 2^32 - 1
HEXADECIMAL
Note: In the last category, negative values will be expressed as two's complement.
Here are a few examples of C codes in use in LabTalk:
double nn = -247.56;
type "Value: $(nn,%d)"; // ANS: -247

double nn = 1.23456e5;
type "Values: $(nn, %9.4f), $(nn, %9.4E), $(nn, %g)";
// ANS: 123456.0000, 1.2346E+005, 123456

double nn = 1.23456e6;
type "Values: $(nn, %9.4f), $(nn, %9.4E), $(nn, %g)";
// ANS: 123456.0000, 1.2346E+006, 1.23456e+006

double nn = 65551;
type "Values: $(nn, %o), $(nn, %u), $(nn, %X)";
// ANS: 200017, 65551, 1000F

Combining Origin and C-language Formats

Origin supports the use of formats E and S along with C-language format specifiers. For example:
xx = 1e6;
type "xx = $(xx, E%4.2f)"; // ANS: 1.00M

Displaying Negative Values

The command parsing for the type command (and others) looks for the - character as an option
switch indicator. If you assign a negative value to the variable K and try to use the type command to
express that value, you must protect the - by enclosing the substitution in quotes or parentheses. For
example:
K = -5;
type "$(K)"; // This works
type ($(K)); // as does this
type $(K); // but this fails since type command has no -5 option

Dynamic Variable Naming and Creation

66
 Language Fundamentals

Note that in assignment statements, the $() notation is substitution-processed and resolved to a value
regardless of which side of the assignment operator it is located.
This script creates a variable A with the value 2.
A = 2;
Then we can create a variable A2 with the value 3 with this notation:
A$(A) = 3;
You can verify it by entering A$(A) = or A2 = in the Script window.

For more examples of $() substitution, see Numeric to String conversion.

3.3.3.5 %n Macro and Script Arguments

Substitutions of the form %n, where n is an integer 1-5 (up to five arguments can be passed to a
macro or a script), are used for arguments passed into macros or sections of script.
In the following example, the script defines a macro that takes two arguments (%1 and %2), adds
them, and outputs the sum to a dialog box:
def add {type -b "(%1 + %2) = $(%1 + %2)"}
Once defined, the macro can be run by typing:
add -13 27;
The output string reads:
(-13 + 27) = 14
since the expression $(%1 + %2) resolves to 14.

3.3.4 LabTalk Objects

LabTalk script programming provides access to various objects and their properties. These objects
include components of the Origin project that are visible in the graphical interface, such as
worksheets columns and data plots in graphs. Such objects are referred to as Origin Objects, and
are the subject of the next section, Origin Objects.
The collection of objects also includes other objects that are not visible in the interface, such as the
INI object or the System object. The entire set of objects accessible from LabTalk script is found in
Alphabetical Listing of Objects.
In general, every object has properties that describe it, and methods that operate on it. What those
properties and methods are depend on the particular object. For instance, a data column will have
different properties than a graph, and the operations you perform on each will be different as well. In
either case, we need a general syntax for accessing an object's properties and calling it's methods.
These are summarized below.
Also, because objects can be renamed, and objects of different scope may even share a name,
object names can at times be ambiguous identifiers. For that reason, each object is assigned a
unique universal identifier (UID) by Origin and functions are provided to go back and forth between an
object's name and it's UID.

3.3.4.1 Properties
A property either sets or returns a number or a text string associated with an object with the following
syntax:
objName.property (For numeric properties)
objName.property$ (For text properties)
Where objName is the name of the object; property is a valid property for the type of object. When
accessing text objects, you should add the $ symbol after property.
For example, you can set object properties in the following way:
// Set the number of columns on the active worksheet to 10
wks.ncols = 10;
// Rename the active worksheet 'MySheet'

67
 LabTalk Scripting Guide

wks.name$ = MySheet;
Or you can get property values:
pn$ = page.name$; // Get that active page name
layer.x.from = ; // Get and display the start value of the x-axis

3.3.4.2 Methods
Methods are a form of immediate command. When executed, they carry out a function related to the
object and return a value. Object methods use the following syntax:
objName.method(arguments)
Where objName is the name of the object; method is a valid method for the type of object; and
arguments determine how the method functions. Some arguments are optional and some methods
do not require any arguments. However, the parentheses "()" must be included in every object
method statement, even if their contents are empty.
For example, the following code uses the section method of the run object to call the Main section
within a script named computeCircle, and passes it three arguments:
double RR = 4.5;
string PA$ = "Perimeter and Area";
run.section(computeCircle, Main, PA$ 3.14 R);

3.3.4.3 Object Name and Universal Identifier (UID)

Each object has a short name, a long name, and most objects also have a universal identifier (UID).
Both the short name and long name can be changed, but an object's UID will stay the same within a
project (also known as an OPJ file). An object's UID can change if you append one project to another
one, at which time all object UID's will go through a refresh process to ensure the uniquness of each
object in the newly combined project.
Since many LabTalk functions require the name of an object as argument, and since an object can be
renamed, the following functions are provided to convert between the two:
 nVal = range2uid(rangeName$)

 str$ = uid2name(nVal)$

 str$ = uid2range(nVal)$

A related function is NameOf(range$) with the general syntax:

 str$ = nameof(rangeName$)

Its use is demonstrated in the following example:

// Establish a range variable for column 1 (in Book1, Sheet1)
range ra=[Book1]1!1;
// Get the internal name associated with that range
string na$ = NameOf(ra)$;
// na$ will be 'Book1_A'
na$ =;
// Get the UID given the internal name
int nDataSetUID = range2uid(na$);
Besides a range name, the UID can be recovered from the names of columns, sheets, or books
themselves:
// Return the UID of column 2
int nColUID = range2uid(col(2));
// Return the UID of a sheet or layer
int nLayerUID = range2uid([book2]Sheet3!);
// Return the UID of the active sheet or layer
nLayerUID =range2uid(!);

68
 Language Fundamentals

// Return the UID of sheet3 of the active workbook

nLayerUID =range2uid(sheet3!);
// Return the UID of the column with index 'jj' within a specific sheet
nColUID = range2uid([Book1]sheet2!wcol(jj));
Additionally, the range2uid function works with the system variable %C, which holds the name of the
active data plot or data column:
// Return the UID of the active data plot or selected column
nDataSetUID = range2uid(%C);

Getting Page and Layer from a Range Variable

Given a range variable, you can get its corresponding Page and Layer UID. The following code
shows how to make a hidden plot from XY data in the current sheet and to obtain the hidden plot's
graph page name:
plotxy (1,2) hide:=1; // plot A(x)B(y) to a new hidden plot
range aa=plotxy.ogl$;
int uid=aa.GetPage();
string str$=uid2Name(uid)$;
type "Resulting graph name is %(str$)";

Getting Book And Sheet from a Plot

You can also get a data plot's related workbook and worksheet as range variables. The following
code (requires Origin 8 SR2) shows how to get the Active plot (%C) as a column range and then
retrieve from it the corresponding worksheet and book variables allowing complete access to the plot
data:
// col range for active plot, -w switch default to get the Y column
range -w aa=%C;
// wks range for the sheet the column belongs to
range ss = uid2range(aa.GetLayer())$;
// show sheet name
ss.name$=;
// book range from that col
range bb = uid2range(aa.GetPage())$;
// show book name
bb.name$=;
There is also a simpler way to directly use the range string return from GetLayer and GetPage in
string form:
// col range for active plot, -w switch default to get the Y column
range -w aa=%C;
// sheet range string for the sheet the column belongs to
range ss = aa.GetLayer()$;
// show sheet name
ss.name$=;
// book range string from that col
range bb = aa.GetPage()$;
// show book name
bb.name$=;
When you create a range mapped to a page, the range variable has the properties of a PAGE
(Object).
When you create a range mapped to a graph layer, the range variable has the properties of a LAYER
(Object).
When you create a range mapped to a workbook layer (a worksheet or matrix sheet), the range
variable has the properties of a WKS (Object).

69
 LabTalk Scripting Guide

3.3.5 Origin Objects

Then there is a set of LabTalk Objects that is so integral to scripting in Origin that we give them a
separate name: Origin Objects. These objects are visible in the graphical interface, and will be saved
in an Origin project file (.OPJ). Origin Objects are the primary components of your Origin Project.
They are the following:
1. Page (Workbook/Graph Window/Matrix Book) Object

2. Worksheet Object

3. Column Object

4. Layer Object

5. Matrix Object

6. Dataset Object

7. Graphic Object

Except loose datasets, Origin objects can be organized into three hierarchies:
Workbook -> Worksheet -> Column
Matrix Book -> Matrix Sheet -> Matrix Object
Graph Window -> Layer -> Dataplot
In the sections that follow, tables list object methods and examples demonstrate the use of these
objects in script.

3.3.6 String registers

3.3.6.1 Introduction
String Registers are one means of handling string data in Origin. Before Version 8.0, they were the
only way and, as such, current versions of Origin continue to support the use of string registers.
However, users are now encouraged to migrate their string processing routines toward the use of
proper string variables, see String Processing for comparative use.
Long-time LabTalk scripters know string register names to be comprised of a %-character followed by
a single alphabetic character (a letter from A to Z). Of these original 26 string registers, i.e., %A--%Z,
some are reserved as system string registers (listed in the table, below).
Starting with Origin 2016 SR2, "%@N" read-only system string registers are being added, as needed.
You will find those listed in a second table below the original "%N" string registers.

String registers are of global scope; this means that they can be changed by any script
at any time. Sometimes this is useful, other times it is dangerous, as one script could
change the value in a string register that is being used by another script with
erroneous and confusing results.

Some string registers are reserved for use as system variables, and attempting to
assign values to them could result in errors in your script. They are grouped in the
ranges %C--%I, and %X--%Z, or are preceded by a %@ (e.g. %@A = Apps root
folder). Consult the tables below.

3.3.6.2 String Registers as System Variables

70
 Language Fundamentals

String registers hold up to 260 characters (%Z holds up to 6290). String register names are
comprised of a %-character followed by a single alphabetic character (a letter from A to Z); for this
reason, string registers are also known as % variables. Of the 26 possible string registers, the
following are reserved as system variables that have a special meaning, and they should not be
reassigned in your scripts. It is often helpful, however, to have access to (or operate on) the values
they store.
%
Description
Variable

%C The name of the current active dataset.

%D Current Working Directory, as set by the cd command. (New in Origin 8)

%E The name of the window containing the latest worksheet selection.

%F The name of the dataset currently in the fitting session.

%G The current project name.

%H The current active window title.

%I The current baseline dataset.

%X The path of the current project.

The full path name to the User Files folder, where the user .INI files as well as
other user-customizable files are located. %Y can be different for each user
depending on the location they selected when Origin was started for the first time.
Prior to Origin 7.5, the path to the various user .INI files was the same as it was to
the Origin .EXE. Beginning with Origin 7.5, we added multi-user-on-single-
%Y workstation support by creating a separate "User Files" folder.
To get the Origin .EXE path(program path), use the following LabTalk statement:
%a = system.path.program$

In Origin C, pass the appropriate argument to the GetAppPath() function (to

return the INI path or the EXE path).

%Z A long string for temporary storage. (maximumn 6290 characters)

The following extra read-only system string registers comprised of %@-characters followed by a
single alphabetic character are added from Origin 2016 SR2. ;
%@
Description
Variable

%@A The Apps root installation folder.

%@F The name of the active Project Explorer folder.

%@H The book name that contains the active embedded graph.

%@P The full Project Explorer path of the active folder.

71
 LabTalk Scripting Guide

User AppData Root folder. This folder stores the xml file that lists installed apps
%@Y
and their version number.

String registers containing system variables can be used anywhere a name can be used, as in the
following example:
// Deletes the current active dataset:

del %C;

3.3.6.3 String Registers as String Variables

Except the system variable string registers, you can use string registers as string variables,
demonstrated in the following examples:

Assigning Values to a String Variable

Entering the following assignment statement in the Script window:

%A = John
defines the contents of the string variable %A to be John.
String variables can also be used in substitution notation. Using substitution notation, enter the
following assignment statement in the Script window:
%B = %A F Smith
This sets %B equal to John F Smith. Thus, the string variable to the right of the assignment operator
is expressed, and the result is assigned to the identifier on the left of the assignment operator.
As with numeric variables, if you enter the following assignment statement in the Script window:
%B =
Origin returns the value of the variable:
John F Smith

Expressing the Variable Before Assignment

By using parentheses, the string variable on the left of the assignment operator can be expressed
before the assignment is made. For example, enter the following assignment statement in the Script
window:
%B = Book1_A
This statement assigns the string register %B the value Book1_A. If Book1_A is a dataset name,
then entering the following assignment statement in the Script window:
(%B) = 2*%B
results in the dataset being multiplied by 2. String register %B, however, still contains the string
Book1_A.

String Comparison

When comparing string registers, use the "equal to" operator (==).
 If string registers are surrounded by quotation marks (as in, "%a"), Origin literally compares the

string characters that make up each variable name. For example:

aaa = 4;
bbb = 4;

72
 Language Fundamentals

%A = aaa;
%B = bbb;
if ("%A" == "%B")
type "YES";
else
type "NO";
The result will be NO, because in this case aaa != bbb.
 If string registers are not surrounded by quotation marks (as in, %a), Origin compares the

values of the variables stored in the string registers. For example:

aaa = 4;
bbb = 4;
%A = aaa;
%B = bbb;
if (%A == %B)
type "YES";
else
type "NO"
The result will be YES, because in this case the values of the strings (rather than the characters) are
compared, and aaa == bbb == 4.

Substring Notation

Substring notation returns the specified portion of a string. The general form of this notation is:
%[string, argument];
where string contains the string itself, and argument specifies which portion of the string to return.
For the examples that follow, enter this assignment statement in the Script window:
%A = "Results from Data2_Test"
The following examples illustrate the use of argument in substring notation:
To do this: Enter this script: Return value:

Search for a character and return all text to Results from

%B = %[%A, '_']; %B =
the left of the character. Data2

Search for a character and return all text to

%B = %[%A, >'_']; %B = Test
the right of the character.

Return all text to the left of the specified

%B = %[%A, 8]; %B = Results
character position.

Return all text between two specified %B = %[%A, 14:18]; %B

Data2
character positions (inclusive). =

Return the #n token, counting from the left. %B = %[%A, #2]; %B = from

Return the length of the string. ii = %[%A]; ii = ii = 23

Other examples of substring notation:
To do this: Enter this script: Return value:

73
 LabTalk Scripting Guide

%A = 123 342 456;

for (ii = 1; ii
Return the ith token
<= 3; ii++) Places the value 123 in
separated by a specified
{ Book1_a[1], 342 in Book1_a[2],
separator (in this case, a Book1_A[ii] = and 456 in Book1_a[3].
tab) %[%A, #ii,\t]
};

%Z = "First line Places the second line of the %Z

Return the @n line second line"; string into %A. To verify this, type
%A = %[%Z, @2]; %A = in the Script window.

Note:

When using quotation marks in substring or substitution notation:

 Space characters are not ignored.

 String length notation includes space characters.

For example, to set %A equal to 5 and find the length of %A, type the following in the Script window
and press Enter:
%A = " 5 ";
ii = %[%A];
ii = ;
Origin returns: ii = 3.

A Note on Tokens

A token can be a word surrounded by white space (spaces or TABS), or a group of words enclosed in
any kind of brackets. For example, if:
%A = These (are all) "different tokens"
then entering the following in the Script window:
Scripts Returns

%B = %[%A, #1]; %B= These

%B = %[%A, #2]; %B= are all

%B = %[%A, #3]; %B= different tokens

3.3.7 X-Functions Introduction

The X-Function is a new feature, introduced in Origin 8, that provides a framework for building Origin
tools. Most X-Functions can be accessed from LabTalk script to perform tasks like object
manipulation or data analysis.
The general syntax for issuing an X-Function command from script is as follows, where square-
brackets [ ] indicate optional statements:
xfname [-options] arg1:=value arg2:=value ... argN:=value;
Note that when running X-Functions, Origin uses a combined colon-equal symbol, ":=", to assign
argument values. For example, to perform a simple linear fit, the fitlr X-Function is used:
// Data to be fit, Col(A) and Col(B) of the active worksheet,

74
 Language Fundamentals

// is assigned, using :=, to the input variable 'iy'

fitlr iy:=(col(a), col(b));
Also note that, while most X-Functions have optional arguments, it is often possible to call an X-
Function with no arguments, in which case Origin uses default values and settings. For example, to
create a new workbook, call the newbook X-Function:
newbook;
Since X-Functions are easy and useful to run, we will use many of them in the following script
examples. Details on the options (including getting help, opening the dialog and creating auto-update
output) and arguments for running X-Functions are discussed in the Calling X-Functions and Origin C
Functions section.

3.4 LabTalk Script Precedence

Now that we know that there are several objects, like Macros, Origin C functions, X-Functions, OGS
files, etc. So, we should be careful to avoid naming conflicts between these objects, which could
cause confusion and lead to incorrect results. If duplicate names are unavoidable, LabTalk will run
objects according to set of precedence rules. The following list of LabTalk objects are arranged top to
bottom in descending precedence.
1. Macros

2. OGS Files

3. X-Functions

4. LT object methods, like run.file(FileName)

5. LT callable Origin C functions

6. LT commands (can be abbreviated)

75
4 Calling X-Functions and Origin C Functions

4.1 Calling X-Functions and Origin C Functions

This chapter covers how to call X-Functions and Origin C functions from LabTalk.

 X-Functions

 Origin C Functions

4.2 X-Functions
4.2.1 X-Functions
X-Functions are a primary tool for executing tasks and tapping into Origin features from your LabTalk
scripts. The following sections outline the details that will help you recognize, understand, and utilize
X-Functions in LabTalk.

This chapter covers the following topics:

 X-Functions Overview

 X-Function Input and Output

 X-Function Execution Options

 X-Function Exception Handling

4.2.2 X-Functions 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.

4.2.2.1 Syntax

77
 LabTalk Scripting Guide

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

4.2.2.2 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:

78
 Calling X-Functions and Origin C Functions

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.

4.2.2.3 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:
Name Function

-h Prints the contents of the help file to the Script window.

-d Brings up a graphical user interface dialog to input parameters.

-s Runs in silent mode; results not sent to Results log.

-t <themeName> Uses a pre-set theme.

-r <value> Sets the output to automatically recalculate if input changes.

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

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

79
 LabTalk Scripting Guide

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

4.2.3 X-Function Input and Output

4.2.3.1 X-Function Variables
X-Functions accept LabTalk variable types (except StringArray) as arguments. In addition to LabTalk
variables, X-Functions also use special variable types for more complicated data structures.
These special variable types work only as arguments to X-Functions, and are listed in the table below
(Please see the Special Keywords for Range section below for more details about available key
words.):
Variable
Description Sample Constructions Comment
Type

For
graph,
1. (1,2) use
index
2. <new> directly
A
to
combination 3. (1,2:end) indicate
of X, Y, and
XYRange plot
optional Y 4. (<input>,<new>) range
Error Bar
(1,2)
data 5. [book2]sheet3!<new> means
1st and
2nd
plots on
graph

1. (1,2,3)
A 2. <new>
combination
XYZRange
of X, Y, and 3. [book2]sheet3!(1,<new>,<new>)
Z data

A Tree
based
object for a
Hierarchical 1. <new>
Report
Must be 2. [<input>]<new>
ReportTree associated
with a 3. [book2]sheet3
worksheet
range or a
LabTalk
Tree
variable

80
 Calling X-Functions and Origin C Functions

A Tree
based
object for a
collection of
vectors
Must be
associated
with a
worksheet
range or a
LabTalk
Tree
variable. 1. <new>
Unlike
ReportTree, 2. [<input>]<new>
ReportData
outputs to a 3. [book2]sheet3
ReportData
regular
worksheet 4. [<input>]<input>!<new>
and thus
can be
used to
append to
the end of
existing
data in a
worksheet.
All the
columns in
a
ReportData
object must
be grouped
together.

To understand these variable types better, please refer to the real examples in the ReportData
Output section below, which have shown some concrete usages.

4.2.3.2 Special Keywords for Range

<new>
Adding/Creating a new object
<active>
Use the active object
<input>
Same as the input range in the same X-Function
<same>
Same as the previous variable in the X-Function
<optional>
Indicate the object is optional in input or output
<none>
No object will be created

4.2.3.3 ReportData Output

81
 LabTalk Scripting Guide

Many X-Functions generate multiple output vectors in the form of a ReportData object. Typically, a
ReportData object is associated with a worksheet, such as the Fit Curves output from the NLFit X-
Function. Consider, for example, the output from the fft1 X-Function:
// Send ReportData output to Book2, Sheet3.
fft1 rd:=[book2]sheet3!;
// Send ReportData output to a new sheet in Book2.
fft1 rd:=[book2]<new>!;
// Send ReportData output to Column 4 in the active workbook/sheet.
fft1 rd:=[<active>]<active>!Col(4);
// Send ReportData output to a new sheet in the active workbook.
fft1 rd:=[<active>]<new>!;
// Send ReportData output to a tree variable named tr1;
// If 'tr1' does not exist, it will be created.
fft1 rd:=tr1;

Sending ReportData to Tree Variable

Often, you may need the ReportData output only as an intermediate variable and thus may prefer not
to involve the overhead of a worksheet to hold such data temporarily.
One alternative then is to store the datasets that make up the Report Data object using a Tree
variable, which already supports bundling of multiple vectors, including support for additional
attributes for such vectors.
The output range specification for a worksheet is usually in one of the following forms: [Book]Sheet!,
<new>, or <active>. If the output string does not have one of these usual book-sheet specifications,
then the output is automatically considered to be a LabTalk Tree name.
The following is an example featuring the avecurves X-Function. In this example, the resulting
ReportData object is first output to a tree variable, and then one vector from that tree is placed at a
specific column-location within the same sheet that houses the input data. ReportData output typically
defaults to a new sheet.
int nn = 10;
col(1)=data(1,20); //fill some data
loop(i,3,nn){wcol(i)=normal(20);};
range ay=col(2); //for 'avecurves' Y-output
Tree tr; // output Tree
avecurves (1,3:end) rd:=tr;
// Assign tree node (vector) 'aveY' to the range 'ay'.
// Use 'tr.=' to see the tree structure.
ay=tr.Result.aveY;
ay[L]$="Ave Y"; // set its LongName
// Plot the raw data as scatter-plot using the default-X.
plotxy (?,3:end) p:=201;
// Add the data in range 'ay' to the same as line-plot.
plotxy ay o:=<active> p:=200;

Sending ReportData Directly to a Specific Book/Sheet/Column Location

If you are happy with simply putting the result from the X-Function into the input sheet as new
columns, then you can also do the following:
avecurves (1,2:5) rd:=[<input>]<input>!<new>;
Or if you would like to specify a particular column of the input sheet in which to put the ReportData
output, you may specify that as well:
avecurves (1,2:5) rd:=[<input>]<input>!Col(3);
Subsequent access to the data is more complicated, as you will need to write additional code to find
these new columns.

82
 Calling X-Functions and Origin C Functions

Realize that output of the ReportData type will contain different amounts (columns) of
data depending on the specific X-Function being used. If you are sending the results
to an existing sheet, be careful not to overwrite existing data with the ReportData
columns that are generated.

4.2.4 X-Function Execution Options

4.2.4.1 X-Function Option Switches
The following option switches are useful when accessing X-Functions from script:
Switch Full Name Function

Copy column format of the input range, and apply it to the

-cf --
output range.

-d -dialog Brings up a dialog to select X-Function parameters.

Variation of dialog; Brings up the X-Function dialog as a panel

-db --
in the current workbook.

Variation of dialog; Brings up a dialog to select X-Function

parameters. Set IsCancel to 0 if click the OK button, set to 1 if
-dc IsCancel -- click the Cancel button. When clicking the Cancel button, no
error message like #User Abort! dumps to Script Window and
the script after X-Function can be executed.

Open the X-Function in the X-Function Builder. This works the

-e --
same as the edit -x command.

-h -help Prints the contents of the help file to the Script window.

Loads and compiles the X-Function without doing anything

-hn -- else. If the X-Function has already been compiled and loaded,
it will do nothing.

-hs -- Variation of -h; Prints only the Script Usage Examples.

Variation of -h; Prints only the Treenode information, if any

-ht --
exists.

-hv -- Variation of -h; Prints only the Variable list.

-hx -- Variation of -h; Prints only the related X-Function information.

-r 1 -recalculate 1 Sets the output to automatically recalculate if input changes.

Sets the output to recalculate only when manually prompted to

-r 2 -recalculate 2
do so.

-s -silent Runs in silent mode; results are not sent to Results log.

83
 LabTalk Scripting Guide

Variation of -s; suppresses error messages and Results log

-sb --
output.

Variation of -s; suppresses error messages, does not

-se --
suppress Results log output.

-sl -silent Same as -s.

Variation of -s; suppresses info messages to the script

-ss --
window.

-t <Name> -theme Uses the designated preset theme.

Recalculate is not supported when <input> is used an an <output>.
For options with an existing Full Name, either the shortened switch name or the full name may be
used in script. For instance, for the X-Function smooth,
smooth -h
is the same as
smooth -help

4.2.4.2 Examples

Using a Theme

Use the theme named FivePtAdjAve to perform a smoothing operation on the XY data in columns 1
and 2 of the active worksheet.
smooth (1,2) -t FivePtAdjAve
Note: A path does not need to be specified for the theme file since Origin automatically saves and
retrieves your themes. Themes saved in one project (*.OPJ) will be available for use in other projects
as well.

Setting Recalculate Mode

Set the output column of the freqcounts X-Function to automatically recalculate when data in the
input column changes.
freqcounts irng:=col(1) min:=0 max:=50 stepby:=increment inc:=5
end:=0 count:=1 center:=1 cumulcount:=0 rd:=col(4) -r 1;
// Set Recalculate to Auto with '-r 1'.

Open X-Function Dialog

While running an X-Function from script it may be desirable to open the dialog to interactively supply
input. In this simple example, we perform a smoothing operation using a percentile filter (method:=2)
and specifying a moving window width of 25 data points. Additionally, we open the dialog (-d)
associated with the smooth X-Function allowing the selection of input and output data, among other
options.
smooth method:=2 npts:=25 -d

Copy Format from Input to Output

Use an FFT filter with the -cf option switch to format the output data to match that of the input data:

84
 Calling X-Functions and Origin C Functions

// Import a *.wav file; imported *.wav data format is short(2).

fname$ = system.path.program$ + "Samples\Signal Processing\sample.wav";
newbook s:=0; newsheet col:=1; impWav options.SparkLines:=0;
string bkn$=%H;

// By default, all analysis results are output as datatype double.

// -cf is used here to make sure the output data to be short(2)
fft_filters -cf [bkn$]1!col(1) cutoff:=2000
oy:=(<input>,<new name:="Lowpass Sound Frequency">);

4.2.5 X-Function Exception Handling

The example below illustrates trapping an X-Function error with LabTalk, so that an X-Function call
that is likely to generate an error does not break your entire script.
For X-Functions that do not return an error code, two functions exist to check for errors in the last
executed X-Function: xf_get_last_error_code() and xf_get_last_error_message()$. These
functions should be used in situations where the potential exists that a particular X-Function could
fail.
In this example, the user is given the option of selecting a file for import, but if that import fails (e.g.
user picked file type inappropriate for the import) we need to handle the remaining code.
dlgfile gr:=*.txt; // Get the file name and path from user
impasc -se; // Need to use -se switch for execution to continue, see note
below
if( 0 != xf_get_last_error_code() )
{
strError$ = "XFunction Failed: " + xf_get_last_error_message()$;
type strError$;
break 1; // Stop execution
}
// Data import probably succeeded, so our script can continue
type continuing...;
Note the use of the general X-Function option -se to suppress error messages. You can also use -sl
to suppress error logging and -sb to suppress both. It is necessary to use one of these options in
order for script execution to continue to the next line when the X-Function call fails.

4.2.5.1 Looping Over to Find Peaks

In the following example, we loop over all columns in a worksheet to find peaks. If no peak is found in
a particular column, the script continues with the rest of the columns. It is assumed here that a
worksheet with suitable data is active.
for(int ii=2; ii<=wks.ncols; ii++)
{
// Find peak in current column, suppress error message from XF
Dataset mypeaks;
pkfind $(ii) ocenter:=mypeaks -se; // Need to use -se for execution to
continue

// Check to see if XF failed

if( 0 != xf_get_last_error_code() )
{
type "Failed on column $(ii): %(xf_get_last_error_message()$)";
}
else
{
type Found $(mypeaks.getsize()) peaks in column $(ii);

85
 LabTalk Scripting Guide

}
}

4.3 Origin C Functions

4.3.1 Origin C Functions
The following subsections detail how to call Origin C functions from your LabTalk scripts.

This chapter covers the following topics:

 Loading and Compiling Origin C Functions

 Passing Variables To and From Origin C Functions

 Updating an Existing Origin C File

 Using Origin C Functions

4.3.2 Loading and Compiling Origin C Functions

4.3.2.1 Loading and Compiling Origin C Function or Workspace
Before you call your Origin C function from Origin, your function must be compiled and linked in the
current Origin session. To programmatically compile and link a source file, or to programmatically
build a workspace from a LabTalk script use the run.loadOC method of the LabTalk run object.
err = run.LoadOC("myFile",[option]);

Example

Use option to scan the .h files in the OC file being loaded, and all other dependent OC files are also
loaded automatically:
// Load and compile Origin C function in the file iw_filter.c
// with the option=16, so to also load all dependent Orign C
// files by scanning for .h files included in iw_filter.c
if(run.LoadOC(OriginLab\iw_filter.c, 16) != 0)
{
type "Failed to load iw_filter.c!";
return 0;
}
Now, open Code Builder by menu View: Code Builder, and in the Workspace panel (if not see this
panel, open by View: Workspace menu item in Code Builder) of Code Builder, you can see the
iw_filter.c file is under the Temporary folder.

4.3.2.2 Adding Origin C Source Files to System Folder

86
 Calling X-Functions and Origin C Functions

Once a file has been opened in Code Builder, one can simply drag and drop the file to the System
branch of the Code Builder workspace. This will then ensure that the file will be loaded and compiled
in each new Origin session. For more details, please refer to Code Builder documentation.
You can programmatically add a source file to the system folder so that it will be available anytime
Origin is run.
run.addOC(C:\Program Files\Originlab\Source Code\MyFunctions.c);
This can be useful when distributing tools to users or making permanently available functions that
have been designed to work with Set Column Values.

4.3.2.3 Adding Origin C Files to Project (OPJ)

Origin C files (or files with any extension/type) can also be appended to the Origin project (OPJ) file
itself. The file will then be saved with the OPJ and extracted when the project is opened. In case of
Origin C files, the file is then also compiled and linked, and functions within the file are available for
access. To append a file to the project, simply drag and drop the file to the Project branch of Code
Builder or right-click on Project branch and add the file. For more details, please refer to Code Builder
documentation.

4.3.3 Passing Variables To and From Origin C Functions

When calling a function of any type it is often necessary to pass variables to that function and
likewise receive variables output by the function. The following summarizes the syntax and
characteristics of passing LabTalk variables to Origin C functions.

4.3.3.1 Sytnax for calling Origin C Function from LabTalk

Origin C functions are called from LabTalk with sytnax such as:
// separate parameters by commas (,) if more than one
int iret = myfunc(par1, par2....);

// no need for parentheses and comma if there is no assignment

myfunc par1;

// function returns no value, and no parameter, parentheses optional

myfunc;

4.3.3.2 Variable Types Supported for Passing To and From LabTalk

The following table lists Origin C variable types that can be passed to and from LabTalk when calling
an Origin C Function:
Variable Type Argument to OC Function Return from OC Function

double Yes Yes

int Yes Yes

bool (true or No, pass int instead, 0 for false, and other No, return int instead, 0 for
false) integer for true. false, 1 for true.

string Yes Yes

int, double
Yes Yes
array

87
 LabTalk Scripting Guide

string array Yes, but cannot pass by reference Yes

Note:
1. The maximum number of arguments that Origin C function can have to call from LabTalk is 80.

2. LabTalk variables can be passed to Origin C numeric function by reference.

4.3.4 Updating an Existing Origin C File

4.3.4.1 Introduction
There are cases where a group leader or a developer wants to release a new version of an Origin C
file to other Origin users. In such cases, if the end users have already installed an older version of the
Origin C file, they will have a corresponding .OCB file in their User Files Folder (UFF). It is possible
that the time stamp of the new Origin C file is older than the time stamp of the .OCB file. When this
happens Origin will think the .OCB file is already updated and will not recompile the new Origin C file.
To avoid this possible scenario it is best to delete the .OCB file when the new Origin C file is installed.
Once deleted, Origin will be forced to remake the .OCB file and will do so by compiling the new Origin
C file.

4.3.4.2 Manually Deleting OCB Files

The OCB file corresponding to the Origin C file in question, can be manually deleted from the
OCTEMP folder in the Users Files Folder on the end user's computer. Depending on the location of
the Origin C file, it is possible for the OCB file to be in nested subfolders within the OCTemp folder.
Once located, the end user can delete the OCB file and rebuild their workspace to create an updated
OCB file.

4.3.4.3 Programmatically Deleting OCB Files

A group leader or developer can programmatically delete the corresponding OCB files using
LabTalk's Delete command with the OCB option. This is very useful when distributing Origin C files in
an Origin package and it is not acceptable to have the end user manually delete the .OCB files.
Below are some examples of how to call LabTalk's Delete command with the OCB option:
del -ocb filepathname1.c
del -ocb filepathname1.ocw
del -ocb filepathname1.c filepathname2.c // delete multiple files
del -ocb %YOCTEMP\filename.c // use %Y to get to the Users Files Folder

4.3.5 Using Origin C Functions

To extend the functions, you can also define an Origin C function (see Creating and Using Origin C
Code for details) which returns a single value, and call the function from command window. For
example,
1. Open Code Builder by menu View: Code Builder.

2. In Code Builder, create a new *.c file by menu File: New. In the New File dialog, give a file

name, MyFuncs for example, and click OK.

3. Start a new line at the end of this new file, and add the following code.

88
 Calling X-Functions and Origin C Functions

double MyFunc (double x)

{
return sin(x) + cos(x);
}
4. Click menu item Build: Build to compile and link the file.

5. If no error, the function defined above is now available in LabTalk. Run the following script in

the Command Window.

newbook; // create a new workbook

col(A) = data(1, 32); // fill row number
col(B) = MyFunc(col(A)); // call the Origin C function, result is put
to column B

89
5 Running and Debugging LabTalk Scripts

5.1 Running and Debugging LabTalk Scripts

This chapter covers the following topics:

 LT Running Scripts

 LT Debugging Scripts

Origin provides several options for executing and storing LabTalk scripts. The first part of this chapter
profiles these options. The second part of the chapter outlines the script debugging features
supported by Origin.

5.2 Running Scripts

5.2.1 Running Scripts
The following sections document various ways to execute and/or store LabTalk scripts. We begin by
examining the relationship between scripts and the objects they work on.

This section covers the following topics:

 From Script and Command Window

 From Files

 From Set Values Dialog

 From Worksheet Script

 From Script Panel

 From Graphical Objects

 ProjectEvents Script

91
 LabTalk Scripting Guide

 From Import Wizard

 From Nonlinear Fitter

 From an External Application

 From Console

 On A Timer

 On Starting or Exiting Origin

 From a Custom Menu Item

 From a Toolbar Button

Active Window Default

When working on an Origin Object, like a workbook or graph page, a script always operates on the
active window by default. If the window is inactive, you may use win -a to activate it.
win -a book2; // Activate the window named book2
col(b) = {1:10}; // Fill 1 to 10 on column B of book2
However, working on active windows with win -a may not be stable. In the execution sequence of the
script, switching active windows or layers may have delay and may lead to unpredictable outcome.
It is preferable to always use win -o winName {script} to enclose the script, then Origin will temporarily
set the window you specified as the active window (internally) and execute the enclosed script
exclusively on that window. For example, the following code will create a new project, fill the default
book with some data, and make a plot and then go back to add a new sheet into that book and make
a second plot with the data from the second sheet:
doc -s;doc -n;//new project with default worksheet
string bk$=%H;//save its book short name
//fill some data and make new plot
wks.ncols=2;col(1)=data(1,10);col(2)=normal(10);
plotxy (1,2) o:=<new>;
//now the newly created graph is the active window
//but we want to run some script on the original workbook
win -o bk$ {
newsheet xy:="XYY";
col(1)=data(0,1,0.1);col(2)=col(1)*2;col(3)=col(1)*3;
plotxy (1,2:3) plot:=200 o:=<new>;
}
Please note that win -o is the only LabTalk command that allows a string variable to be used. As seen
above, we did not have to write
win -o %(bk$)
as this particular command is used so often that it has been modified since Origin 8.0 to allow string
variables. In all other places you must use the %( ) substitution notation if a string variable is used as
an argument to a LabTalk command.
Where to Run LabTalk Scripts

92
 Running and Debugging LabTalk Scripts

While there are many places in Origin that scripts can be stored and run, they are not all equally
likely. The following sub-sections have been arranged in an assumed order of prevalence based on
typical use.
The first two, on (1) Running Scripts from the Script and Command Windows and (2) Running Scripts
from Files, will be used much more often than the others for those who primarily script. If you only
read two sub-sections in this chapter, it should be those. The others can be read on an as-needed
basis.

5.2.2 From Script and Command Window

Two Windows exist for direct execution of LabTalk: the (older) Script Window and the (newer)
Command Window. Each window can execute single or multiple lines of script. The Command
Window has a prompt and will execute all code entered at the prompt.
The Script Window has only a cursor and will execute highlighted code or code at the current cursor
position when you press Enter. Both windows accept Ctrl+Enter without executing. When using
Ctrl+Enter to add additional lines, you must include a semicolon (;) at the end of a statement. You
can also turn Script Execution off or on in the Edit menu by selecting Script Execution:None.
The Command Window includes Intellisense for auto-completion of X-Functions, a command history
and recall of line history (Up and Down Arrows) while the Script Window does not. The Script Window
allows for easier editing of multiline commands and longer scripts.
Below is an example script that expects a worksheet with data in the form of one X column and
multiple Y columns. The code finds the highest and lowest Y values from all the Y data, then
normalizes all the Y's to that range.
// Find the lowest minimum and the highest maximun
double absMin = 1E300;
double absMax = -1E300;
loop(ii,2,wks.ncols)
{
stats $(ii);
if(absMin > stats.min) absMin = stats.min;
if(absMax < stats.max) absMax = stats.max;
}
// Now normalize each column to that range
loop(ii,2,wks.ncols)
{
stats $(ii);
wcol(ii)-=stats.min; // Shift to minimum of zero
wcol(ii)/=(stats.max - stats.min); // Normalize to 1
wcol(ii)*=(absMax - absMin); // Normalize to range
wcol(ii)+=absMin; // Shift to minimum
}
To execute in the Script Window, paste the code, then select all the code with the cursor (selected
text will be highlighted), and press Enter.
To execute the script in the Command Window, paste the code then press Enter. Note that if there
were a mistake in the code, you would have it all available for editing in the Script Window, whereas
the Command Window history is not editable and the line history does not recall the entire script.

Origin also has a native script editor, Code Builder, which is designed for editing and
debugging both LabTalk and Origin C code. To access Code Builder, enter ed.open()
into the script or command window, or select the button from the Standard
Toolbar.

93
 LabTalk Scripting Guide

The font in Script Window can be customized in this way:

1. Open the Origin.ini file in User Files Folder, search for the [font] section: paste

the contents below in [font] section.

2. Restart the Origin and check the Script Window again, the font and size both

changed.

ScriptWindowFontHeight=24
ScriptWindowCharset=0
ScriptWindowFaceName=Times New Roman
For more charset value, see http://msdn.microsoft.com/en-us/library/cc250412.aspx

5.2.3 From Files

LabTalk script usually requires an Origin Object and are thus restricted to an open project. Scripts
can also be saved to a file on disk to be called from any project. Script files can be called with up to
five arguments. This section outlines the use of LabTalk scripts saved to a file.

5.2.3.1 Creating and Saving Script Files

LabTalk scripts can be created and saved from any text editor, including Origin's Code Builder. To
access Code Builder, select the icon from the Standard Toolbar. Create a new document of type
LabTalk Script File and type or paste your code into the editor window and then save with a desired
filename and path (use the default OGS file extension).

5.2.3.2 The OGS File Extension

LabTalk scripts can be saved to files and given any extension, but for maximum flexibility they are
given the OGS file extension, and are therefore also known as OGS files. You may save script files
to any accessible folder in your file system, but specific locations may provide additional advantages.
If an OGS file is located in your User Files Folder, you will not have to provide a path when running
your script.

An OGS file can also be attached to the Origin Project (OPJ) rather than saving it to
disk. The file can be added to the Project node in Code Builder and will then be saved
with the project. Drag the filename from the User folder and drop into the Project
folder. Script sections in such attached OGS files can be called using the
run.section() object method similar to calling sections in a file saved on disk. Only the
file name needs to be specified, as Origin will first look for the file in the project itself
and execute the code if filename and section are found as attachments to the project.

5.2.3.3 Sections in an OGS File

Script execution is easier to follow and debug when the code is written in a modular way. To support
modular scripting, LabTalk script files can be divided into sections, which are declared by placing the
desired section name in square brackets [ ] on its own line:
[SectionName]
Lines of script under the section declaration belong to that section. Execution of LabTalk in a section
ends when another section declaration is met, when a return statement is executed or when a

94
 Running and Debugging LabTalk Scripts

Command Error occurs. The framework of a typical multi-section OGS file might look like the
following:
[Main]
// Script Lines
ty In section Main;

[Section 1]
// Script Lines
ty In section 1;

[Section 2]
// Script Lines
ty In section 2;
Note here that ty issues the type command, which is possible since no other commands in Origin
begin with the letters 'ty'.

5.2.3.4 Running an OGS File

You can use the run object to execute script files or in certain circumstances LabTalk will interpret
your file name as a command object. To use a file as a command object, the file extension must be
OGS. See the Note below for additional information.
Compare the following call formats:
run.section(OGSFileName, SectionName[,arg1 arg2 ... arg5])
run.file(OGSFileName[ arg1 arg2 ... arg5] )
OGSFileName.SectionName [arg1 arg2 ... arg5]
OGSFileName [arg1 arg2 ... arg5]
Specifically, if you save a file called test.ogs to your Origin User Files folder:
// Runs [Main] section of test.ogs using command syntax, else runs
// unsectioned code at the beginning of the file, else does nothing.
test;

// Runs only section1 of test.ogs using command syntax:

test.section1;

// Runs only section1 of test.ogs with run.section() syntax:

run.section(test, section1)
Note: After saving the OGS file, you need to run the cd X-Function (cd 1;) to change to the folder
where the file was saved or use dir to list files in the current working folder - if that is where the file is.
Otherwise, Origin does not detect the file and will not see it as a runnable command.
After Origin recognizes an OGS filename as an object, run the OGS file by entering its name or
name.sectionname into the Script Window or Command Window. If either the file name or section
name contains a space quotes must surround both. For example:
// Run a LabTalk Script named 'My Script.ogs' located in the folder
//'D:\OgsFiles'.

// Change the current directory to 'D:\OgsFiles'

cd D:\OgsFiles; // This causes Origin to scan that folder for OGS files
// This runs the code in section 'Beta Test' of 'My Scripts.ogs'
// passing three arguments separated by spaces (protected by quotes where
needed)
"My Scripts.Beta Test" "Redundant Test" 5 "Output Averages";
There are many examples in Origin's Samples\LabTalk Script Examples folder which can be
accessed by executing:
cd 2;

95
 LabTalk Scripting Guide

5.2.3.5 Passing Arguments in Scripts

When you use the run.section() object method to call a script file (or one of its sections) or a macro,
you can pass arguments with the call. Arguments can be literal text, numbers, numeric variables, or
string variables.
When passing arguments to script file sections or to macros:
 The section call or the macro call must include a space between each argument being passed.

When using run.section, a comma must separate the section name from the first argument

only.

 When you pass literal text or string variables as arguments, each argument must be

surrounded by quotation marks (in case the argument contains more than one word, or is a

negative value). Passing numbers or numeric variables doesn't require quotation mark

protection, except when passing negative values.

 You can pass up to five arguments, separated by Space, to script file sections or macros. In

the script file section or macro definition, argument placeholders receive the passed arguments.

These placeholders are %1, %2, %3, %4, and %5. The placeholder for the first passed

argument is %1, the second is %2, etc. These placeholders work like string variables in that

they are substituted prior to execution of the command in which they are embedded. The

number of arguments passed is contained in macro.narg.

As an example of passing literal text as an argument that is received by %1, %2, etc., Suppose a
TEST.OGS file includes the following section:
[output]
type "%1 %2 %3";
and you execute the following script:
run.section(test.ogs, output, "Hello World" from LabTalk);
Here, %1 holds "Hello World", %2 holds "from", and %3 holds "LabTalk". After string substitution,
Origin outputs
Hello World from LabTalk
to the Script window. If you had omitted the quotation marks from the script file section call, then %1
would hold "Hello", %2 would hold "World", and %3 would hold "from". Origin would then output
Hello World from

Passing Numeric Variables by Reference

Passing numeric variable arguments by reference allows the code in the script file section or macro to
change the value of the variable.
For example, suppose your application used the variable LastRow to hold the row number of the last
row in column B that contains a value. Furthermore, suppose that the current value of LastRow is 10.
If you pass the variable LastRow to a script file section whose code appends five values to column B
(starting at the current last row), after appending the values, the script file section could increment the
value of the LastRow variable so that the updated value of LastRow is 15.

96
 Running and Debugging LabTalk Scripts

See example:
If a TEST.OGS file includes the following section:
[adddata]
loop (n, 1, 5)
{
%1[%2 + n] = 100;
};
%2 = %2 + (n - 1);
return 0;
And you execute the following script:
col(b) = data(1, 10); // fill data1_b with values
get col(b) -e lastrow; // store last row of values in lastrow
run.section(test.ogs, adddata, col(b) lastrow);
lastrow = ;
Then LastRow is passed by reference and then updated to hold the value 15.

Passing Numeric Variables by Value

Passing numeric variable arguments by value is accomplished by using the $() substitution notation.
This notation forces the interpreter to evaluate the argument before sending it to the script file section
or macro. This technique is useful for sending the value of a calculation for future use. If the
calculation were sent by reference, the entire expression would require calculation each time it was
interpreted.
In the following script file example, numeric variable var is passed by reference and by value. %1 will
hold the argument that is passed by reference and %2 will hold the argument that is passed by value.
Additionally, a string variable (%A) consisting of two words is sent by value as a single argument
to %3.
[typing]
type -b "The value of %1 = %2 %3";
return 0;
Save the section to Test.OGS and run the following script on command window:
var = 22;
%A = "degrees Celsius";
run.section(test.ogs, typing, var $(var) "%A");
Then a dialog box pop-up and says: "The value of var = 22 degrees Celsius".

5.2.3.6 Guidelines for Naming OGS Files and Sections

Naming rules for OGS script files differ based on how they will be called. The section above
discusses the two primary methods: calling using the run.section() method or calling directly from
the Script or Command window (the command method).

When Using the Run.section() Method

 There is no restriction on the length or type of characters used to name the OGS file.

 Specifying the filename extension is optional for files with the OGS extension.

 When using run.section( ) inside an OGS file to call another section of that same OGS file, the

filename may be omitted, for instance:

97
 LabTalk Scripting Guide

[main]
run.section( , calculate);

[calculate]
cc = aa + bb;

When Using the Command Method

 The name of the OGS file must conform to the restrictions on command names: 25 characters

or fewer, must not begin with a number or special character, must not contain spaces or

underscore characters.

 The filename extension must be OGS and must not be specified.

Section Name Rules (When Using Either Method)

 When SectionName is omitted,

1. Origin looks for a section named main and executes it if found

2. If no main section is found, but code exists at the beginning of the file without a

section name, then that code is executed

3. Otherwise Origin does nothing and does not report an error

Do not give an OGS file the same name as an existing Origin function or X-Function!

5.2.3.7 Setting the Path

In Origin 7.5, script files (*.OGS) could be run from both the Origin System and User Files folders,
and these are the current working directory by default. If your script file resides there, there is no
need to change the path. If the script file was not located in either of these two folders, the full path
needed to be specified in the run.section() object method. Since Origin 8, the idea of the Current
Working Folder (CWF) was introduced, allowing you to run your own script files and X-Functions
located in the CWF you have specified.
Per MS-DOS convention, Origin uses the cd X-Function to display the CWF:
// Entering this command displays the current working folder
// in the Script Window.
cd
and unless it has been changed, the output is similar to:

current working directory:

C:\Documents and Settings\User\My Documents\OriginLab\Origin8.1\User Files\
However, if you write many scripts, you will want to organize them into folders, and call these scripts
from where they reside. Also, Origin provides sample scripts that you may want to run from their
respective directories.

98
 Running and Debugging LabTalk Scripts

In the case or run.section( ) scripts can reside in subfolders of the User Files Folder and you can use
relative referencing such as:
run.section(subfolder1\scriptA,main); // ScriptA.ogs is in subfolder1
run.section(subfolder2\scriptA,main); // ScriptA.ogs is in subfolder2
You can set the Current Working Folder from script. For example, to run an OGS file named
ave_curves.ogs, located in the Origin system sub-folder Samples\LabTalk Script Examples, enter
the following:
// Create a string variable to hold the complete path to the desired
//script file
// by appending folder path to Origin system path:
path$ = system.path.program$ + "Samples\LabTalk Script Examples\";
// Make the desired path the current directory.
cd path$;
// Call the function
ave_curves;
You can create a set of pre-defined paths. The cdset X-Function is used to list all the pre-defined
paths and add/change the CWF. By typing
// The 'cdset' command displays pre-defined paths
//in the Script Window.
cdset
you should see three paths like below if you have not changed them yet.

1 = C:\Documents and Settings\User\My Documents\OriginLab\Origin8.1\User

Files\
2 = C:\Program Files\OriginLab\Origin81\Samples\LabTalk Script Examples\
3 = C:\Program Files\OriginLab\Origin81\
If you want to set the second path above to be the CWF, just type:
// Changes the CWF to the folder path specified
// by pre-defined path #2.
cd 2
To add a new path to pre-defined folder set, first change to the new path, making it the CWF, then
add it to the set by using cdset X-Function with the specified index. For example:
cd D:\Files\Filetype\Script; // Set this new path as CWF
// Add this path to pre-defined folder list, to the 4th postion (index 4)
// If there already is a path with index 4, it will be over-written
cdset 4;
// If the CWF is changed manually, it can now be reset to
// 'D:\Files\Filetype\Script\' by entering 'cd 4'.

A few tips for working with the cdset command:

 Folder paths added to the pre-defined set in one project are saved for use with

other projects.

 To see the current paths displayed to the Script Window, enter 'cdset' by itself

on a line in the Script Window.

 Up to 9 pre-defined paths are supported.

 Indices can be assigned out of order.

99
 LabTalk Scripting Guide

 A new path, assigned to an index for which a current path exists, will overwrite

the current path.

As the three default pre-defined paths show above, the second one contains several sample script
files (with the OGS extension). Similar to DOS, you can go to this folder by cd 2, then see the valid
OGS using the dir X-Function, and then run any available script file in this folder, such as:
// Set 2nd folder as the CWF
cd 2;
// List all ogs and X-Function in the CWF
dir;
// Run a script file
// Note that the file extension is not needed when calling it
autofit;
You can also load the script file in the CWF into Code Builder by using ed.open() method. Such as:
// In this case, the OGS extension on the filename is required!
ed.open(pick_bad_data.ogs)

5.2.3.8 Running LabTalk from Origin C

Besides running .OGS files directly, LabTalk commands and scripts can also be run from Origin C.
For more information, please refer to LabTalk Interface global function of Origin C help document.

5.2.4 From Set Values Dialog

The Set Values Dialog is useful when calculations on a column of data are based on functions that
may include references to other datasets.
The column designated by Set Values is filled with the result of an expression that you enter (the
expression returns a dataset). The expression can be made to update automatically (Auto), when
requested by the user (Manual), or not at all (None).
For more complex calculations, where a single expression is not adequate, a Before Formula Scripts
panel in the dialog can include any LabTalk script.
Auto and Manual updates create lock icons, and respectively, at the top of the column. A green
lock indicates updated data; A yellow lock indicates pending update; A red lock indicates broken
functionality.
In cases where the code is self-referencial (i.e. the column to be set is included in the calculation) the
Auto and Manual options are reset to None.
Below are two examples of script specifically for the Set Values Dialog. Typically short scripts are
entered in this dialog.

Expression using another column

While limited to expressions (the right side of an equation) as in:

// In column 3
// Scale a column - useful for fitting where very large
//or very small numbers are problematic
col(2)*1e6;
the conditional expression can be useful in some situations:
// Set negative values to zero
col(2)<0?0:col(2);

100
 Running and Debugging LabTalk Scripts

Using Before Formula Scripts Section

In the Before Formula Scripts section of the Set Column Values dialog, a script can be entered
that will be executed by Origin just before the formula itself is executed. This feature is useful for
carrying out operations that properly setup the formula itself. The following example demonstrates the
use of such a script:
// In column BaseNormal
// In the expression section ..
BN
// In the Before Formula Scripts section ..
range raR = col(Reading); // The signal
range raB = col(Baseline); // The Baseline
dataset BN;
BN = raR - raB; // Subtract the baseline from the signal
stats BN; // Get statistics of the result
BN /= (stats.max / 100); // Normalize to maximum value of 100
The following image is a screenshot of the code above entered into the Set Column Values dialog:

5.2.5 From Worksheet Script

The Worksheet Script dialog is mostly provided for backward compatibility with older versions of
Origin that did not have the Auto Update feature in the Set Values dialog and/or did not have import
filters where scripts could be set to run after import.
Scripts can be saved in a Worksheet (so workbooks have separate Worksheet Scripts for each sheet)
and set to run after either importing into this Worksheet and/or changes in a particular dataset (even
one not in this Worksheet).

101
 LabTalk Scripting Guide

Here is a script that is attached to Sheet3 which is set to run on Import (into Sheet3) or when the A
column of Sheet2 changes.
range ra1 = Sheet1!1;
range ra2 = Sheet1!2;
range ra3 = Sheet2!A; // Our 'Change in Range' column
range ra4 = 3!2; // Import could change the sheet name ..
range ra5 = 3!3; // .. so we use numeric sheet references
ra5 = ra3 * ra2 / ra1 * ra4;

5.2.6 From Script Panel

The Script Panel (accessed via the context menu of a Workbook's title bar) is a hybrid of the Script
Window and Command Window.
 Like the Script Window, it can hold multiple lines and you can highlight select lines and press

Enter to execute.

 Like the Command Window, there is a history of what has been executed.

 Unlike the Script window, whose content is not saved when Origin closes, these scripts are

saved in the project.

// Scale column 2 by 10
col(2)*=10;

// Shift minimum value of 'mV' column to zero

stats col(mV);
col(mV)-=stats.min;

// Set column 3 to column 2 normalized to 1

stats 2;
col(3) = col(2)/stats.max;

5.2.7 From Graphical Objects

Graphic Objects (text, lines and shapes) can be tied to events and contain script that runs on those
events or by using the run method for those objects. Since graphical objects are attached to a page,
they are saved in Templates, Window files and Project files.

5.2.7.1 Buttons
Some of your scripts may be used so often that you would like to automate their execution by
assigning one or more of them to a button on the Origin project's graphical-user interface (GUI). To
do so, follow the steps below:
From a new open Origin project:

1. Select the text tool from the tool menu on the left side of the project window -->

2. Now click in the open space to the right of the two empty columns of the blank worksheet in the

Book1 window. This will open a text box. Type "Hello" in the text box and click outside the box-

-you have now created a label for the button.

102
 Running and Debugging LabTalk Scripts

3. Now hold down the ALT key while double-clicking on the text that you just created. A window

called Programming Control will appear.

4. Not that there is an Object Name in the upper left of the dialog. Change this to Greeting.

5. In the lower text box of the Programming Control window, enter our script:

type -b "Hello World";

6. Also in the Programming Control window, in the Script, Run After box, select Button Up,

and click OK.

7. You have now created a button that, when pressed, executes your script and prints "Hello

World" in a pop-up window.

Unlike a text script which exists only in the Classic Script Window, this button and the script it runs
will be saved when you save your Origin project.
The script behind any graphic object an be run using its name and the run method. Open the
Command Window and type:
greeting.run()
and press Enter.

5.2.7.2 Lines
Here is a script that creates a vertical line on a graph that can be moved to report the interpolated
value of your data at the X position represented by the line:
// Create a vertical line on our graph
draw -n MyCursor -l -v $(x1+(x2-x1)/2);
MyCursor.HMOVE = 1; // Allow horizontal movement
MyCursor.color = color(orange); // Change color to orange
MyCursor.linewidth = 3; // Make line thicker
// Add a label to the graph
label -sl -a $(MyCursor.x) $(Y2+0.05*(Y2-Y1)) -n MyLabel $(%C(MyCursor.x));
// Assign a script to the line ..
MyCursor.script$="MyLabel.x = MyCursor.x;
MyLabel.y = Y2 + MyLabel.dy;
doc -uw;";
// .. and make the script run after the line is moved
MyCursor.Script = 2;

5.2.7.3 Other Objects

Any Graphical Object (text, lines and shapes) can have an attached script that runs when an event
occurs.
In this example, a rectangle (named RECT) on a graph is set to have a script run when the rectangle
is either Moved or Sized.
1. Use the Rectangle tool on the Tools toolbar to draw a rectangle on a graph.

2. Use the Back(data) tool on the Object Edit toolbar to push the rectangle behind the data.

103
 LabTalk Scripting Guide

3. Hold down the Alt key and double-click on the rectangle to open Programming Control. Note

that the objects name is Rect.

4. Enter the following script:

%B = %C;
%A = xof(%B);
dataset dsRect;
dsRect = ((%A >= rect.x1) && (%A <= rect.x2) &&
(%B >= rect.y3) && (%B <= rect.y1))?%B:0/0;
stats dsRect;
delete dsRect;
type -a Mean of $(stats.mean);
5. Choose the Moved or Sized event in the Script, Run After drop down list.

6. Click OK.

When you Move or Resize this rectangle, the script calculates the mean of all the points within the
rectangle and types the result to the Script Window. You can also define a Graphic Object range and
run the script like:
GObject gobj = [Graph1]1!rect;
gobj.run();

5.2.8 ProjectEvents Script

You may want to define functions, perform routine tasks, or execute a set of commands, upon
opening, closing, or saving your Origin project. In Origin 8.1 a file named ProjectEvents.ogs is
attached to the Origin Project (OPJ) by default.
A template version of this file is shipped with Origin and is located in the EXE folder. This template file
is attached to each new project. The file can be viewed and edited by opening Code Builder and
expanding the Project node in the left panel.

5.2.8.1 Sections of ProjectEvents.ogs

The ProjectEvents.ogs file, by default, contains three sections that correspond to three distinct
events associated with the project:
1. AfterOpenDoc: This section will be executed immediately after the project is opened

2. BeforeCloseDoc: This section will be executed before the project is closed

3. BeforeSaveDoc: This section will be executed before the project is saved

5.2.8.2 Utilizing ProjectEvents.ogs

In order for this file and its contents to have an effect, a user needs to edit the file and save it in Code
Builder, and then save the project. The next time the project is opened, the script code contained in
this attached OGS file will be executed upon the specified event (given by the pre-defined section
name).
For example, if a user defines a new function in the [AfterOpenDoc] section of ProjectEvents.ogs,
saves it (in Code Builder), and then saves the project in Origin, that function will be available (if
defined to be global) for use any time the project is re-opened. To make the function available in the
current session place the cursor (in Code Builder) on the section name to execute, select the Debug

104
 Running and Debugging LabTalk Scripts

drop-down menu, and select the Execute Current Section option. Then in the Origin Script Window,
issuing the list a command will confirm that the new function appears and is available for use in the
project.
A brief tutorial in the Functions demonstrates the value of ProjectEvents.ogs when used in
conjunction with LabTalk's dataset-based functions.

You can add your own sections to this OGS file to save custom routines or project-
specific script code. Such sections will not be event-driven, but can be accessed by
name from any place that LabTalk script can be executed. For example, if you add a
section to this file named [MyScript], the code in that section can be executed after
opening the project by issuing this command from the script window:
run.section(projectevents,myscript);

A ProjectEvents.ogs script can also be made to run by opening the associated Origin Project (OPJ)
from a command console external to Origin.

5.2.9 From Import Wizard

The Import Wizard can be used to import ASCII, Binary or custom file formats (when using a custom
program written in Origin C). The Wizard can save a filter in select locations and can include script
that runs after the import occurs. Once created, the filter can be used to import data and
automatically execute script. This same functionality applies when you drag a file from Explorer and
drop onto Origin if Filter Manager has support for the file type.
For example,
1. Start the Import Wizard.

2. Browse to the Origin Samples\Spectroscopy folder and choose Peaks with Base.DAT.

3. Click Add, then click OK.

4. Click Next six times to get to the Save Filters page.

5. Check Save Filter checkbox.

6. Enter an appropriate Filter file name, such as Subtract Base and Find Peaks.

7. Check Specify advanced filter options checkbox.

8. Click Next.

9. Paste the following into the text box:

range raTime = 1; // Get the Time column as a range

range raAmp = 2; // Get the Amp column as a range
range raBase = 3; // Get the Base column as a range
wks.addcol(Subtracted); // Create a column called Subtracted
range raSubtracted = 4; // Get the Subtracted column as a range
raSubtracted = raAmp - raBase; // Subtract Base from Amp
pkFind iy:=(1,4); // Find peaks in the Subtracted data
range raPeaks = 5; // Get the peak index column as a range
for( idx = 1; idx <= raPeaks.GetSize() ; idx++ )
{
pkidx = raPeaks[idx];
ty Peak found at $(raTime[pkidx]) with height of

105
 LabTalk Scripting Guide

$(raSubtracted[pkidx]);
}
10. Click Finish.

This is what happens:

 The filter is saved.

 The import runs using this filter.

 After the import, the script runs which creates the subtracted data and the pkFind function

locates peak indices. Results are typed to the Script Window.

5.2.10 From Nonlinear Fitter

The Nonlinear Fitter has a Script After Fitting section on the Code page of the NLFit dialog. This
can be useful if you want to always do something immediately after a fit. As an example, you could
access the fit parameter values to do further calculations or accumulate results for further analysis.
In this example, the Script After Fitting section adds the name of the fit dataset and the calculated
peak center to a Workbook named GaussResults:
// This creates a new book only the first time
if(exist(GaussResults)!=2)
{
newbook name:=GaussResults sheet:=1 option:=1 chkname:=1;
GaussResults!wks.col1.name$= Dataset;
GaussResults!wks.col2.name$= PeakCenter;
}

// Get the tree from the last Report Sheet (this fit)
getresults iw:=__REPORT$;

// Assign ranges to the two columns in 'GaussResults'

range ra1 = [GaussResults]1!1;
range ra2 = [GaussResults]1!2;

// Get the current row size and increment by 1

size = ra1.GetSize();
size++;

// Write the Input data range in first column

ra1[size]$ = ResultsTree.Input.R2.C2$;
// and the Peak Center value in the second
ra2[size] = ResultsTree.Parameters.xc.Value;

5.2.11 From an External Application

External applications can communicate with Origin as a COM Server. Origin's COM Object exposes
various classes with properties and methods to other applications. For complete control, Origin has
the Execute method which allows any LabTalk - including LabTalk callable X-Functions and OriginC
function - to be executed. In this example (using Visual Basic Syntax), we start Origin, import some
data, do a Gauss fit and report the peak center :

106
 Running and Debugging LabTalk Scripts

' Start Origin

Dim oa
Set oa = GetObject("", "Origin.Application")
'oa.Execute ("doc -m 1") ' Uncomment if you want to see Origin
Dim strCmd, strVar As String
Dim dVar As Double
' Wait for Origin to finish startup compile
' (30 seconds is specified here,
' but function may return in less than 1 second)
oa.Execute ("sec -poc 30")
'Project is empty so create a workbook and import some data
oa.Execute ("newbook")
strVar = oa.LTStr("SYSTEM.PATH.PROGRAM$") + _
"Samples\Curve Fitting\Gaussian.DAT"
oa.Execute ("string fname") ' Declare string in Origin
oa.LTStr("fname$") = strVar ' Set its value
oa.Execute ("impasc") ' Import

' Do a nonlinear fit (Gauss)

strCmd = "nlbegin 2 Gauss;nlfit;nlend;"
oa.Execute (strCmd)
' Get peak center
dVar = oa.LTVar("nlt.xc")
strVar = "Peak Center at " + CStr(dVar)
bRet = MsgBox(strVar, vbOKOnly, "Gauss Fit")

oa.Exit
Set oa = Nothing
End
There are more detailed examples of COM Client Applications in the Samples\COM Server and
Client folder.

5.2.12 From Console

When Origin is started from the command-line of an external console (such as Windows cmd
window), it reads any command beyond the Origin.exe call, to check if any optional arguments have
been specified.
For information, see Customizing Origin Startup Behavior with the Command Line.

5.2.13 On A Timer
The Timer (Command) executes the TimerProc macro, and the combination can be used to run a
script every n seconds.
The following example shows a timer procedure that runs every 2 seconds to check if a data file on
disk has been modified, and it is then re-imported if new.
In order to run this scipt example, perform the following steps first:
1. Create a simple two-column ascii file c:\temp\mydata.dat or any other desired

name and location

2. Start a new project and import the file into a new book with default ascii settings.

The book short name changes to mydata

107
 LabTalk Scripting Guide

3. Create a line+symbol plot of the data, and set the graph x and y axis rescale

property to auto so that graph updates when new data is added

4. Keep the graph as the active window

5. Save the script below to the [AfterOpenDoc] section of the ProjectEvents.OGS

file attached to the project.

6. Add the following command to the [BeforeCloseDoc] section of

ProjectEvents.OGS:

timer -k;

7. Save the Origin Project, close, and then re-open the project. Now any time the

project is opened, the timer will start, and when the project is closed the timer

will stop executing.

8. Go to the data file on disk and edit and add a few more data points

9. The timer procedure will trigger a re-import and the graph will update with the

additional new data

// Set up the TimerProc macro

def TimerProc {
// Check if file exists, and quit if it does not
string str$="c:\temp\mydata.dat";
if(0 == exist(str$) ) return;

// Get date/time of file on disk

double dtDisk = exist(str$,5);

// Run script on data book

// Assuming here that book short name is mydata
win -o mydata {
// Get date/time of last import
double dtLast = page.info.system.import.filedate;

// If file on disk is newer, then re-import the file

if( dtDisk > dtLast ) reimport;
}
}

// Set TimerProc to be executed every 2 seconds

timer 2;

108
 Running and Debugging LabTalk Scripts

The Samples\LabTalk Script Examples subfolder has a sample Origin Project

named Reimport File Using Timer.OPJ which has script similar to above set up. You
can open this OPJ to view the script and try this feature.

5.2.14 On Starting or Exiting Origin

Defining Global Constants, Variables and Functions

Use the [Startup] section of the Origin.ini to define global constants, variables and functions for use
any time you run Origin.
See these topics for more information on scope:
 Scope of Variables

 Scope of Functions

Defining global constants and variables

See FAQ-286 for information on defining constants and variables for use across Origin sessions.

Defining a global function

1. If Origin is running, exit the program.

2. Start a fresh page in a text editor (e.g. Notepad) and enter the following information:

[Main]
@global = 1;
// This function calculates the cube root of a number
function double dCubeRoot(double dVal)
{
double xVal;
if(dVal<0) xVal = -exp(ln(-dVal)/3);
else xVal = exp(ln(dVal)/3);
return xVal;
}
@global = 0;
3. Name and save the file to your the User Files Folder (UFF), using an .OGS file extension (e.g.

myLTFuncs.ogs).

4. Browse to your Origin.ini file in your UFF and open this file in your text editor.

5. Locate the [Startup] section of the file and add the name of the .OGS file you just created

using the following form:

FileN=myLTFuncs.ogs

109
 LabTalk Scripting Guide

6. ... where N is 1,2,3,etc.

7. Save your changes to Origin.ini.

8. To check the availability of your function, run Origin, open the Script Window and enter the

name of the function, followed by a value in parentheses and "=", then press ENTER.

dCubeRoot(8)=
9. Origin returns:
dCubeRoot(8)=2
See this topic for more information on the Scope of Functions.

Using OEvents.ogs to Trigger Events

When the Origin application is launched, there are multiple events that are triggered. Your LabTalk
script can be set to execute with each event using the OEvents.OGS file. This OEvents.OGS file
includes several sections that indicate when to run the script, such as, [AfterCompileSystem],
[BeforeOpenDoc], and [OnExitOrigin].
The following example demonstrates cleaning the history panel of Command Window on existing
Origin.
(Note that Origin C functions can not be run in the [OnExitOrigin] section. If you want to trigger
events on exiting Origin, always use LabTalk commands.)
1. Copy the OEvents.OGS file from the Origin EXE folder to your User Files Folder. Alternatively,

when opening the file from the EXE folder just make sure to then save it to your User Files

Folder.

2. In the section named [OnExitOrigin], add the following script:

// Delete the files, which keep the history of command window, from the
User File folder
del -f "%YUpDown_Buffer.txt";
del -f "%YLTHistory.txt";
3. To run sections in OEvents.OGS, you also need to edit the Origin.ini file in your User Files

Folder. Close Origin if running, and then edit your Origin.ini and uncomment (remove the ";") in

the line under the [Config] section, so that it is as below:

Ogs1 = OEvents
; Ogs2 = OEvents
; Origin can trigger multiple system events
; Uncomment this line and implement event handlers in OEvents.ogs

Note: More than one event handler file may exist in Origin.ini and the name is not restricted
to OEvents.OGS.
5. Close Origin and restart a new Origin session to check whether the history panel of Command

Window is clean.

110
 Running and Debugging LabTalk Scripts

Origin C functions can be run from other sections of OEvents.OGS such as

[BeforeOpenDoc]. View the Compiling, Linking and Loading page in Origin C
Programming Guide for an example.
Please note that If you need to call Origin C functions from your custom script
associated with events, you need to ensure that the Origin C file is compiled and the
functions are available for script access. See Loading and Compiling Origin C
Functions for details.

5.2.15 From a Custom Menu Item

LabTalk script can be assigned to custom menu items. The Custom Menu Organizer dialog
accessible from the Tools main menu in Origin provides easy access to add and edit main menu
items. The Add Custom Menu tab of this dialog can be used to add a new main menu entry and
then populate it with sub menu items including pop-up menus and separators. Once a menu item has
been added, LabTalk script can be assigned for that item. The menu items can be made available for
all window types or a specific window type.
The custom menu configuration can then be saved and multiple configuration files can be created
and then loaded separately using the Format: Menu main menu. For further information please view
the help file page for the Custom Menu Organizer dialog.

5.2.16 From a Toolbar Button

LabTalk script files can also be run from buttons on the Origin toolbar. In Getting Started with
LabTalk chapter, we have introduced how to run Custom Routine from a toolbar button, here we will
introduce more details. Three files enable this to happen:
1. A bitmap file that defines the appearance of the button. Use one of the set of buttons provided

in Origin or create your own.

2. A LabTalk script file that will be executed when the user clicks the button.

3. An INI file that stores information about the button or button group. Origin creates the INI file for

you, when you follow the procedure below.

We will assume for now that you have a bitmap image file (BMP) that will define the button itself (if
you are interested in creating one, example steps are given below).
First, use CodeBuilder (select on the Origin Standard Toolbar to open) or other text editor, to
develop your LabTalk script (OGS) file. Save the file with the OGS extension. You may divide a single
script file into several sections, and associate each section with a different toolbar button.

5.2.16.1 Putting a Button on an Origin Toolbar

To put the button on an Origin toolbar, use this procedure:
1. In Origin, select View:Toolbars to open the Customize Toolbar dialog.

2. Make the Button Groups Tab active.

3. Click the New button in the Button Group to open the Create Button Group dialog.

4. Enter a new Group Name.

111
 LabTalk Scripting Guide

5. Enter the Number of Buttons for this new Group.

6. Click the Browse button to locate your bitmap file. This file should be in your User directory.

7. Click OK.

8. The Save As dialog will open. Enter the same name as that of your bitmap file. Click OK to

save the INI file. You will now see that your group has been added to the Groups list and your

button(s) is now visible.

When creating a custom button group for export to an OPX file, consider saving your button group's
initialization file, bitmap file(s), script file(s), and any other support files to a user-created subfolder in
your User Files folder. When another Origin user installs your OPX file, your custom subfolder will
automatically be created in the user's User Files folder, and this subfolder will contain the files for the
custom button group. This allows you to keep your custom files separate from other Origin files.

5.2.16.2 Match the Button with a LabTalk Script (OGS) File

1. Click on the button to select it.

2. Click the Settings button, to open the Button Settings dialog.

3. Click the Browse button to locate your OGS file.

4. Enter the Section Name of the OGS file and any arguments in the Argument List.

5. Enter something descriptive in the Tool Tip Text text box.

6. Enter a status bar message in the Status Bar text box.

7. Click OK.

8. Repeat these steps for each of the buttons in your Button Group.

9. Drag the first button out onto your Origin workspace. A toolbar is created. You can now drag all

other buttons onto this toolbar.

5.2.16.3 Custom Buttons Available in Origin

The following dialog can be accessed from the View: Toolbars menu option in Origin. On the Button
Groups tab, scroll down to select the User Defined group:

112
 Running and Debugging LabTalk Scripts

Drag any of these buttons onto the Origin toolbar to begin using them. Use the procedure outlined
above to associate a script with a given button.

5.2.16.4 Creating a Bitmap File for a New Button

To create a bitmap file, using any program that allows you to edit and save a bitmap image (BMP)
such as Window's Paint. The following steps will help you get started:

1. Using the bitmap for the built-in user defined toolbar is a good place to begin. In Windows

Paint, select File:Open, browse to your User Files folder and select Userdef.bmp.

2. Set the image size. Select Image:Attributes. The height needs to remain at 16 and should not

be changed. Each button is 16 pixels high by 16 pixels wide. If your toolbar will be only 2

buttons then change the width to 32. The width is always 16 times the number of buttons, with

a maximum of 10 buttons or a width of 160.

113
 LabTalk Scripting Guide

3. Select View:Zoom:Custom:800%. The image is now large enough to work with.

4. Select View:Zoom:Show Grid. You can now color each pixel. The fun begins - create a look

for each button.

5. Select File:Save As, enter a new File name but leave the Save as type to 16 Color Bitmap.

5.3 Debugging Scripts

5.3.1 Debugging Scripts
This section covers means of debugging your LabTalk scripts. The first part introduces interactive
execution of script. The second presents several debugging tools, including Origin's native script
editor, Code Builder. And the third covers the error handling.

Topics covered in this section:

 Interactive Execution

 Debugging Tools

 Error Handling

5.3.2 Interactive Execution

You can execute LabTalk commands or X-functions line-by-line (or a selection of multiple lines) to
execute step-by-step. The advantage of this procedure is that you can verify the result of the issued
command, and according to the result or error, you can act appropriately.
To execute LabTalk commands interactively, you can enter them in the following places:
 Classic Script Window

 Command Window in Origin's main window

 Command & Results Windows in Code Builder

The characteristics and the advantages of each window are as follows:

Classic Script Window

This window can be open from the Window main menu. This is the most flexible place for advanced
users to execute LabTalk scripts. Enter key will execute
1. the current line if cursor has no selection

2. the selected block if there is a selection

114
 Running and Debugging LabTalk Scripts

You can use Ctrl+Enter to add a line without executing. There is also a Script Execution option on
the Edit menu to toggle between editing and interactive execution.

Command Window in Origin's Main Window

You can enter a LabTalk command at the command prompt in the Command Window. The result
would be printed immediately after the entered command line. Command Window has various
convenient features such as command history panel, auto-completion, roll back support for utilizing
previously executed commands, saving previously executed commands to an OGS file, etc. Note,
however, that you cannot edit multi-line scripts within the Command Window.
To learn how to use the Command window, see The Origin Command Window chapter in the
Origin help file.

Command & Results Windows in Code Builder

Code Builder is Origin's integrated development environment useful in debugging LabTalk scripts as
well as Origin C code, X-Function code, etc. In Code Builder, use various convenient debugging tools
like setting up break points, step-by-step execution, inspection of the values of variables, etc.
To learn how to use the Code Builder, see the Code Builder User's Guide in the Programming help
file.

5.3.3 Debugging Tools

Origin provides various tools to help you to develop and debug your LabTalk scripts.

5.3.3.1 Code Builder (Origin feature)

Code Builder is Origin's integrated development environment to debug LabTalk scripts, Origin C
code, X-Function code and fitting functions coded in Origin C. In Code Builder, use various
convenient debugging tools like setting up break points, step-by-step execution and inspection of
variable values. Code Builder can be opened by the ed.open() method.
To learn how to use the Code Builder, see the Code Builder User's Guide in the Programming help
file.
Here is an example showing how to debug LabTalk script in Code Builder.
1. Open an OGS file by running the following script.

// Open an ogs file in Code Builder

file$ = system.path.program$ + "Samples\LabTalk Script
Examples\ave_traces.ogs";
ed.open(%(file$));
2. Set a break point on line 22 in the open file, by clicking on the margin to the left of this line:

fname$ = system.path.program$ + "Samples\Data

Manipulation\not_monotonic_multicurve.dat";
The break point will look like this:

115
 LabTalk Scripting Guide

3. Place the cursor on line 12 - the [Main] section - then select menu Debug: Execute Current

Section. The [Main] section code will run and stop at the line with the break point.

4. Now press F10 to execute the remaining script line by line. Code Builder provides the Watch

window to view the value of a variable during debugging. For example, after pressing F10 once,

open the Watch window by menu item View: Watch if it is not opened yet. Then type fname$

in the left cell of the table in this window, the value will show in the right cell of the same row.

5. To execute the remaining script, press F5. It will complete unless encountering another break

point.

5.3.3.2 Ed (object)

116
 Running and Debugging LabTalk Scripts

The Ed (object) provides script access to Code Builder, a dedicated editor for LabTalk script and
Origin C code.
The ed object methods are:
Method Brief Description

ed.open() Open the Code Builder window.

ed.open(fileName) Open the specified file in the Code Builder window.

ed.open(fileName, Open the specified OGS file at the specified section in the Code
sectionName) Builder window. (Defaults to file beginning if section not found.)

Open the Code Builder

ed.open()

Open a Specific File in Code Builder

The following command opens the file myscript.ogs

ed.open(E:\myfolder\myscript.ogs)

Open a File on a Pre-Saved Path

Use the cd X-Function to first switch to the particular folder:

cd 2;
ed.open(autofit.ogs);

5.3.3.3 LabTalk Variables and Functions Dialog

The list command with no options as well as the ed command (different than the ed object) opens
the LabTalk Variables dialog, which is a table of attributes for all variables in the current project. The
attributes are variable name, value, type, subtype, property, plot information, and description.
This is a useful tool for script programmers as the current values and properties of variables can be
viewed in real time. Additionally, variables can be sorted by any of their attributes, alphabetically in
the case of text descriptors, numerically in the case of numeric values.
Check boxes exist on the right-hand side of the dialog that allow you to see any subset of the entire
variable list.

117
 LabTalk Scripting Guide

5.3.3.4 Echo (system variable)

To debug and trace, this system variable, Echo prints scripts or error messages to the Command
window (or Script window when entered there). To enable echo, type:
echo = Number
in the Script window (where Number is one of the following):
Number Description

1 Display commands that generate an error;

2 Display scripts that have been sent to the queue for delayed execution;

4 Display scripts that involve commands;

8 Display scripts that involve assignments;

16 Display macros.
These values are bits that can be combined to produce cumulative effects. For example, echo = 12
displays both command and assignment scripts. Echo = 7 (includes echo = 1, echo = 2, and echo =
4) is useful for following script execution during menu command selection. To disable echo, type echo
= 0 in the Script window

5.3.3.5 #!script (special syntax)

Embed debugging statements in your script using this notation. The # character tells the LabTalk
interpreter to ignore the text until the end of the line. However, when followed by the ! character, the
script is executed if the @B system variable (or System.Debug object property) is set to 1. The
following example illustrates this option:

118
 Running and Debugging LabTalk Scripts

@B = 1;
range rr = [Book1]Sheet1!col(A); // Range to column A
for (ii=1; ii<=10; ii+=1) {
#!ii=; rr[ii]=; // Embedded debugging script
rr[ii]+=ii*10;
}
@B = 0;
#!type -a This line will not execute
The script sets @B equal to 1 to allow #! lines to execute. By setting @B to 0 , the last line will not
execute.

5.3.3.6 {script} (special syntax)

An error in your LabTalk code will cause the code to stop at the point of the error and not execute any
statements after the error. In cases where you would like the script to continue executing in such
cases, you can use curly braces to define where error handling should begin and resume. For
instance, in the following script,
type Start;
impasc fname:=BadFileName;
type End;
the word Start will print to the Script Window, but if BadFileName cannot be found, the script will
stop executing at that point, and the word End will not print.
If, however, you surround the line in question with curly braces (i.e., {}), as in,
type Start;
{
impasc fname:=BadFileName;
}
type End;
then End will print whether or not BadFileName is properly imported.
You can catch this condition with a variable:
flag = 1;
{
impasc fname:=MyFile;
flag = 0;
}
if(flag)
type Error ocurred;
else
type OK;
A similar situation occurs when a section in an OGS file fails. Code will silently return to the calling
context. Use the above variable method to identify that code failed. In this case, the brackets are not
needed:
[Called Section]
flag = 1;
BadCommand; // This line errors and silently returns
flag = 0; // flag (which must be global variable) is 1, then above code
failed.

5.3.3.7 @B(system variable), System.Debug (object property)

@B system variable controls the Debug mode to execute the LabTalk statements that begin with #! :
1 = enable
0 = disable
It is equivalent to the System.Debug object property.

119
 LabTalk Scripting Guide

5.3.3.8 @OC (system variable)

@OC system variable controls whether or not you can call Origin C functions from LabTalk.
Value Description

@OC = 1 (default) Origin C functions CAN be called

@OC = 0 Origin C functions CANNOT be called

5.3.3.9 @V(system variable), System.Version(object property)

@V indicates the Origin version number. @V and System.Version object property are equivalent.

5.3.3.10 @VDF (system variable)

If you set @VDF = 1, when you open a project file (.OPJ), Origin will report the Origin version in
which the file was saved.

5.3.3.11 VarName= (command)

This command examines the value of any variable. Embed this in your script to display intermediate
variable values in the Script window during script execution.
Example 1
The following command prints out the value of myHight variable:
myHight=

5.3.3.12 LabTalk:List (command)

The list command is used to examine your system environment. For example, the list s command
displays all datasets (including temporary datasets) in the project.

5.3.3.13 ErrorProc (macro)

The ErrorProc macro is useful for error trapping.
The ErrorProc macro is triggered ...
 when the LabTalk interpreter detects a #Command Error.

 when you click the Cancel button in any dialog box.

 when you click the No button in dialog boxes that do not have a Cancel button.

The ErrorProc macro is deleted immediately after it is triggered and executed.

5.3.3.14 NotReady (macro)

This macro displays the message "This operation is still under development..." in a dialog box with an
OK button.

5.3.3.15 Type <ogsFileName> (command)

This variant of the type command prints out the contents of a specified script file (.OGS) in the current
directory to the Command (or Script) window. Note that the file extension .OGS in ogsFileName may
be omitted. The file name cannot include a path and must be in the working directory.
Examples:
The following script prints the contents of D: \temp\mytemp1.ogs and C:\myogs\hello.ogs.
cd D:\Temp;

120
 Running and Debugging LabTalk Scripts

type mytemp1.ogs; // Extension included

cd C:\temp;
type hello; // Extension omitted

5.3.3.16 Log to a File

To output the log information to a file, the type command is available. type -gb will specify the log file
to output to, and begin the output routine. Then type -ge will end the routine and stop logging to the
file. For example:
type -gb %Ylog.txt; // Start typing text to a file, log.txt, if not exist,
create it
type aa; // Write aa
type bb; // Write bb
type cc; // Write cc
type -ge; // End writing
This can be particularly useful when your script is creating a large volume of output to the Script
Window since it has only a 30000 byte buffer.

5.3.4 Error Handling

LabTalk scripts may be interrupted if an error has been thrown. But there are times when you want to
continue the execution of the script even if an error is encountered. In this situation, Origin allows you
to use a pair of curly braces ("{" and ―}‖) to enclose a part of the script that might generate an error.
When Origin encounters an error within the section the remaining script up to the "}" is skipped and
execution resumes outside the curly braces. In this sense, braces and run.section() commands have
the same behavior.
The following is a simple example to show how to handle possible errors. Please note that before
executing the scripts in the Script Window, you should create a new worksheet and make sure that
column C does not exist.
// Script without error handling
type "Start the section";
stats col(c);
stats.max=;
type "Finished the section";
The line of code, stats col(c);, will throw an error, because Column C does not exist. Then, the
script will terminate and only output:
Start the section
Failed to resolve range string, VarName = ix, VarValue = col(c)
Now we will introduce braces to use error handling. We can add a variable to indicate if an error
occurred and make use of a System Variable to temporarily shut off Origin error messages:
// Script with error handling
type "Start the section";
int iNOE = @NOE; // Save current Origin error message output flag
// The section that will generate an error
{
@NOE = 0; // Shut off Origin error messages
vErr = 1; // Set our error variable to true (1)
stats col(c); // This is the code which could produce an error
stats.max=; // Execution will continue only if no error occurs
vErr = 0; // If NO error then our variable gets set to false (0)
}
@NOE = iNOE; // Restore Origin error messages
if(vErr) ty An error occurred. Continuing ...;
type "Finished the section";

121
LabTalk Scripting Guide

The output will become

Start the section
An error occurred. Continuing ...
Finished the section
After the error on the stats col(c) line, code execution continues outside the closing brace (})
and we can trap our error and process as needed. You can comment out the lines related to @NOE if
you want the Message Log to retain a record of all errors that occurred.

122
6 String Processing

6.1 String Processing

This chapter introduces you to working with strings, including string variables, registers and arrays,
converting numbers to strings, strings to numbers, and various methods available for string
processing.

Topics covered in this chapter:

 String Variables and String Registers

 String Processing

 Converting Strings to Numbers

 Converting Numbers to Strings

 String Arrays

6.2 String Variables and String Registers

In Origin, string processing is supported in two ways: with string variables, and with string registers. In
general, we encourage the use of string variables as they are more intuitive (i.e., more like strings in
other programming languages) and are supported by many pre-defined string methods; both of which
are advantages over string registers.

6.2.1 String Variables

A string variable is created by declaration and/or assignment, and its name is always followed by a $-
sign. For example:
// Creates by declaration a variable named 'aa' of the string type;
//'aa' is empty (i.e., "")
string aa$;

// Assigns to 'aa' a character sequence

aa$ = "Happy";

// Creates and assigns a value to string variable 'bb',

//all on the same line
string bb$ = "Yes";

// Creates and assigns a value to string variable 'cc' with no declaration

123
 LabTalk Scripting Guide

//(see note below)

cc$ = "Project";
Note: Because string variable cc was not declared, it is given Project scope, which means all
routines, functions, or otherwise can see it as long as the project is open. Declared variables aa and
bb are given Local (or Session) scope. For more on scope, see Variables and Scope.

6.2.2 String Registers

Prior to Version 8.0, Origin supported string processing with string registers. As such, they continue
to be supported by more recent versions, and you may see them used in script programming
examples. There are 26 string registers, corresponding to the 26 letters of the English alphabet, each
preceeded by a %-sign, i.e., %A--%Z. They can be assigned a character sequence just like string
variables, the differences are in the way they are handled and interpreted, as the examples below
illustrate. As a warning, several of the 26 string registers are reserved for system use, most notably,
the ranges %C--%I, and %X--%Z. For complete documentation on their use, see String Registers.

6.3 String Processing

6.3.1.1 Using String Methods
These examples show multiple ways to get a substring (in this case a file name) from a longer string
(a full file path). In the last of these, we demonstrate how to concatenate two strings.

Find substring, using getFileName()

In this example, a string method designed for a very specific but commonly needed task is invoked.
// Use the built-in string method, GetFileName():
string fname$="C:\Program Files\Origin 8\Samples\Import\S15-125-03.dat";
string str1$ = fname.GetFileName()$;
str1$=;

Find substring, using reverseFind(), mid() methods

This time, a combination of string methods is used:

// Use the functions ReverseFind and Mid to extract the file name:
string fname$="C:\Program Files\Origin 8\Samples\Import\S15-125-03.dat";
// Find the position of the last '\' by searching from the right.
int nn=fname.ReverseFind('\');
// Get the substring starting after that position and going to the end.
string str2$=fname.Mid(nn+1)$;
// Type the file name to the Script Window.
str2$=;

Find substring, token-based

Here, another variation of generic finding methods is chosen to complete the task.
// Use a token-based method to extract the file name:

string fname$="C:\Program Files\Origin 8\Samples\Import\S15-125-03.dat";

// Get the number of tokens, demarcated by '\' characters.
int nn=fname.GetNumTokens('\');
// Get the last token.

124
 String Processing

string str3$ = fname.GetToken(nn, '\')$;

// Output the value of that token to the Script Window.
str3$=;

6.3.1.2 String Concatenation

You can concatenate strings by using the '+' operator. As shown below:
string aa$="reading";
string bb$="he likes " + aa$ + " books";
type "He said " + bb$;
You may also use the insert string method to concatenate two strings:
string aa$ = "Happy";
string bb$ = " Go Lucky";
// insert the string 'aa' into string 'bb' at position 1
bb.insert(1,aa$);
bb$=;
For a complete listing and description of supported string methods, please see String (Object).

6.3.1.3 Using String Registers

String Registers are simpler to use and quite powerful, but more difficult to read when compared with
string variables and their methods. Also, they are global (session scope) and you will have less
control on their contents being modified by another program.
// Concatenate two strings using string registers

%A="Left";
%B="Handed";
%N="%A %B";
%N= // "Left Handed"
// Extract the file name substring from the longer file path string:
%N="C:\Program Files\Origin 8\Samples\Import\S15-125-03.dat";
for(done=0;done==0; )
{
%M=%[%N,>'\'];
if(%[%M]>0) %N = %M;
else done = 1;
}
%N=;

6.3.1.4 Extracting Numbers from a String

This example shows multiple ways to extract numbers from a string:
// String variables support many methods
string fname$="S15-125-03.dat";

int nn=fname.Find('S');
string str1$ = fname.Mid(nn+1, 2)$;
type "1st number = %(str1$)";

string str2$ = fname.Between("-", "-")$;

type "2nd number = %(str2$)";

int nn = fname.ReverseFind('-');
int oo = fname.ReverseFind('.') ;
string str3$ = fname.Mid(nn + 1, oo - nn - 1)$;
type "3rd number = %(str3$)";

125
 LabTalk Scripting Guide

type $(%(str2$) - %(str1$) * %(str3$));

// Using string Registers, we can use substring notation

%M = "S15-125-03.dat";
%N = %[%M,2:3]; // Specify start and end
type "1st number = %N";
%N = %[%M,>'S']; // Find string after 'S'
%N = %[%N,'-']; // Find remaining before '-'
type "1st number = %N";
%O = %[%M,#2,\x2D]; // Find second token delimited by '-' (hexadecimal 2D)
type "2nd number = %O";
%P = %[%M,'.']; // trim extension
%P = %[%P,>'-']; // after first '-'
%P = %[%P,>'-']; // after second '-'
type "3rd number = %P";
type $(%O - %N * %P);

6.4 Converting Strings to Numbers

The next few examples demonstrate converting a string of numeric characters to an actual number.

6.4.1 Converting String to Numeric

6.4.1.1 Using Substitution Notation
To convert a variable of type string to a variable of type numeric (double, int, const), consider the
following simple example:
// myString contains the characters 456 as a string
string myString$ = "456";

// myStringNum now contains the integer value 456

int myStringNum = %(myString$);
The syntax %(string$) is one of two substitution notations supported in LabTalk. The other, $(num),
is used to convert in the opposite direction; from numeric to string.

6.4.1.2 Using String Registers

This example demonstrates how to convert a string held in a string register to a numeric value.
// Similar to above, but performed using string registers:
string myString$ = "456";
// Assignment without quotes will evaluate the right-hand-side
%A = myString$;
// %A will be substituted, then right-hand-side evaluated
int aa = %A;
// 'aa' can be operated on by other integers
int bb = aa + 100;
bb=; // ANS: 556

6.5 Converting Numbers to Strings

The following examples demonstrate conversion of numeric variables to string, including notation to
format the number of digits and decimal places.

126
 String Processing

6.5.1 Converting Numeric to String

6.5.1.1 Using Substitution Notation
To convert a variable of a numeric type (double, int, or const) to a variable of string type, consider the
following simple example:
// myNum contains the integer value 456
int myNum = 456;
// myNumString now contains the characters 456 as a string
string myNumString$ = $(myNum);
The syntax $(num) is one of two substitution notations supported in LabTalk. The other, %(string$),
is used to convert in the opposite direction, from string to numeric, substituting a string variable with
its content.
Formatting can also be specified during the type conversion:
$(number [,format]) // braces indicate that the format is optional
Format follows the C-programming format-specifier conventions, which can be found in any C-
language reference, for example:
string myNumString2$ = $("3.14159",%3d);
myNumString2$= // "3"

string myNumString2$ = $("3.14159",%3.2f);

myNumString2$= // "3.14"

string myNumString2$ = $("3141.59",%6.4e);

myNumString2$= // "3.1416e+003"
For further information on this type of formatting, please see $() Substitution.

6.5.1.2 Using the Format Function

Another way to convert a numeric variable to a string variable uses the format function:
// call format, specifying 3 significant figures
string yy$=Format(2.01232, "*3")$;
// "2.01"
yy$=;
For full documentation of the format function see Format (Function)

6.5.2 Significant Digits, Decimal Places, and Numeric Format

LabTalk has native format specifiers that, used as part of LabTalk's Substitution Notation provide a
simple means to format a number.

6.5.2.1 Use the * notation to set significant digits

x = 1.23456;
type "x = $(x, *2)";
In this example, x is followed by *2, which sets x to display two significant digits. So the output result
is:
x = 1.2
Additionally, putting a * before ")" will cause the zeros just before the power of ten to be truncated.
For instance,
y = 1.10001;
type "y = $(y, *4*)";
In this example, the output result is:

127
 LabTalk Scripting Guide

y = 1.1
The result has only 2 siginificant digits, because y is followed by *4* instead of *4.

6.5.2.2 Use the . notation to set decimal places

x = 1.23456;
type "x = $(x, .2)";
In this example, x is followed by .2, which sets x to display two decimal places. So the output result is:
x = 1.23

6.5.2.3 Use E notation to change the variable to engineering format

The E notation follows the variable it modifies, like the * notation. For example,
x = 1e6;
type "x = $(x, E%4.2f)";
where % indicates the start of the substitution notation, 4 specifies the total number of digits, .2
specifies 2 decimal places, and f is an indicator for floating notation. So the output is:
x = 1.00M

6.5.2.4 Use the $(x, S*n) notation to convert from engineering to scientific
notation
In this syntax, n specifies the total number of digits.
x = 1.23456;
type "x = $(x,S*3)";
And Origin returns:
x = 1.23E0

6.6 String Arrays

This example shows how to create a string array, add elements to it, sort, and list the contents of the
array.
// Import an existing sample file
newbook;
fpath$ = "Samples\Data Manipulation\US Metropolitan Area Population.dat";
string fname$ = system.path.program$ + fpath$;
impasc;

// Loop over last column and find all states

range rMetro=4;
stringarray saStates;
for( int ir=1; ir<=rMetro.GetSize(); ir++ )
{
string strCell$ = rMetro[ir]$;
string strState$ = strCell.GetToken(2,',')$;
// Find instances of '-' in name
int nn = strState.GetNumTokens("-");
// Add to States string array
for( int ii=1; ii<=nn; ii++ )
{
string str$ = strState.GetToken(ii, '-')$;
// Add if not already present
int nFind = saStates.Find(str$);

128
 String Processing

if( nFind < 1 )

saStates.Add(str$);
}
}

// Sort States string array and print out

saStates.Sort();
for(int ii=1; ii<=saStates.GetSize(); ii++)
saStates.GetAt(ii)$=;

129
7 Workbooks Worksheets and Worksheet Columns

7.1 Workbooks Worksheets and Worksheet Columns

In this chapter we cover the Workbook -> Worksheet -> Column hierarchy, and how to access these
objects from script. The concept of treating data in a worksheet as a virtual matrix is also covered.

This chapter covers the following topics:

 LT Workbooks

 LT Worksheets

 LT Worksheet Columns

7.2 Workbooks
7.2.1 Workbooks

This chapter covers the following topics:

 Basic Workbook Operation

 Workbook Manipulation

7.2.2 Basic Workbook Operation

You can manipulate workbooks with the Page object and Window command. You can also use Data
Manipulation X-Functions. With these tools, you can create new worksbooks, duplicate workbooks,
save workbook as template, etc. Some practical examples are provided below.

7.2.2.1 Create New Workbook

The newbook X-Function can be used to create new workbook. With the arguments of this X-
Function, you can specify the newly created workbook with Long Name, number of sheets, template
to use, whether hidden, etc.
//Create a new workbook with the Long Name "MyResultBook"

131
 LabTalk Scripting Guide

newbook MyResultBook;

// Create a new workbook with 3 worksheets

// and use "MyData" as Long Name and short name
newbook name:="MyData" sheet:=3 option:=lsname;

// Create a new hidden workbook

// and the workbook name is stored in myBkName$ variable
newbook hidden:=1 result:=myBkName$;
// Output workbook name
myBkName$ = ;

// By default, the built-in template "Origin" is used to

// create the new workbook, you can also use a specified template
// Create a new workbook with the XYZ template
newbook template:=XYZ;
Also, the command win -ti is capable of creating a minimized new workbook from a template file.
// Create a new wookbook from the FFT template
// and Long Name and short name to be MyFFT, then minimize it
win -ti wks FFT MyFFT;

7.2.2.2 Open Workbook

If the workbook with data is saved (as extension of ogw), it can be opened by the doc -o command.
// The path of the workbook to open
string strName$ = system.path.program$;
strName$ += "Samples\Graphing\Automobile Data.ogw";
// Open the workbook
doc -o %(strName$);

7.2.2.3 Save Workbook

Origin allows you to save a workbook with data to a file (*.ogw), or as a template without data (*.otw),
and for the workbook with analysis, it is able to be saved as an analysis template (*.ogw).
1. The command save -i is able to save the active workbook with data to an ogw file.

// Create a new workbook

newbook;
// Fill some data to col(1)
col(1) = uniform(32);
// Save this workbook with data to MyData.ogw under User Files Folder
save -i %YMyData.ogw;
2. The X-Function template_saveas is used to save workbook as a template.

// Create a new workbook with 3 sheets

newbook sheet:=3;
// Save this workbook as a template named My3SheetsBook
// in User Files Folder (default)
template_saveas template:=My3SheetsBook;
3. To save a workbook with analysis, the command save -ik can be used.

132
 Workbooks Worksheets and Worksheet Columns

// Create a project
string strOpj$ = system.path.program$ + "Samples\Analysis.opj";
doc -o %(strOpj$);

// Activate the workbook to be saved as analysis template

win -a Book1J;

// Save this workbook as an analysis template

// name MyAnalysis.ogw under User Files Folder
save -ik %YMyAnalysis.ogw;

7.2.2.4 Close Workbook

To close workbook, just click the Close button in the top right corner of the workbook. And this
behovior is done by command win -ca, and a dialog pops up to prompt user to delete or hide the
workbook.
// Create a workbook, and name is stored in MyBook$ variable
newbook result:=MyBook$;

// Simulate the Close button clicking

win -ca %(MyBook$);
To close the workbook directly without prompting, and delete all the data, you can use command win
-cd. And this is the same with Delete Workbook below.
// Create a new workbook for closing
newbook;

// close this workbook without prompting, and delete all the data
win -cd %H;

7.2.2.5 Show or Hide Workbook

There are three switches, -ch, -h, and -hc, in win command for showing or hiding workbook.
// Create 3 workbooks for hiding
newbook name:=MyBook1 option:=lsname; // first workbook, MyBook1
newbook name:=MyBook2 option:=lsname; // second workbook, MyBook2
newbook name:=MyBook3 option:=lsname; // third workbook, MyBook3;

// Use -ch to hide the active workbook, MyBook3

// And the View Mode in Project Explorer is Hidden
win -ch 1;

// Use -hc to hide the first workbook (not the active one), MyBook1
// And the View Mode in Project Explorer is Hidden
win -hc 1 MyBook1;

// Use -h to hide the second workbook (active workbook), MyBook2

// The View Mode in Project Explorer is still Normal
win -h 1;

// Actually, MyBook2 is still the active workbook

// It is able to show it by:
win -h 0;

// To show MyBook1 and MyBook3, need to use the -hc switch to specify
// the workbook name
win -hc 0 MyBook1;

133
 LabTalk Scripting Guide

win -hc 0 MyBook3;

7.2.2.6 Name and Label Workbook

For a workbook, there will be short name, Long Name, and Comments. You can rename (short
name) a workbook with win -r command, and use the page object to control Long Name and
Comments, including how to show the workbook title (short name, Long Name, or both).
// Create a new workbook with name of "Data",
// and show both in workbook title
// both short name and Long Name are the same
// workbook title only shows short name
newbook name:=Data option:=lsname;

// Rename the workbook to "RawData"

win -r Data RawData;

// Change Long Name to be "FFT Data"

page.longname$ = "FFT Data";
// Add Comments, "1st group data for fft"
page.comments$ = "1st group data for fft";

// Let the workbook title shows Long Name only

page.title = 1; // 1 = Long Name, 2 = short name, 3 = both

7.2.2.7 Activate Workbook

To activate a workbook, the command win -a can be used.
// The path of project to be opened
string strOpj$ = system.path.program$;
strOpj$ += "Samples\Curve Fitting\Intro_to_Nonlinear_Curve_Fit_Tool.opj";
// Open the project
doc -o %(strOpj$);

// Activate workbook, Book1, in the second subfolder of the project

win -a Book1;

// It also can put the workbook name into a variable

// Variable for the name of workbook, Gaussian, in the project
string strGau$ = Gaussian;
// Activate the Gaussian workbook in the first subfolder
win -a %(strGau$);
Most Origin commands operate on the active window, so you may be tempted to use win -a to
activate a workbook and then run script after it to assume the active workbook. This will work in
simple codes but for longer script, there might be timing issues and we recommend that you use
window -o winName {script} instead. See A Note about Object that a Script Operates upon for more
detail explanation.

7.2.2.8 Delete Workbook

To delete a workbook, you can use the win -c command, and this command will delete the workbook
directly without prompts.
// The path of project to be opened
string strOpj$ = system.path.program$ + "Samples\Curve Fitting\2D Bin and
Fit.opj";
// Open the project
doc -o %(strOpj$);

134
 Workbooks Worksheets and Worksheet Columns

// Delete workbook, Book1, from the project

win -c Book1;

// To delete an active workbook, the workbook name can be omitted

// Or using %H to refer to the workbook name
win -a MatrixFit1; // Activate the workbook MatrixFit1
win -c; // Delete the workbook
// Or using this one
// win -c %H;

// It also allows to delete a workbook whose name is stored in a variable

// Create a new workbook using newbook X-Function
// And the name of this workbook is stored in string variable ToDel$
newbook result:=ToDel$;
// delete the workbook created just now
win -c %(ToDel$);

7.2.3 Workbook Manipulation

Origin provides the capabilities for workbook manipulation by using LabTalk script, such as
duplicating, merging, splitting, etc.

7.2.3.1 Duplicate Workbook

To duplicate active workbook, the win -d command is used. It allows to specify a name for the
duplicated workbook, and the new workbook is activated after duplicated. The command win -da is
doing the similar thing, however, it keeps the active workbook active after duplicated.
// Open a project
string strOpj$ = system.path.program$;
strOpj$ += "Samples\LabTalk Script Examples\Loop_wks.opj";

doc -o %(strOpj$);

// Activate the workbook S2Freq1

win -a S2Freq1;

// Duplicate this workbook, and name it "MyCopy"

// And this new workbook will be activated
win -d MyCopy;

// Duplicate the MyCopy workbook, and name it "MyCopy2"

// But keep MyCopy still activated
win -da MyCopy2;

7.2.3.2 Merge Workbooks

To merge multiple workbooks into one new workbook, the X-Function, merge_book, is available.
// Open a project
string strOpj$ = system.path.program$;
strOpj$ += "Samples\LabTalk Script Examples\Loop_wks.opj";

doc -o %(strOpj$);

// Activate Sample1 folder

pe_cd /Sample1;

135
 LabTalk Scripting Guide

// Merge two workbooks (S1Freq1 and S1Freq2) in two subfolders

// User the source workbook name for the worksheet name in the merged
workbook
merge_book fld:=recursive rename:=sname;

// Activate Sample2 folder

pe_cd /Sample2;

// Merge two workbooks (S2Freq1 and S2Freq2) in two subfolders

// User the source workbook name for the worksheet name in the merged
workbook
merge_book fld:=recursive rename:=sname;

// Activeate the root folder

pe_cd /;

// Two new workbooks are created from the above script

// The names of these two workbooks begin with "mergebook"
// Now, merge these two workbooks into a new workbooks
// The worksheets in the final result workbook will name
// by using the original worksheet name
merge_book fld:=project single:=0 match:=wkbshort key:="mergebook*"
rename:=wksname;

7.2.3.3 Split Workbook

The example above is merging multiple workbooks into one workbook. It is also able to split a
workbook into multiple workbooks, which contain single worksheet. The wsplit_book X-Function is
designed for this purpose.
// Open a project
string strOpj$ = system.path.program$;
strOpj$ += "Samples\COM Server and Client\Basic Stats on Data.opj";

doc -o %(strOpj$);

// There are three worksheets in the active workbook, RawData

// Now split this workbook into three workbooks
// And each workbook will contain one worksheet from the original workbook
wsplit_book fld:=active;

7.3 Worksheets
7.3.1 Worksheets

This section covers the following topics:

 Basic Worksheet Operation

136
 Workbooks Worksheets and Worksheet Columns

 Worksheet Data Manipulation

 Converting Worksheet to Matrix

 Virtual Matrix

7.3.2 Basic Worksheet Operation

The basic worksheet operations include adding worksheet to workbook, activating a worksheet,
getting and setting worksheet properties, deleting worksheet, etc. And these operations can be done
by using Page and Wks objects, together with some Data Manipulation X-Functions. Some practical
examples are provided below.

7.3.2.1 Add New Worksheet

The newsheet X-Function can be used to add new worksheets to a workbook.
// Create a new workbook with 3 worksheets,
// and use "mydata" as long name and short name
newbook name:="mydata" sheet:=3 option:=lsname;
// Add a worksheet named "source" with 4 columns to current workbook
newsheet name:=source cols:=4;

7.3.2.2 Activate a Worksheet

Workbook is an Origin object that contains worksheets which then contain columns. Worksheets in a
workbook are internally layers in a page. In other words, a worksheet is derived from a layer object
and a workbook derived from a page object. The active layer in a page is represented by the
page.active or page.active$ property, and thus it is used to active a worksheet.
// Create a new workbook with 4 worksheets
newbook sheet:=4;

page.active = 2; // Active worksheet by index

page.active$ = sheet3; // Active worksheet by name

7.3.2.3 Modify Worksheet Properties

Using Worksheet Object

When a worksheet is active, you can type wks.= and press Enter to list all worksheet properties.
Most of these properties are writable so you can modify it directly. For example:
// Rename the active worksheet
wks.name$ = Raw Data;
// Set the number of columns to 4
wks.ncols = 4;
// Modify the column width to 8 character
wks.colwidth = 8;
// Show the first user-defined parameter on worksheet header
wks.userparam1 = 1;

137
 LabTalk Scripting Guide

Two properties, wks.maxRows and wks.nRows are similar. The former one find the largest row index
that has value in the worksheet, while the later set or read the number of rows in the worksheet. You
can see the different in the following script.
newbook; // Create a new workbook
col(b) = {1:10}; // Set column B with 1-10 for the first ten rows
wks.maxRows = ;
wks.nRows = ;
Origin outputs 10 for wks.maxRows; while outputs 32 for wks.nRows.
If the worksheet is not the active one, you can specify the full worksheet name (including workbook
name) before wks object, the syntax is
[WorkbookName]WorksheetNameOrIndex!wks
Or you can use the range of the worksheet. For example
// Open a project
string strOpj$ = system.path.program$;
strOpj$ += "Samples\COM Server and Client\Basic Stats on Data.opj";
doc -o %(strOpj$);

wks.nCols = ; // Output number of columns in the active worksheet

// Output number of columns in the worksheet [RawData]Data!
[RawData]Data!wks.nCols = ;
// Output the name of the first worksheet in RawData workbook
[RawData]1!wks.name$ = ;

// Use range
range rWks = [RawData]Data!; // Range for the Data worksheet in RawData
workbook
rWks.userparam1 = 1; // Show the first user-defined parameter in worksheet

Using X-Functions

Besides wks object, you can also use X-Functions to modify worksheet properties. These X-Function
names are usually with the starting letter "w". Such as wcolwidth, wcellformat and wclear, etc. So we
can also resize the column with as below without using wks.colwidth:
wcolwidth 2 10; // Set the 2nd column width to 10

7.3.2.4 Delete Worksheet

The layer -d command can be used to delete a worksheet or graph layer.
// Create a new workbook with 6 worksheets
// Workbook name is stored into MyBook$
// And the first worksheet will be the active one
newbook sheet:=6 result:=MyBook$;

// Add a new worksheet with name of "My Sheet"

newsheet name:="My Sheet";

page.active = 1; // Activate the first worksheet

layer -d; // Delete the active worksheet

// Delete a worksheet by index

// Delete the third worksheet (or layer) in the active workbook (or graph)
layer -d 3;

// Delete a worksheet by name

layer -d "Sheet5";

138
 Workbooks Worksheets and Worksheet Columns

// Delete a specified worksheet by range

range rs = [%(MyBook$)]"My Sheet"!; // Define a range to a specified
worksheet
layer -d rs;

// Delete a worksheet whose name is stored in a string variable

string strSheet$ = "Sheet3";
layer -d %(strSheet$);
To delete a worksheet whose name is stored in a string variable, there are some special string
variables for some special worksheets, for example:
//__report$ holds the name of the last report sheet Origin created
layer -d %(__report$);
The variable __report$ is an example of a system-created string variable that records the last-used
instance of a particular object. A list of such variables can be found in Reference Tables.

7.3.3 Worksheet Data Manipulation

In this section we present examples of X-Functions for basic data processing. For direct access to
worksheet data, see Range Notation.

7.3.3.1 Copy Worksheet Data

Copy a Worksheet

The wcopy X-Function is used to create a copy worksheet of the specified worksheet.
The following example duplicates the current worksheet, creating a new workbook with the copied
worksheet:
wcopy 1! [<new>]1!;

Copy a Range of Cells

The wrcopy X-Function is used to copy a range of cells from one worksheet to another. It also allows
you to specify a source row to be used as the Long Names in the destination worksheet.
The following script copies rows from 5 to 9 of [book1]sheet1! to a worksheet named CopiedValues in
Book1 (if the worksheet does not exist it will be created), and assigns the values in row 4 from
[book1]sheet1! to the long name of the destination worksheet, [book1]CopiedValues!
wrcopy iw:=[book1]sheet1! r1:=5 r2:=10 name:=4 ow:=CopiedValues!;
To copy column and matrix object, please refer to Copy Column and Copy Matrix Data respectively.

7.3.3.2 Reduce Worksheet Data

Origin has several data reducing X-Functions like reduce_ex, reducedup, reducerows and reducexy.
These X-Functions provide different ways of creating a smaller dataset from a larger one. Which one
you choose will depend on what type of input data you have, and what type of output data you want.

Examples

The following script will create a new X and Y column where the Y will be the mean value for each of
the duplicate X values.
reducedup col(B);

139
 LabTalk Scripting Guide

The following script will reduce the active selection (which can be multiple columns or an entire
worksheet, independent of X or Y plotting designation) by a factor of 3. It will remove rows 2 and 3
and then rows 5 and 6, leaving rows 1 and 4, etc. By default, the reduced values will go to a new
worksheet.
reducerows npts:=3;
The following script will average every n numbers (5 in the example below) in column A and output
the average of each group to column B. It is the same as the ave LabTalk function, which would be
written as col(b)=ave(col(a),5):
reducerows irng:=col(A) npts:=5 method:=ave rd:=col(b);

7.3.3.3 Extract Worksheet Data

Partial data from a worksheet can be extracted using conditions involving the data columns, using the
wxt X-function.
// Import a sample data file
newbook;
string fname$ = system.path.program$ + "samples\statistics\automobile.dat";
impasc;
// Define range using some of the columns
range rYear=1, rMake=2, rHP=3;
type "Number of rows in raw data sheet= $(rYear.GetSize())";
// Define a condition string and extract data
// to a new named sheet in the same book
string strCond$="rYear >= 1996 and rHP<70 and rHP>60 and rMake[i]$=Honda";
wxt test:=strCond$ ow:="Extracted Rows"! num:=nExtRows;
type "Number of rows extracted = $(nExtRows)";

Output To New Workbook

You can also direct the output to a new workbook, instead of a new worksheet in the existing
workbook, by changing the following line:
wxt test:=strCond$ ow:=[<new name:="Result">]"Extracted"! num:=nExtRows;
As you can see, the only difference from the earlier code is that we have added the workbook part of
the range notation for the ow variable, with the <new> keyword. (show links and indexing to <new>
modifiers, options, like template, name, etc)

Use Wildcard Search

LabTalk uses * and ? characters for wildcard in string comparison. You can try changing the strCond
as follows:
string strCond$ = "rYear >= 1996 and rHP<70 and rHP>60 and rMake[i]$=*o*";
to see all the other makes of cars with the letter o.

7.3.3.4 Delete Worksheet Data

Deleting the Nth row can be accomplished with the reducerows X-Function, described above.
This example demonstrates deleting every Nth column in a worksheet using a for-loop:
int ndel = 3; // change this number as needed;
int ncols = wks.ncols;
int nlast = ncols - mod(ncols, ndel);
// Need to delete from the right to the left
for(int ii = nlast; ii > 0; ii -= ndel)
{

140
 Workbooks Worksheets and Worksheet Columns

delete wcol($(ii));
}

7.3.3.5 Sort Worksheet

The following example shows how to perform nested sorting of data in a worksheet using the wsort
X-Function:
// Start a new book and import a sample file
newbook;
string fname$ = system.path.program$ + "Samples\Statistics\automobile.dat";
impasc;
// Set up vectors to specify nesting of columns and order of sorting;
// Sort nested: primary col 2, then col 1, then col 3:
dataset dsCols = {2, 1, 3};

// Sort col2 ascending, col 1 ascending, col 3 descending:

dataset dsOrder = {1, 1, 0};

wsort nestcols:=dsCols order:=dsOrder;

7.3.3.6 Split Worksheet

Origin provides the X-Function, wsplit, for the purpose of splitting one worksheet's columns into
multiple worksheets.
The example below is going to import multiple CSV files, and then get the Amplitude data from all the
data file into a worksheet, and then convert this worksheet to matrix to make a contour plot.
// Create a new workbook
newbook;

// Find all csv files in the specified folder

string strPath$ = system.path.program$ + "Samples\Batch Processing\";
findfiles path:=strPath$ fname:=csvFiles$ ext:=csv;

// Import all found csv files into one worksheet

impCSV fname:=csvFiles$ // All found csv files
options.Mode:=1 // From second file, start new column
options.names.FNameToSht:=0 // Not rename worksheet
options.names.FNameToBk:=0 // Not rename workbook
options.HeaderLines.SubHeaderLines:=2 // Two subheader lines
options.HeaderLines.LongNames:=1 // First subheader line is LongName
options.HeaderLines.Units:=2; // Second subheader line is Units

// Split the worksheet according to the Long Name

// The columns with the same Long Name will be in the same result worksheet
// All the result worksheets will be in the same new workbook
wsplit mode:=label label:=L;

// Activate the Amplitude worksheet

page.active$ = Amplitude;

// Convert the Amplitude worksheet to matrix directly

w2m;

// Make a contour for the amplitude

worksheet -p 226 contour;

141
 LabTalk Scripting Guide

7.3.3.7 Unstack/Stack Categorical Data

Unstack Worksheet Columns

At times unstacking categorical data is desirable for analysis and/or plotting purposes. The
wunstackcol X-Function is the most convenient way to perform this task from script.
In this example, categorical data is imported, and we want to unstack the data by a particular
category, which we specify with the input range irng2. The data to be displayed (by category) is
referenced by input range irng1. In this example, the column ranges are input directly, but range
variables can also be used.
// Import automobile data
newbook;
string fpath$ = "\Samples\Statistics\Automobile.dat";
string fname$ = system.path.program$ + fpath$;
impasc;

// Unstack all other columns using automobile Make, stored in col 2

// Place "Make" in Comments row of output sheet
wunstackcol irng1:=(1, 3:7) irng2:=2 label:="Comments";
The result is a new worksheet with the unstacked data.

Stack Worksheet Columns

Staking categorical data is something like reverse operation of unstacking categorical data. In the
original dataset, samples belong to different groups is stored in different columns. After stacking, the
samples will be in different rows in the same column, with an additional column in the worksheet
providing the group information. You can use wstackcol to stack worksheet columns.
In the following example, we open a workbook with categorical data first. And then with the first
worksheet activated, and stack column B, C, and D by rows, including another column to be A.
// Open a workbook
string strBook$ = system.path.program$;
strBook$ += "Samples\Statistics\Body.ogw";
doc -o %(strBook$);

// Stack column B, C, D in Male worksheet

// Include column A as another column
// Method is By Rows
wstackcol irng:=(2:4) tr.identifiers:={L} include:=1 method:=1;
The result is a new worksheet in the same workbook with the stacked data.

7.3.3.8 Pivot Table

The wpivot X-Function is available for the purpose of quickly summarizing the data, so to analyze,
compare, and detect the relationships in the data. That is an easy way to present data information.
// Create a new workbook
// And import a data file
newbook;
fname$ = system.path.program$ +
"Samples\Statistics\HouseholdCareSamples.xls";
impExcel lname:=1;

// Make sure "HQ Family Mart" worksheet is activate

// And make a copy of this worksheet
page.active$ = "HQ Family Mart";

142
 Workbooks Worksheets and Worksheet Columns

wcopy ow:=[<new>]"HQ Family Mart"!;

// Pivot table, row source is Make

// Column source is Brand, and data is Number in shelf
// The result will show the number of products in shelf
// for different brands and different makes
wpivot row:=col(D) col:=col(F) data:=col(K)
method:=sum total:=1 sort_total:=no sum:=1;

// Activate the source data worksheet

page.active$ = "HQ Family Mart";

// Pivot table, row source, column source and data column are the same
// For the smaller values, it will combine them across columns
// by 10% of the total
// In the result worksheet, the column info. is put to user-defined parameter
rows
// The row name is the name of column's Long Name in source worksheet
wpivot row:=col(D)
col:=col(F)
data:=col(K)
method:=sum total:=1 sort_total:=no sum:=1
dir:=col threshold:=10 // Combine smaller values across column, by
10%
// Put column info (from column's Long Name) to user-defined
parameters row
pos:=udl udlabel:=L;

7.3.3.9 Worksheet Filter

Worksheet Filter (Data Filter) in Origin is column-based filter to reduce rows of worksheet data by
using the specified condition, so to hide the undesired rows for relevant data analysis and graphing.
Three data formats are supported: numeric, text and date/time. In LabTalk, you can use the wks.col
(wks.col.filter, wks.col.filter$, wks.col.filterenabled, wks.col.filterprescript$, and wks.col.filterx$) object
to handle the data filter. And to run/re-apply the filter, use the wks.runfilter() method.
// Create a new workbook, and import the data
newbook;
string fname$ = system.path.program$ + "Samples\Statistics\Automobile.dat";
impasc;

// Set data filter for column 1, numeric type

wks.col1.filter = 1; // Add filter
wks.col1.filterx$ = year; // Set the variable "year" to represent column 1
// Set filter condition, between 1995 and 2000
wks.col1.filter$ = "year.between(1995,2000)";

// Set data filter for column 2, text type

wks.col2.filter = 1; // Add filter
wks.col2.filterx$ = make; // Set the variable "make" to represent column 2
// Set before query script
wks.col2.filterprescript$ = "string strFavorite$ = GMC";
wks.col2.filter$ = "make = strFavorite$"; // Set filter query string

// Run the worksheet filter

wks.runfilter();

// Disable the filter in column 1

143
 LabTalk Scripting Guide

wks.col1.filterenabled = 0;

// Re-apply the worksheet filter

wks.runfilter();
To detect whether there is filter in a worksheet, you can use the wks.hasfilter() method.
// If the active worksheet has filter, return 1, otherwise, return 0
wks.hasfilter() = ;

7.3.3.10 Insert Links into Worksheet Cells

Origin provides several cell linking syntax for adding links into worksheet cell, so to easily access or
display the linked resource. Available cell linking syntax are included in the following table.
Syntax Description Example

Insert a link to
another cell, given
by CellName, so
cell://CellName to display its cell://[Book2]Sheet2!Col(B)[3]
contents in the
current worksheet
cell.

Insert a link to a
range, given by
RangeName,
which can be
book, sheet,
column, etc. The
contents in the
current worksheet
cell will show as a
range://RangeName
link, if clicked, the range://[Book2]Sheet2!Col(B)[3]
[DisplayedText]
corresponding
range will be
activated. If the
option
DisplayedText is
included, the
displayed text in
the cell is this text,
but not the range.

Insert a link to a
graph, given by
GraphName, so
the graph will be
displayed in the
graph://GraphName current worksheet graph://Graph1
cell. If double-click
on this cell, the
corresponding
graph window will
be activated.

144
 Workbooks Worksheets and Worksheet Columns

Insert a link to a
matrix object,
given by
MatrixObjectNam
e, so the matrix
object will be
matrix://MatrixObjectNa displayed in the
matrix://[MBook1]MSheet1!2
me current worksheet
cell, as an image.
If double-click on
this cell, the
corresponding
matrix window will
be activated.

Insert a link to a
Notes window,
given by
NotesWindowNa
me. The contents
notes://NotesWindowNa
in this cell will notes://Notes
me [DisplayedText]
show as a link, if
clicked, the
corresponding
Notes window will
be activated.

Insert a link to a
LabTalk variable,
var://LabTalkVariableNa
and the value of var://MyVar
me
this variable will
show in this cell.

Insert a link to a
LabTalk string
str://LabTalkStringVaria
variable, and this str://MyBook$
ble
string will show in
this cell.

Insert a live URL

into worksheet
cells. The link will
become active
when finishing
editing, and the
corresponding
http://URL
page will be http://www.originlab.com
[DisplayedText]
opened in a web
browser if clicked.
If the option
DisplayedText is
included, the
displayed text in
the cell is this text,

145
 LabTalk Scripting Guide

but not the URL.

If the option
DisplayedText is
included, the
help://HelpPage help://TUTORIAL.CHM/Tutorial/Import_Wizard
displayed text in
[DisplayedText] .html
the cell is this text,
but not the help
link.

Insert a link to an
image file, given
by FilePath. And
file://FilePath file://D:\Flower.jpg
the linked image
will display in the
current cell.

7.3.4 Converting Worksheet to Matrix

You may need to re-organize your data by converting from worksheet to matrix, or vice versa, for
certain analysis or graphing needs. This page provides information and examples of converting
worksheet to matrix, and please refer to Converting Matrix to Worksheet for the "vice versa" case.

7.3.4.1 Worksheet to Matrix

Data contained in a worksheet can be converted to a matrix using a set of Gridding X-Functions.
The w2m X-Function converts matrix-like worksheet data directly into a matrix. Data in source
worksheet can contain the X or Y coordinate values in the first column, first row, or a header row.
However, because the coordinates in a matrix should be uniform spaced, you should have uniformly
spaced X/Y values in the source worksheet.
If your X/Y coordinate values are not uniform spaced, you should use the Virtual Matrix feature
instead of converting to a matrix.
The following example show how to perform direct worksheet to matrix conversion:
// Create a new workbook
newbook;
// Import sample data
string fname$ = system.path.program$ +
"\samples\Matrix Conversion and Gridding\DirectXY.dat";
impasc;
// Covert worksheet to matrix, first row will be X and first column will be Y
w2m xy:=xcol xlabel:=row1 ycol:=1;
// Show X/Y values in the matrix window
page.cntrl = 2;
When your worksheet data is organized in XYZ column form, you should use Gridding to convert
such data into a matrix. Many gridding methods are available, which will interpolate your source data
and generate a uniformly spaced array of values with the X and Y dimensions specified by you.
The following example converts XYZ worksheet data by Renka-Cline gridding method, and then
creates a 3D graph from the new matrix.
// Create a new workbook without sheets
newbook;
// Import sample data
string fname$ = system.path.program$ +
"\samples\Matrix Conversion and Gridding\XYZ Random Gaussian.dat";
impasc;

146
 Workbooks Worksheets and Worksheet Columns

// Convert worksheet data into a 20 x 20 matrix by Renka-Cline gridding

method
xyz_renka 3 20 20;
// Plot a 3D color map graph
worksheet -p 242 cmap;

7.3.5 Virtual Matrix

Data arranged in a group of worksheet cells can be treated as a matrix and various plots such as 3D
Surface, 3D Bars, and Contour can be created from such data. This feature is referred to as Virtual
Matrix. The X and Y coordinate values can be optionally contained in the block of data in the first
column and row, or also in a header row of the worksheet.
Whereas Matrix objects in Origin only support linear mapping of X and Y coordinates, a virtual matrix
supports nonlinear or unevenly spaced coordinates for X and Y.
The virtual matrix is defined when data in the worksheet is used to create a plot. The plotvm X-
Function should be used to create plots.
The following example shows how to use the plot_vm X-Function:
// Create a new workbook and import sample data
newbook;
string fname$=system.path.program$ + "Samples\Graphing\VSurface 1.dat";
impasc;
// Treat entire sheet as a Virtual Matrix and create a colormap surface plot
plotvm irng:=1! format:=xacross rowpos:=selrow1 colpos:=selcol1
ztitle:="VSurface 1" type:=242 ogl:=<new template:=cmap>;
// Change X axis scale to log
layer.x.type=2;

7.4 Worksheet Columns

7.4.1 Worksheet Columns

This chapter covers the following topics:

 Basic Worksheet Column Operation

 Worksheet Column Data Manipulation

 Date and Time Data

7.4.2 Basic Worksheet Column Operation

To perform operations on worksheet columns, in most situations, you can use wks.col object, or the
Range Notation to the column object.

7.4.2.1 Add or Insert Column

147
 LabTalk Scripting Guide

To add a column to the end of the worksheet, you can use the wks.addCol() method, which will add a
column with the specified name, if the specified name is used or ignored, a generic name is chosen
for the newly added column.
// Create a new workbook
newbook;

// Add a new column to the end, with name of Result

wks.addCol(Result);
The method above is only able to add one column to the end at a time. If you are going to add a
multiple columns, you can add columns by setting the number of columns in the worksheet with the
wks.nCols property. For example, the script below will add 3 columns to the end of the active
worksheet with the generic names (Note: it is not able to specify the names in this way, please refer
to Rename and Label Column section below).
// Create a new workbook
newbook;

// Add 3 columns to the end of worksheet

wks.nCols = wks.nCols + 3;
Besides adding columns to the end of the worksheet, it is also capable of inserting numbers of
columns before the current column. First of all, it needs to specify which column (by 1-based index) is
the current column using wks.col property, and then using wks.insert() method to insert column(s)
before the current column. In the method, you need to specify a list of column names separated by
space.
// Create a new workbook
newbook;

// Set column 2 to be the current column

wks.col = 2;

// Insert 3 column before column 2, with the specify column names

wks.insert(DataX DataY Result);

7.4.2.2 Insert or Delete Rows in Columns

To delete or insert rows in worksheet columns, you can use the wks.deleteRows() or
wks.insertRows() methods.
The syntax is as follows ...
wks.deleteRows(rowBegin[,numRows, colBegin, colEnd])
wks.insertRows(rowBegin[,numRows, colBegin, colEnd])
... with arguments inside the square brackets being optional.
Examples are given below:
wks.deleteRows(3); // Delete the third row in all columns
wks.deleteRows(3, 5); // Delete 5 rows beginning with the third row in all
columns:
wks.deleteRows(3, 5, 2); // Delete 5 rows beginning with the third row in
columns from the second to the end
wks.deleteRows(3, 5, 2, 4); // Delete 5 rows beginning with the third row in
columns 2 to 4

wks.insertRows(3); // Insert a row in front of the third row in all columns

wks.insertRows(3, 5); // Insert 5 rows in front of the third row in all
columns
wks.insertRows(3, 5, 2); // Insert 5 rows in front of the third row in
columns from the second to the end

148
 Workbooks Worksheets and Worksheet Columns

wks.insertRows(3, 5, 2, 4); // Insert 5 rows in front of the third row in

columns 2 to 4
Note that the wdelrows X-Function can also be used to delete worksheet rows.

7.4.2.3 Move Column

The colmove X-Function allows you to move column(s) of data within a worksheet. It accepts an
explicitly stated range (as opposed to a range variable), and the type of move operation as inputs.
// Make the first column the last (left to right) in the worksheet:
colmove rng:=col(1) operation:=last;

// Move columns 2-4 to the leftmost position in the worksheet:

colmove rng:=Col(2):Col(4) operation:=first;

7.4.2.4 Rename and Label Column

To rename (short name) a column, Origin provides the wks.col object with the name$ property. Also,
the Column Label Row Characters, G, is able to rename column short name.
// Create a new workbook
newbook;

// Rename column 1 to DataX

wks.col1.name$ = DataX;
// Rename column 2 to DataY by using range
range rY = 2; // range to column 2
rY.name$ = DataY;

// Add a new column

wks.addCol();
// Rename it with "G"
col(3)[G]$ = "Result";
The Column Label Row Characters are the convenient way to access the column labels, including
Long Name, Units, Comments, Column Parameters, User-Defined Parameters, etc.
// Create a new workbook
newbook result:=BkName$;

// Show the following label rows:

// Long Name, Units, Comments, 1st Column Parameter
// and 1st User-Defined Parameter
wks.labels(LUCP1D1);

// Ranges to column 1 and 2

range r1 = [%(BkName$)]1!1;
range r2 = [%(BkName$)]1!2;
// Set Long Name by using col
col(1)[L]$ = Time;
col(2)[L]$ = Voltage;
// Set Units by using range
r1[U]$ = Sec;
r2[U]$ = V;
// Set Comments by using range
r1[C]$ = Sample1;
r2[C]$ = Sample1;
// Set Column Parameters by using range
r1[P1]$ = "Machine1";
r2[P1]$ = "Machine1";

149
 LabTalk Scripting Guide

// Rename the 1st User-Defined Parameter

wks.UserParam1$ = Current;

// Set Current label row

r1[Current]$ = 1mA;
r2[Current]$ = 1mA;

7.4.2.5 Hide/Unhide Column

To hide/unhide column(s), you can use the colHide X-Function.
// Create a new workbook
newbook;

// Set worksheet column number to 6

wks.nCols = 6;

// Hide the second column

colHide 2 hide;

// Hide the 3rd and 5th columns

colHide (3, 5) hide;
To show (unhide) column(s), it just changes the second argument from hide to unhide.

7.4.2.6 Swap Column

The colSwap X-Function is used to swap two specified columns.
// Create a new workbook
newbook;

// Swap the position of the 1st and 2nd columns

colSwap (1, 2);
The specified two columns is not needed to be adjacent.
// Create a new workbook
newbook;

// Set number of columns to be 6

wks.ncols = 6;

// Swap the 2nd and 4th columns

colswap (2, 4);

7.4.2.7 Modify Column Formats

Plot Designation

Plot designation for a column determines how the selected data will be handled by default for plotting
and data analysis. Plot designation includes X, Y, Z, Z Error, Y Error, Label, etc. And you can change
it by using wks.col.type.
// Import data
newbook;
string fname$ = system.path.program$;
fname$ += "Samples\Matrix Conversion and Gridding\XYZ Random Gaussian.dat";
impasc;

150
 Workbooks Worksheets and Worksheet Columns

// Set column designation (column type)

wks.col = 3; // Set column 3 to be current column
wks.col.type = 6; // Z

// Select the 3rd column (Z column)

worksheet -s 3 1 3 -1;
// Make a color map surface with the template based on OpenGL
worksheet -p 103 glcmap;

Column Width

To set column width, the wcolwidth X-Function is available, or use wks.col.width.

// Open a workbook
string strPath$ = system.path.program$;
strPath$ += "Samples\Graphing\Automobile Data.ogw";
doc -o %(strPath$);

// To make column 2 show all the numbers but not ###

// Set width of column 2 to 6 characters
wcolwidth irng:=col(2) width:=6;

Data Format and Display

Setting a correct data format for a column helps to display the data in the column correctly, also helps
to perform operations, such plotting, data analysis, etc. properly. There are many data format
available for a column, such as Numeric, Text, Date, Time, Month, Day of Week, etc. To set format,
please use wks.col object's format property.
// Import data
newbook;
string fname$ = system.path.program$;
fname$ += "Samples\Signal Processing\Average Sunspot.dat";
impasc;

// Set column 2 to Numeric (current is Text & Numeric)

wks.col2.format = 1; // Numeric = 1

// Enable digit mode to be "Set Decimal Places"

// and set number of decimal places to 2
wks.col2.digitMode = 1; // Set Decimal Places
wks.col2.digits = 2; // Two decimal places
The following examples are showing the corresponding settings for different format.
1. Numeric

// Import data
newbook;
string fname$ = system.path.program$;
fname$ += "Samples\Curve Fitting\Enzyme.dat";
impasc;

// Set column 2 to Numeric (current is Text & Numeric)

wks.col2.format = 1; // Numeric = 1
// Set display format with comma
wks.col2.subformat = 4; // Display as Decimal: 1,000

151
LabTalk Scripting Guide

// Data type to be short int

wks.col2.numerictype = 3;

// Do the same for column 3

wks.col3.format = 1; // Numeric = 1
// Set display format with comma
wks.col3.subformat = 4; // Display as Decimal: 1,000
// Data type to be short int
wks.col3.numerictype = 3;
2. Date

For Date and Time format, if the data stored in a column is not Julian day numbers (looks
like Date and Time format, actually is text), we cannot set the format as Date or Time
directly, or the look-like-Date-and-Time-format text will become missing value or something
incorrect. To avoid this issue, Origin provides the wks.col.setformat() method.
// Import data
newbook;
string fname$ = system.path.program$;
fname$ += "Samples\Import and Export\Custom Date and Time.dat";
impasc;

// Set format of column 1 to be Date

// with a custom display format, which is like
// the current text display in the column
wks.col1.setformat(4, 22, dd'.'MM'.'yyyy HH':'mm':'ss'.'##);
// Set a familiar display format yyyy/MM/dd HH:mm:ss
wks.col1.subformat = 11;
3. Time

Please refer to the description about Date above.

// Import data
newbook;
string fname$ = system.path.program$;
fname$ += "Samples\Import and Export\IRIG Time.dat";
impasc;

// Set format of column 1 to be Time

wks.col1.format = 3; // Time = 3
// Display IRIG Time format DDD:HH:mm:ss.##
wks.col1.subformat = 16;
4. Month

// Set column 1 format as Month

// And show the whole name of month
wks.col1.format = 5; // Month = 5
wks.col1.subformat = 2; // Show the whole month's name
5. Day of Week

// Set column 1 format as Day of Week

// And show only the first letter of each day of week
wks.col1.format = 6; // Day of Week = 6

152
 Workbooks Worksheets and Worksheet Columns

wks.col1.subformat = 3; // Show the first letter of each day of week

7.4.2.8 Add Sparkline to Column

The sparklines X-Function is used to add sparklines to the specified columns in the worksheet.
// Open a workbook
string strPath$ = system.path.program$;
strPath$ += "Samples\Graphing\Automobile Data.ogw";
doc -o %(strPath$);

// Turn on sparklines for all columns except the ones with "Year" Long Name
for(ii = 2; ii <= wks.nCols; ii+=5)
{
sparklines sel:=0 c1:=ii c2:=ii+3;
}

7.4.2.9 Delete Column

The delete command is capable of removing a column from worksheet.
// Create a workbook
newbook;

// Delete column B
delete col(B);

// Add a new worksheet with 4 columns

newsheet cols:=4;

// Delete column 3 by using range

range rr = 3; // column 3 in the newly added worksheet
delete rr;
If the column(s) you want to delete is (are) at the end of the worksheet, you can just set the number
of worksheet columns to delete it (them), by using wks.nCols.
// Open a workbook
string strPath$ = system.path.program$;
strPath$ += "Samples\Graphing\Automobile Data.ogw";
doc -o %(strPath$);

// Delete last 20 columns from the opened worksheet

wks.nCols = wks.nCols-20;

7.4.3 Worksheet Column Data Manipulation

7.4.3.1 Basic Operation
Once you have loaded or created some numeric data, here are some script examples of things you
may want to do.

Basic Arithmetic

Most often data is stored in columns and you want to perform various operations on that data in a
row-wise fashion. You can do this in two ways in your LabTalk scripts: (1) through direct statements
with operators or (2) using ranges. For example, you want to add the value in each row of column A
to its corresponding value in column B, and put the resulting values in column C:

153
 LabTalk Scripting Guide

Col(C) = Col(A) + Col(B); // Add

Col(D) = Col(A) * Col(B); // Multiply
Col(E) = Col(A) / Col(B); // Divide
The - and ^ operators work the just as above for subtraction and exponentiation respectively.
You can also perform the same operations on columns from different sheets with range variables:
// Point to column 1 of sheets 1, 2 and 3
range aa = 1!col(1);
range bb = 2!col(1);
range cc = 3!col(1);
cc = aa+bb;
cc = aa^bb;
cc = aa/bb;

When performing arithmetic on data in different sheets, you need to use range
variables. Direct references to range strings are not supported. For example, the script
Sheet3!col(1) = Sheet1!col(1) + Sheet2!col(1); will not work!

Functions

In addition to standard operators, LabTalk supports many common functions for working with your
data, from trigonometric functions like sin and cos to Bessel functions to functions that generate
statistical distributions like uniform and Poisson. All LabTalk functions work with single-number
arguments of course, but many are also "vectorized" in that they work on worksheet columns, loose
datasets, and matrices as well. Take the trigonometric function sin for example:
// Find the sine of a number:
double xx = sin(0.3572)
// Find the sine of a column of data (row-wise):
Col(B) = sin(Col(A))
// Find the sine of a matrix of data (element-wise):
[MBook2] = sin([MBook1])
As an example of a function whose primary job is to generate data consider the uniform function,
which in one form takes as input N, the number of values to create, and then generates N uniformly
distributed random numbers between 0 and 1:
/* Fill the first 20 rows of Column B
with uniformly distributed random numbers: */
Col(B) = uniform(20);
For a complete list of functions supported by LabTalk see Alphabetic Listing of Functions.

7.4.3.2 Set Formula for Column

In the Origin GUI, the Set Column Values dialog can be used to generate or transform data in
worksheet columns using a specified formula. Such transformation can also be performed in LabTalk
by using the csetvalue X-Function. Here are some examples on how to set column value using
LabTalk.
newbook;
wks.ncols = 3;
// Fill column 1 with random numbers
csetvalue formula:="rnd()" col:=1;
// Transform data in column 1 to integer number between 0 ~ 100
csetvalue formula:="int(col(1)*100)" col:=2;
// Specify Before Formula Script when setting column value
// and set recalculate mode to Manual

154
 Workbooks Worksheets and Worksheet Columns

csetvalue formula:="mm - col(2)" col:=3 script:="int mm = max(col(2))"

recalculate:=2;
string str$ = [%h]%(page.active$)!;
newsheet cols:=1;
// Use range variables to refer to a column in another sheet
csetvalue f:="r1/r2" c:=1 s:="range r1=%(str$)2; range r2=%(str$)3;" r:=1;

When logic statement is used to set formula for columns, values such as 0.0, NANUM
(missing value) and values between -1.0E-290 to 1.0E-290 will be evaluated to be
False. For instance, LabTalk command will return a value 0 (False) instead of 1
(True).
type $(-1e-290?1:0); // Returns 0 (False)
type $(1/0?1:0); // Returns 0 (False), where 1/0 == NANUM

7.4.3.3 Copy Column

The colcopy X-Function copies column(s) of data including column label rows and column format
such as date or text and numeric.
The following example copies columns two through four of the active worksheet to columns one
through three of sheet1 in book2:
// Both the data and format as well as each column long name,
// units and comments gets copied:
colcopy irng:=(2:4) orng:=[book2]sheet1!(1:3) data:=1
format:=1 lname:=1 units:=1 comments:=1;

7.4.3.4 Sort Column

To sort a specified column, you can use wsort X-Function. And when using this X-Function to sort just
one column, the arguments c1 and c2 should be the same column in worksheet, and the bycol also
needs to be the same as c1.
// Create a new workbook
newbook;

// Fill first column with row number, and second column with uniform random
number
col(1) = {1:32};
col(2) = uniform(32);

// Sort column 2 descending

wsort c1:=2 c2:=2 bycol:=2 descending:=1;

7.4.3.5 Reverse Column

The X-Function colreverse is available for reversing column.
// Create a new workbook
newbook;

// Fill first column with row number, and second column with uniform random
number
col(1) = {1:32};
col(2) = uniform(32);

// Reverse column 1 by using index

colreverse rng:=1; // colreverse rng:=col(A); // this also works

// Reverse column 2 by using range variable

155
 LabTalk Scripting Guide

range rr = 2;
colreverse rng:=rr;

7.4.4 Date and Time Data

While the various string formats used for displaying date and time information are useful in conveying
information to users, a mathematical basis for these values is needed to provide Origin with plotting
and analysis of these values. Origin uses a modification of the Astronomical Julian Date system to
store dates and time. In this system, time zero is 12 noon on January 1, 4713 BCE. The integer part
of the number represents the number of days since time zero and the fractional part is the fraction of
a 24 hour day. Origin offsets this value by subtracting 12 hours (0.50 days) to put day transitions at
midnight, rather than noon.
The next few examples are dedicated to dealing with date and time data in your LabTalk scripts.
Note : Text that appears to be Date or Time may in fact be Text or Text & Numeric which would not
be treated as a numeric value by Origin. Use the Column Properties dialog (double-click a column
name or select a column and choose Format : Column) to convert a Text or Text & Numeric column
to Date or Time Format. The Display format should match the text format in your column when
converting.

7.4.4.1 Dates and Times

As an example, say you have Date data in Column 1 of your active sheet and Time data in Column 2.
You would like to store the combined date-time as a single column.
/* Since both date and time have a mathematical basis,
they can be added: */
Col(3) = Col(1) + Col(2);

// By default, the new column will display as a number of days ...

/* Use format and subformat methods to set
the date/time display of your choice: */

// Format #4 is the date format

wks.col3.format = 4;
// Subformat #11 is MM/dd/yyyy hh:mm:ss
wks.col3.subformat = 11;
The column number above was hard-coded into the format statement; if instead you had the column
number as a variable named cn, you could replace the number 3 with $(cn) as in
wks.col$(cn).format = 4. For other format and subformat options, see LabTalk Language
Reference: Object Reference: Wks.col (object).
If our date and time column are just text with a MM/dd/yyyy format in Column 1 and hh:mm:ss
format in Column 2, the same operation is possible with a few more lines of code:
// Get the number of rows to loop over.
int nn = wks.col1.nrows;

loop(ii,1,nn){
string dd$ = Col(1)[ii]$;
string tt$ = Col(2)[ii]$;
// Store the combined date-time string just as text
Col(3)[ii]$ = dd$ + " " + tt$;
// Date function converts the date-time string to a numeric date value
Col(4)[ii] = date(%(dd$) %(tt$));
};
// Now we can convert column 4 to a true Date column
wks.col4.format = 4; // Convert to a Date column
wks.col4.subformat = 11; // Display as M/d/yyyy hh:mm:ss

156
 Workbooks Worksheets and Worksheet Columns

Here, an intermediate column has been formed to hold the combined date-time as a string, with the
resulting date-time (numeric) value stored in a fourth column. While they appear to be the same text,
column C is literally just text and column D is a true Date.
Given this mathematical system, you can calculate the difference between two Date values which will
result in a Time value (the number of days, hours and minutes between the two dates) and you can
add a Time value to a Date value to calculate a new Date value. You can also add Time data to Time
data and get valid Time data, but you cannot add Date data to Date data.

7.4.4.2 Formatting for Output

Available Formats

Use the D notation to convert a numeric date value into a date-time string using one of Origin's built-
in Date subformats:
type "$(@D, D10)";
returns the current date and time (stored in the system variable @D) as a readable string:
7/20/2009 10:30:48
The D10 option corresponds to the MM/dd/yyyy hh:mm:ss format. Many other output formats are
available by changing the number after the D character, which is the index entry (from 0) in the Date
Format drop down list of the Worksheet Column Format dialog box, in the line of script above. The
first entry (index = 0) is the Windows Short Date format, while the second is the Windows Long Date
format.
Note : The D must be uppercase. When setting a worksheet subformat as in wks.col3.subformat = #,
these values are indexed from 1.
For instance
type "$(date(7/20/2009), D1)";
produces, using U.S. Regional settings,
Monday, July 20, 2009
Similarly, for time values alone, there is an analagous T notation, to format output:
type "$(time(12:04:14), T5)"; // ANS: 12:04 PM
Formatting dates and times in this way uses one specific form of the more general $() Substitution
notation.

Custom Formats

There are three custom date and time formats - two of which are script editable properties and one
which is editable in the Column Properties dialog or using a worksheet column object method.
1. system.date.customformatn$

2. wks.col.SetFormat object method.

Both methods use date-time specifiers, such as yyyy'.'MM'.'dd, to designate the custom format.
Please observe that:
 The text portions (non-space delimiters) of the date-time specifier can be changed as required,

but must be surrounded by single quotes.

 The specifier tokens themselves (i.e., yyyy, HH, etc.) are case sensitive and need to be used

exactly as shown— all possible specifier tokens can be found in the Reference Tables: Date

and Time Format Specifiers.

157
 LabTalk Scripting Guide

 The first two formats store their descriptions in local file storage and as such may appear

different in other login accounts. The third format stores its description in the column itself.

Dnn notation

Origin has reserved D19 to D21 (subformats 20 to 22, since the integer after D starts its count from 0)
for these custom date displays. The options D19 and D20 are controlled by system variables
system.date.customformat1$ and system.date.customformat2$, respectively. To use this option
for output, follow the example below:

system.date.customformat1$ = MMM dd hh'.'mm tt;

type "$(Date(7/25/09 14:47:21),D19)"; // Output: Jul 25 02.47 PM

system.date.customformat2$ = yy','MM','dd H'.'mm'.'ss'.'####;

type "$(Date(7/27/09 8:22:37.75234),D20)"; // Output: 09,07,27 8.22.37.7523

Wks.Col.SetFormat object method

To specify a custom date display for a date column which is stored in the worksheet column, use the
Wks.Col.SetFormat object method. When entering the custom date format specifier, be sure to
surround any non-date characters with single quotes. Also note that this object method works on
columns of the active worksheet only.
In the following example, column 4 of the active worksheet is set to display a custom date/time
format:
// wks.format=4 (date), wks.subformat=22 (custom)
wks.col4.SetFormat(4, 22, yyyy'-'MM'-'dd HH':'mm':'ss'.'###);
doc -uw; // Refresh the worksheet to show the change

158
8 Matrix Books Matrix Sheets and Matrix Objects

8.1 Matrix Books Matrix Sheets and Matrix Objects

Similar to workbooks and worksheets, matrices in Origin also employ a data organizing hierarchy:
Matrix Book -> Matrix Sheet -> Matrix Object. Therefore, objects like Page and Wks encompass
matrix books and matrix sheets as well as workbooks and worksheets. In addition, Origin provides
many X-Functions for handling matrix data.

This chapter covers the following topics:

 Basic Matrix Book Operation

 LT Matrix Sheets

 LT Matrix Objects

8.2 Basic Matrix Book Operation

Matrix book has the same data structure level with workbook in Origin, both are windows. So, you
can manipulate matrix books with the Page object and Window command, which is similar to
workbook.

8.2.1 Workbook-like Operations

Both matrix book and workbook are windows, and they share lots of similar operations, even using
the same LabTalk script. So, the differences will be pointed out below, and if the same script is used,
please refer to Basic Workbook Operation.
1. Create New Matrix Book

When using X-Function newbook to create new matrix book, the argument mat must be 1.

Here is the similar example to the one for workbook.

//Create a new matrix book with the Long Name "MyMatrixBook"

newbook mat:=1 name:=MyMatrixBook;

// Create a new matrix book with 3 matrix sheets

// and use "Images" as Long Name and short name
newbook mat:=1 name:=Images sheet:=3 option:=lsname;

// Create a new hidden matrix book

// and the matrix book name is stored in myBkName$ variable

159
 LabTalk Scripting Guide

newbook mat:=1 hidden:=1 result:=myBkName$;

// Output matrix book name
myBkName$ = ;
2. Open Matrix Book

Use the same command, doc -o, as opening workbook, to open matrix book. The difference is

that the extension of a matrix book is ogm.

3. Save Matrix Book

Origin's matrix book with data is with the extension of ogm, and template without data is otm.

To save matrix book to ogm file and otm file, the save -i command and template_saveas X-

Function will be used respectively, that is also the same with workbook. However, matrix book

is not able to be saved as an analysis template.

4. Close Matrix Book

This is the same as workbook, see commands win -ca and win -cd.

5. Show or Hide Matrix Book

This is the same as workbook, see switches -ch, -h, and -hc in win command.

6. Name and Label Matrix Book

This is the same as workbook, see win -r command, and page object.

7. Activate Matrix Book

This is the same as workbook, see win -a command. The command window -o winName

{script} can be used to run the specified script for the named matrix book. See the opening

pages of the Running Scripts chapter for a more detailed explanation.

8. Delete Matrix Book

This is the same as workbook, see win -c command.

8.2.2 Show Image Thumbnails

To show or hide image thumbnails, the command matrix -it is available.
// Create a new matrix book
newbook mat:=1;
// Import an image
string strImg$ = system.path.program$;
strImg$ += "Samples\Image Processing and Analysis\bamboo.jpg";
impImage fname:=strImg$;

// Hide image thumbnails

160
 Matrix Books Matrix Sheets and Matrix Objects

matrix -it 0;

8.3 Matrix Sheets

8.3.1 Matrix Sheets
Matrix sheet has the same data structure level as Worksheet in Origin. So they have a lot of common
properties.

This section covers the following topics:

 Basic Matrix Sheet Operation

 Matrix Sheet Data Manipulation

8.3.2 Basic Matrix Sheet Operation

Examples in this section are similar to those found in the Basic Worksheet Operation section,
because many object properties and X-Functions apply to both Worksheets and Matrix Sheets. Note,
however, that not all properties of the wks object apply to a matrix sheet, and one should verify
before using a property in production code.

8.3.2.1 Add New Matrix Sheet

The newsheet X-Function with the mat:=1 option can be used to add new matrix sheets to matrix
book.
// Create a new matrix book with 3 matrix sheets,
// and use "myMatrix" as long name and short name
newbook name:="myMatrix" sheet:=3 option:=lsname mat:=1;
// Add a 100*100 matrix sheet named "newMatrix" to current matrix book
newsheet name:=newMatrix cols:=100 rows:=100 mat:=1;

8.3.2.2 Activate a Matrix Sheet

Similar to worksheets, matrix sheets are also layers in a page, and page.active and page.active$
properties can access matrix sheets. For example:
// Create a new matrix book with 3 matrix sheets
newbook sheet:=3 mat:=1;

page.active = 2; // Activate a matrix sheet by layer number

page.active$ = MSheet3; // Activate a matrix sheet by name

8.3.2.3 Modify Matrix Sheet Properties

To modify matrix properties, use the wks object, which works on matrix sheets as well as worksheets.
For example:
// Rename the matrix sheet
wks.name$ = "New Matrix";

161
 LabTalk Scripting Guide

// Modify the column width

wks.colwidth = 8;

Set Dimensions

Both the wks object and the mdim X-Function can be used to set matrix dimensions:
// Use the wks object to set dimension
wks.ncols = 100;
wks.nrows = 200;
// Use the mdim X-Function to set dimension
mdim cols:=100 rows:=100;
For the case of multiple matrix objects contained in the same matrix sheet, note that all of the matrix
objects must have the same dimensions.

Set XY Mapping

Matrices have numbered columns and rows which are mapped to linearly spaced X and Y values. In
LabTalk, you can use the mdim X-Function to set the mapping.
// XY mapping of matrix sheet
mdim cols:=100 rows:=100 x1:=2 x2:=4 y1:=4 y2:=9;

8.3.2.4 Delete Matrix Sheet

Use the layer -d commands to delete matrix sheet. For example:
layer -d; // delete the active layer, can be worksheet, matrix sheet or
graph layer
layer -d 3; // by index, delete third matrix sheet in active matrix book
layer -d msheet1; // delete matrix sheet by name
range rs = [mbook1]msheet3!;
layer -d rs; // delete matrix sheet by range
// the matrix book name stored in a string variable
string str$ = msheet2;
layer -d %(str$);

8.3.3 Matrix Sheet Data Manipulation

8.3.3.1 Conversion Between Matrix Sheets and Matrix Objects

In Origin, a matrix sheet can hold multiple matrix objects. Use the mo2s X-Function to split multiple
matrix objects into separate matrix sheets.
Use the ms2o X-Function to combine multiple matrix sheets into one (provided all matrices share the
same dimensions).
// Merge matrix sheet 2, 3, and 4
ms2o imp:=MBook1 sheets:="2,3,4" oms:=Merge;
// Split matrix objects in MSheet1 into new sheets
mo2s ims:=MSheet1 omp:=<new>;

8.4 Matrix Objects

162
 Matrix Books Matrix Sheets and Matrix Objects

8.4.1 Matrix Objects

Matrix object is the basic unit for storing matrix data, and its container is matrix sheet, that
relationship is like column and worksheet. The following pages will show the practical examples on
the operation of matrix object.

This chapter covers the following topics:

 Basic Matrix Object Operation

 Matrix Object Data Manipulation

 Converting Matrix to Worksheet

8.4.2 Basic Matrix Object Operation

A matrix sheet can have multiple matrix objects, which share the same dimensions. A matrix object is
analogous to a worksheet column and can be added or deleted, etc. The following sections provide
some practical examples on the basic operations of matrix object.

8.4.2.1 Add or Insert Matrix Object

It allows to set the number of matrix objects in the matrix sheet by using wks.nmats, so to add matrix
objects. Also, the method wks.addcol() can be used to add a matrix object.
// Set the number of matrix objects in the matrix sheet to 5
wks.nmats = 5;
// Add a new matrix object to a matrix sheet
wks.addCol();
// Add a named matrix object to a matrix sheet
wks.addCol(Channel2);
By default, the 1st matrix object in matrix sheet is the current matrix object, you can use the wks.col
property. And the method wks.insert() will insert matrix object before the current matrix object.
// Create a new matrix book, and show image thumbnails
newbook mat:=1;
matrix -it 1;

// Insert a matrix object before the 1st one in the active matrix sheet
wks.insert();

// Set the 2nd matrix object to be the current one

wks.col = 2;

// Insert a matrix object before the 2nd one

wks.insert();

8.4.2.2 Activate Matrix Object

To activate a matrix object in the active matrix sheet, the wks.active is available.
// Create a new matrix book

163
 LabTalk Scripting Guide

newbook mat:=1;

// Add two more matrix objects to the active matrix sheet

wks.addCol();
wks.addCol();

// Show image thumbnails

matrix -it 1;

// Activate the second matrix object

wks.active = 2;

8.4.2.3 Switch Between Image Mode and Data Mode

The matrix command has provided the option for switching between image mode and data mode of
the matrix object. Only the active matrix object appears in the matrix sheet.
matrix -ii 1; // Show image mode
matrix -ii 0; // Show data mode

8.4.2.4 Set Labels

For each matrix object, you can set Long Name, Comments, and Units, by using Range Notation,
which is a matrix object.
// Create a new matrix book
newbook mat:=1;

// Set number of matrix object of 1st matrix sheet to be 3

wks.nMats = 3;

// Show image thumbnails

matrix -it 1;

// Activate 1st matrix object

wks.active = 1;

// Set Long Name, Units, and Comments

range rx = 1; // 1st matrix object of the active matrix sheet
rx.lname$ = X; // Long Name = X
rx.unit$ = cm; // Unit = cm
rx.comment$ = "X Direction"; // Comment = "X Direction"

// Do the same thing for matrix object 2 and 3

wks.active = 2;
range ry = 2;
ry.label$ = Y; // Long Name can also be set in this way
ry.unit$ = cm;
ry.comment$ = "Y Direction";
wks.active = 3;
range rz = 3;
rz.label$ = Z;
rz.unit$ = Pa;
rz.comment$ = Pressure;

8.4.2.5 Delete Matrix Object

To delete a matrix object, you can use the delete command.

164
 Matrix Books Matrix Sheets and Matrix Objects

// Delete a matrix object by range

range rs=[mbook1]msheet1!1; // The first matrix object
del rs;
// or delete a matrix object by name
range rs=[mbook1]msheet1!Channel2; // The object named Channel2
del rs;

8.4.3 Matrix Object Data Manipulation

In addition to the matrix command, Origin provides X-Functions for performing specific operations on
matrix object data. In this section we present examples of X-Functions that available used to work
with matrix object data.

8.4.3.1 Set Values in Matrix Object

Matrix cell values can be set either using the matrix -v command or the msetvalue X-Function. The
matrix -v command works only on an active matrix object, whereas the X-Function can set values in
any matrix sheet.
This example shows how to set matrix values and then turn on display of image thumbnails in the
matrix window.
// Create a matrix book
newbook mat:=1;
int nmats = 10;
range msheet=1!;
// Set the number of matrix objects
msheet.Nmats = nmats;
// Set value to the first matrix object
matrix -v x+y;
range mm=1; mm.label$="x+y";
double ff=0;
// Loop over other objects
loop(i, 2, nmats-1) {
msheet.active = i;
ff = (i-1)/(nmats-2);
// Set values
matrix -v (5/ff)*sin(x) + ff*20*cos(y);
// Set LongName
range aa=$(i);
aa.label$="$(5/ff,*3)*sin(x) + $(ff*20)*cos(y)";
}
// Fill last one with random values
msheet.active = nmats;
matrix -v rnd();
range mm=$(nmats); mm.label$="random";
// Display thumbnail images in window
matrix -it;

8.4.3.2 Copy Matrix Data

The mcopy X-Function is used to copy matrix data.
// Copy data from mbook1 into another matrix, mbook2.
mcopy im:=mbook1 om:=mbook2; // This command auto-redimensions the target

8.4.3.3 Conversion between Matrix Object and Vector

165
 LabTalk Scripting Guide

Two X-Functions, m2v and v2m, are available for converting matrix data into a vector, and vector
data into a matrix, respectively. Origin uses row-major ordering for storing a matrix, but both functions
allow for column-major ordering to be specified as well.
// Copy the whole matrix, column by column, into a worksheet column
m2v method:=m2v direction:=col;
// Copy data from col(1) into specified matrix object
v2m ix:=col(1) method:=v2row om:=[Mbook1]1!1;

8.4.3.4 Conversion between Numeric Data and Image Data

In Origin, matrices can contain image data (i.e., RGB) or numeric data (i.e., integer). The following
functions are available to convert between the two formats.
// Convert a grayscale image to a numeric data matrix
img2m img:=mat(1) om:=mat(2) type:=byte;
// Convert a numeric matrix to a grayscale image
m2img bits:=16;

8.4.3.5 Manipulate Matrix Object with Complex Values

X-Functions for manipulating a matrix with complex values include map2c, mc2ap, mri2c, and mc2ri.
These X-Functions can merge two matrices (amplitude and phase, or real and imaginary) into one
complex matrix, or split a complex matrix into amplitude/phase or real/imaginary components.
// Combine Amplitude and Phase into Complex
map2c am:=mat(1) pm:=mat(2) cm:=mat(3);
// Combine Real and imaginary in different matrices to complex in new matrix
mri2c rm:=[MBook1]MSheet1!mat(1) im:=[MBook2]MSheet1!mat(1) cm:=<new>;
// Convert complex numbers to two new matrix with amplitude and phase
respectively
mc2ap cm:=mat(1) am:=<new> pm:=<new>;
// Convert complex numbers to two matrix objects with real part and imaginary
part
mc2ri cm:=[MBook1]MSheet1!Complex rm:=[Split]Real im:=[Split]Imaginary;

8.4.3.6 Transform Matrix Object Data

Use the following X-Functions to physically alter the dimensions or contents of a matrix. In the
transformations below, except the flipping matrix object, others may change the dimensions of its
matrix sheet, which will make the change on other matrix objects in this matrix sheet.

Crop or extract from Data or Image Matrix

When a matrix contains an image in a matrix, the X-Function mcrop can be used to extract or crop to
a rectangular region of the matrix.
// Crop an image matrix to 50 by 25 beginning from 10 pixels
// from the left and 20 pixels from the top.
mcrop x:=10 y:=20 w:=50 h:=25 im:=<active> om:=<input>; // <input> will crop
// Extract the central part of an image matrix to a new image matrix
// Matrix window must be active
matrix -pg DIM px py;
dx = nint(px/3);
dy = nint(py/3);
mcrop x:=dx y:=dy h:=dy w:=dx om:=<new>; // <new> will extract

Expand Data Matrix

166
 Matrix Books Matrix Sheets and Matrix Objects

The X-Function mexpand can expand a data matrix using specified column and row factors.
Biquadratic interpolation is used to calculate the values for the new cells.
// Expand the active matrix with both factor of 2
mexpand cols:=2 rows:=2;

Flip Data or Image Matrix

The X-Function mflip can flip a matrix horizontally or vertically to produce its mirror matrix.
// Flip a matrix vertically
mflip flip:=vertical;

// Can also use the "matrix" command

matrix -c h; // horizontally
matrix -c v; // vertically

Rotate Data or Image Matrix

With the X-Function mrotate90, you can rotate a matrix 90/180 degrees clockwise or
counterclockwise.
// Rotate the matrix 90 degrees clockwize
mrotate90 degree:=cw90;

// Can also use the "matrix" command to rotate matrix 90 degrees

matrix -c r;

Shrink Data Matrix

The X-Function mshrink can shrink a data matrix by specified row and column factors.
// Shrink the active matrix by column factor of 2, and row factor of 1
mshrink cols:=2 rows:=1;

Transpose Data Matrix

The X-Function mtranspose can be used to transpose a matrix.

// Transpose the second matrix object of [MBook1]MSheet1!
mtranspose im:=[MBook1]MSheet1!2;

// Can also use the "matrix" command to transpose a matrix

matrix -t;

8.4.3.7 Split RGB Image into Separate Channels

The imgRGBsplit X-Functions splits color images into separate R, G, B channels. For example:
// Split channels creating separate matrices for red, green and blue
imgRGBsplit img:=mat(1) r:=mat(2) g:=mat(3) b:=mat(4) colorize:=0;
// Split channels and apply red, green, blue palettes to the result matrices
imgRGBsplit img:=mat(1) r:=mat(2) g:=mat(3) b:=mat(4) colorize:=1;
Please see Image Processing X-Functions for further information on image handling.

8.4.3.8 Use Temporary Matrix Object as Intermediate Analysis Result

167
 LabTalk Scripting Guide

Sometimes user may not want to create a new Matrixbook for output in X-Function each time when
performing intermediate matrix analysis operations. He can create a temporary matrix in a hidden
Matrixbook for intermediate output, and delete the Matrixbook when it is not needed in next operation.
 Example 1

This example shows how to save intermediate image operation result in a temporary Matrixbook, and
delete it in the next step.
//Import an image into Origin's Matrixbook
string fn$=system.path.program$ + "Samples\Image Processing and
Analysis\white camellia.jpg";
impImage fname:=fn$;
//Create a hidden Matrixbook
newbook hidden:=1 mat:=1;
%A = bkname$;
//Perform Auto Level operation and save the output in the hidden Matrixbook
imgAutoLevel oimg:=[%A]1! cl:=<optional>;
//Apply Median filter on the image from Auto Level operation
imgMedian d:=3 img:=[%A]1! oimg:=<new>;
//Delete the intermediate matrix
win -cd %A;

 Example 2

In this example, a median filter was applied on a matrix, and the volume was calculated after the
minimum was subtracted. All intermediate matrix results were saved in a hidden temporary
Matrixbook, and the Matrixbook was deleted after it was not needed.
//Open a sample Matrixbook
string fn$=system.path.program$ + "Samples\Matrix Conversion and Gridding\2D
Gaussian.ogm";
doc -o %(fn$);
//Create a temporary hidden Matrixbook
newbook hidden:=1 mat:=1;
%A = bkname$;
range rm = [%A]1!;
//Add two matrix objects to receive two intermediate matrix results
rm.nmats = 2;
//Apply a median filter on a matrix
medianflt2 n:=3 po:=RepeatPadding om:=[%A]1!mat(1);
//Subtract the minimum
msetvalue im:=[%A]1!mat(2) formula:="mat(1)-z0" script:="double z0; mstats
im:=mat(1) min:=z0;";
//Integrate the matrix
double dv;
integ2 im:=[%A]1!mat(2) integral:=dv;
win -cd %A;

8.4.4 Converting Matrix to Worksheet

You may need to re-organize your data by converting from matrix to worksheet, or vice versa, for
certain analysis or graphing needs. This page provides information and examples of converting
matrix to worksheet, and please refer to Converting Worksheet to Matrix for the "vice versa" case.

8.4.4.1 Matrix to Worksheet

168
 Matrix Books Matrix Sheets and Matrix Objects

Data in a matrix can also be converted to a worksheet by using the m2w X-Function. This X-Function
can directly convert data into worksheet, with or without X/Y mapping, or convert data by rearranging
the values into XYZ columns in the worksheet.
The following example shows how to convert matrix into worksheet, and plot graphs using different
methods according the form of the worksheet data.
// Create a new matrix book
win -t matrix;
// Set matrix dimension and X/Y values
mdim cols:=21 rows:=21 x1:=0 x2:=10 y1:=0 y2:=100;
// Show matrix X/Y values
page.cntrl = 2;
// Set matrix Z values
msetvalue formula:="nlf_Gauss2D(x, y, 0, 1, 5, 2, 50, 20)";
// Hold the matrix window name
%P = %H;
// Covert matrix to worksheet by Dierct method
m2w ycol:=1 xlabel:=row1;
// Plot graph from worksheet using Virtual Matrix
plotvm irng:=1! format:=1 ztitle:=MyGraph type:=242 ogl:=<new
template:=cmap>;
// Convert matrix to XYZ worksheet data
sec -p 2;
win -a %P;
m2w im:=!1 method:=xyz;
// Plot a 3D Scatter
worksheet -s 3;
worksheet -p 240 3D;
If the matrix data is converted directly to worksheet cells, you can then plot such worksheet data
using the Virtual Matrix feature.

169
9 Graphing

9.1 Graphing

This chapter covers the following topics:

 Creating Graphs

 Formatting Graphs

 Managing Layers

 Creating and Accessing Graphical Objects

Origin's breadth and depth in graphing support capabilities are well known. The power and flexibility
of Origin's graphing features are accessed as easily from script as from our graphical user interface.
The following sections provide examples of creating and editing graphs from LabTalk scripts.

9.2 Creating Graphs

Creating graphs is probably the most commonly performed operation in Origin. This section gives
examples of two X-Functions that allow you to create graphs directly from LabTalk scripts: plotxy and
plotgroup. Once a plot is created, you can use object properties, like page, layer, axis objects, and
set command to format the graph.

9.2.1 Creating a Graph with the PLOTXY X-Function

plotxy is an X-Function used for general purpose plotting. It is used to create a new graph window,
plot into a graph template, or plot into a new graph layer. It has a syntax common to all X-Functions:
plotxy option1:=optionValue option2:=optionValue ... optionN:=optionValue
All possible options and values are summarized in the X-Function help for plotxy. Since it is
somewhat non-intuitive, the plot option and its most common values are summarized here:
plot:= Plot Type

200 Line

201 Scatter

202 Line+symbol

203 column
All of the possible values for the plot option can be found in the Plot Type IDs.

171
 LabTalk Scripting Guide

9.2.1.1 Plotting X Y data

Input XYRange referencing the X and Y

The following example plots the first two columns of data in the active worksheet, where the first
column will be plotted as X and the second column as Y, as a line plot.
plotxy iy:=(1,2) plot:=200;

Input XYRange referencing just the Y

The following example plots the second column of data in the active worksheet, as Y against its
associated X, as a line plot. When you do not explicitly specify the X, Origin will use the the X-column
that is associated with that Y-column in the worksheet, or if there is no associated X-column, then an
<auto> X will be used. By default, <auto> X is row number.
plotxy iy:=2 plot:=200;

9.2.1.2 Plotting X YY data

The following example plots the first three columns of data from Book1, Sheet1, where the first
column will be plotted as X and the second and third columns as Y, as a grouped scatter plot.
plotxy iy:=[Book1]Sheet1!(1,2:3) plot:=201;

9.2.1.3 Plotting XY XY data

The following example plots the first four columns of data in the active worksheet, where the first
column will be plotted as X against the second column as Y and the third column as X against the
fourth column as Y, as a grouped line+symbol plot.
plotxy iy:=((1,2),(3,4)) plot:=202;

9.2.1.4 Plotting using worksheet column designations

The following example plots all columns in the active worksheet, using the worksheet column plotting
designations, as a column plot. '?' indicates to use the worksheet designations; '1:end' indicates to
plot all the columns.
plotxy iy:=(?,1:end) plot:=203;

9.2.1.5 Plotting a subset of a column

The following example plots rows 1-12 of all columns in the active worksheet, as a grouped line plot.
plotxy iy:=(1,2:end)[1:12] plot:=200;
Note: Please refer to Specifying Subrange Using X Values for more details on subset.

9.2.1.6 Plotting into a graph template

The following example plots the first column as theta(X) and the second column as r(Y) in the active
worksheet, into the polar plot graph template, and the graph window is named MyPolarGraph.
plotxy (1,2) plot:=192 ogl:=[<new template:=polar name:=MyPolarGraph>];

9.2.1.7 Plotting into an existing graph layer

The following example plots columns 10-20 in the active worksheet, using column plotting
designations, into the second layer of Graph1. These columns can all be Y columns and they will still
plot against the associated X column in the worksheet.
plotxy iy:=(?,10:20) ogl:=[Graph1]2!;

172
 Graphing

9.2.1.8 Creating a new graph layer

The following example adds a new Bottom-X Left-Y layer to the active graph window, plotting the first
column as X and the third column as Y from Book1, Sheet2, as a line plot. When a graph window is
active and the output graph layer is not specified, a new layer is created.
plotxy iy:=[Book1]Sheet2!(1,3) plot:=200;

9.2.1.9 Creating a Double-Y Graph

// Import data file
string fpath$ = "Samples\Import and Export\S15-125-03.dat";
string fname$ = system.path.program$ + fpath$;
impASC;

// Remember Book and Sheet names

string bkname$ = page.name$;
string shname$ = layer.name$;

// Plot the first and second columns as X and Y

// The worksheet is active, so can just specify column range
plotxy iy:=(1,2) plot:=202 ogl:=[<new template:=doubleY>];

// Plot the first and third columns as X and Y into the second layer
// Now that the graph window is the active window, need to specify Book
//and Sheet
plotxy iy:=[bkname$]shname$!(1,3) plot:=202 ogl:=2;

9.2.2 Create Graph Groups with the PLOTGROUP X-Function

According to the grouping variables (datasets), plotgroup X-Function creates grouped plots for page,
layer or dataplot. To work properly, the worksheet should be sorted by the graph group data first, then
the layer group data and finally the dataplot group data.
This example shows how to plot by group.
// Establish a path to the sample data
fn$ = system.path.program$ + "Samples\Statistics\body.dat";
newbook;
impASC fn$; // Import into new workbook

// Sort worksheet--Sorting is very important!

wsort bycol:=3;

// Plot by group
plotgroup iy:=(4,5) pgrp:=Col(3);
This next example creates graph windows based on one group and graph layers based on a second
group:
// Bring in Sample data
fn$ = system.path.program$ + "Samples\Graphing\Categorical Data.dat";
newbook;
impASC fn$;
// Sort
dataset sortcol = {4,3}; // sort by drug, then gender
dataset sortord = {1,1}; // both ascending sort
wsort nest:=sortcol ord:=sortord;
// Plot each drug in a separate graph with gender separated by layer
plotgroup iy:=(2,1) pgrp:=col(drug) lgrp:=col(gender);

173
 LabTalk Scripting Guide

Note : Each group variable is optional. For example, you could use one group variable to organize
data into layers by omitting Page Group and Data Group. The same sort order is important for
whichever options you do use.

9.2.3 Create 3D Graphs with Worksheet -p Command

To create 3D Graphs, use the Worksheet (command) (-p switch).
First, create a simple 3D scatter plot:
// Create a new book
newbook r:=bkn$;
// Run script on bkn$
win -o bkn$ {
// Import sample data
string fname$ = system.path.program$ +
"\samples\Matrix Conversion and Gridding" +
"\XYZ Random Gaussian.dat";
impasc;
// Save new book name
bkn$ = %H;
// Change column type to Z
wks.col3.type = 6;
// Select column 3
worksheet -s 3;
// Plot a 3D scatter graph by template named "3d"
worksheet -p 240 3d;
};
You can also create 3D color map or 3D mesh graph. 3D graphs can be plotted either from
worksheet or matrix. And you may need to do gridding before plotting.
We can run the following script after above example and create a 3D wire frame plot from matrix:
win -o bkn$ {
// Gridding by Shepard method
xyz_shep 3;
// Plot 3D wire frame graph;
worksheet -p 242 wirefrm;
};

9.2.4 Create 3D Graph and Contour Graphs from Virtual Matrix

Origin can also create 3D graphs, such as 3D color map, contour, or 3D mesh, etc., from worksheet
by the plotvm X-Function. This function creates a virtual matrix, and then plot from such matrix. For
example:
// Create a new workbook and import sample data
newbook;
string fname$=system.path.program$ + "Samples\Graphing\VSurface 1.dat";
impasc;
// Treat entire sheet as a Virtual Matrix and create a colormap surface plot
plotvm irng:=1! format:=xacross rowpos:=selrow1 colpos:=selcol1
ztitle:="VSurface 1" type:=242 ogl:=<new template:=cmap>;
// Change X axis scale to log
// Nonlinear axis type supported for 3D graphs created from virtual matrix
LAYER.X.type=2;

9.3 Formatting Graphs

174
 Graphing

9.3.1 Graph Window

A graph window is comprised of a visual page, with an associated Page (Object). Each graph page
contains at least one visual layer, with an associated layer object. The graph layer contains a set of X
Y axes with associated layer.x and layer.y objects, which are sub-objects of the layer object.

When you have a range variable mapped to a graph page or graph layer, you can use
that variable name in place of the word page or layer.

9.3.2 Page Properties

The page object is used to access and modify properties of the active graph window. To output a list
of all properties of this object:
page.=
The list will contain both numeric and text properties. When setting a text (string) property value, the $
follows the property name.
To read the Short name of the active window:
page.name$="Graph3";
To read the Long name of the active window:
page.longname$="This name can contain spaces";
You can also access Graph properties or attributes using a range variable instead of the page object.
The advantage is that using a range variable works whether or not the desired graph is active.
The example below sets the active graph layer to layer 2, using a range variable to point to the
desired graph by name. Once declared, the range variable can be used in place of page:
//Create a Range variable that points to your graph
range rGraph = [Graph3];
//The range now has properties of the page object
rGraph.active=2;

9.3.3 Layer Properties

The layer object is used to access and modify properties of the graph layer.
To set the graph layer dimensions:
//Set the layer area units to cm
layer.unit=3;
//Set the Width
layer.width=5;
//Set the Height
layer.height=5;

9.3.3.1 Fill the Layer Background Color

The laycolor X-Function is used to fill the layer background color. The value you pass to the function
for color, corresponds to Origin's color list as seen in the Plot Details dialog (1=black, 2=red, 3=green,
etc).
To fill the background color of layer 1 as green:
laycolor layer:=1 color:=3;

9.3.3.2 Set Speed Mode Properties

The speedmode X-Function is used to set layer speed mode properties.

175
 LabTalk Scripting Guide

9.3.3.3 Update the Legend

The legendupdate X-Function is used to update or reconstruct the graph legend on the page/layer.

9.3.4 Axis Properties

The layer.x and layer.y sub-object of the layer object is used to modify properties of the axes.
To modify the X scale of the active layer:
//Set the scale to Log10
layer.x.type = 2;
//Set the start value
layer.x.from = .001;
//Set the end value
layer.x.to = 1000;
//Set the increment value
layer.x.inc = 2;

If you wish to work with the Y scale, then simply change the x in the above script to a
y. If you wish to work with a layer that is not active, you can specify the layer index,
layerN.x.from. Example: layer3.y.from = 0;

The Axis command can also be used to access the settings in the Axis dialog.
To change the X Axis Tick Labels to use the values from column C, given a plot of col(B) vs. col(A)
with text in col(C), from Sheet1 of Book1:
range aa = [Book1]Sheet1!col(C);
axis -ps X T aa;

9.3.5 Data Plot Properties

The Set (Command) is used to change the attributes of a data plot. The following example shows
how the Set command works by changing the properties of the same dataplot several times. In the
script, we use sec command to pause one second before changing plot styles.
// Make up some data
newbook;
col(a) = {1:5};
col(b) = col(a);
// Create a scatter plot
plotxy col(b);

// Set symbol size

// %C is the active dataset
sec -p 1;
set %C -z 20;
// Set symbol shape
sec -p 1;
set %C -k 3;
// Set symbol color
sec -p 1;
set %C -c color(blue);
// Connect the symbols
sec -p 1;
set %C -l 1;
// Change plot line color
sec -p 1;
set %C -cl color(red);

176
 Graphing

// Set line width to 4 points

sec -p 1;
set %C -w 2000;
// Change solid line to dash
sec -p 1;
set %C -d 1;
Here is another example which plots into a template, DoubleY, with two layers, and then sets dataplot
style for the dataplot in the second layer:
// Importing data
newbook;
string fn$=system.path.program$ + "Samples\Curve Fitting\Enzyme.dat";
impasc fname:=fn$;
//declare active worksheet range
range rr = !;
//plot into a template
plotxy iy:=(1,2) plot:=200 ogl:=[<new template:=DoubleY>];
//plot into second layer of active graph, which is graph created from line
above
plotxy iy:=%(rr)(1,3) plot:=200 ogl:=2!;
//declare range for first dataplot in layer 2
range r2 = 2!1;
//set line to dash
set r2 -d 1;

9.3.6 Legend and Label

Formatting the Legend and Label are discussed on Creating and Accessing Graphical Objects.

9.4 Managing Layers

9.4.1 Creating a panel plot
The newpanel X-Function creates a new graph with an n x m layer arrangement.

9.4.1.1 Creating a 6 panel graph

The following example will create a new graph window with 6 layers, arranged as 2 columns and 3
rows. This function can be run independent of what window is active.
newpanel col:=2 row:=3;

Remember that when using X-Functions you do not always need to use the variable
name when assigning values; however, being explicit with col:= and row:= may make
your code more readable. To save yourself some typing, in place of the code above,
you can use the following:
newpanel 2 3;

9.4.1.2 Creating and plotting into a 6 panel graph

The following example will import some data into a new workbook, create a new graph window with 6
layers, arranged as 2 columns and 3 rows, and loop through each layer (panel), plotting the imported
data.
// Create a new workbook
newbook;

177
 LabTalk Scripting Guide

// Import a file
path$ = system.path.program$ + "Samples\Graphing\";
fname$ = path$ + "waterfall2.dat";
impasc;

// Save the workbook name as newpanel will change %H

string bkname$=%H;

// Create a 2*3 panel

newpanel 2 3;

// Plot the data

for (ii=2; ii<8; ii++)
{
plotxy iy:=[bkname$]1!wcol(ii) plot:=200 ogl:=$(ii-1);
}

9.4.2 Adding Layers to a Graph Window

The layadd X-Function creates/adds a new layer to a graph window. This function is the equivalent of
the Graph:New Layer(Axes) menu.

Programmatically adding a layer to a graph is not common. It is recommended to

create a graph template ahead of time and then use the plotxy X-Function to plot into
your graph template.

The following example will add an independent right Y axis scale. A new layer is added, displaying
only the right Y axis. It is linked in dimension and the X axis is linked to the current active layer at the
time the layer is added. The new added layer becomes the active layer.
layadd type:=rightY;

9.4.3 Arranging the layers

The layarrange X-Function is used to arrange the layers on the graph page.

Programmatically arranging layers on a graph is not common. It is recommended to

create a graph template ahead of time and then use the plotxy X-Function to plot into
your graph template.

The following example will arrange the existing layers on the active graph into two rows by three
columns. If the active graph does not already have 6 layers, it will not add any new layers. It arranges
only the layers that exist.
layarrange row:=2 col:=3;

9.4.4 Moving a layer

The laysetpos X-Function is used to set the position of one or more layers in the graph, relative to
the page.
The following example will left align all layers in the active graph window, setting their position to be
15% from the left-hand side of the page.
laysetpos layer:="1:0" left:=15;

9.4.5 Swap two layers

178
 Graphing

The layswap X-Function is used to swap the location/position of two graph layers. You can reference
the layers by name or number.
The following example will swap the position on the page of layers indexed 1 and 2.
layswap igl1:=1 igl2:=2;
The following example will swap the position on the page of layers named Layer1 and Layer2.
layswap igl1:=Layer1 igl2:=Layer2;

Layers can be renamed from both the Layer Management tool as well as the Plot
Details dialog. In the Layer Management tool, you can double-click on the Name in the
Layer Selection list, to rename. In the left-hand navigation panel of the Plot Details
dialog, you can slow double-click a layer name to rename.
To rename from LabTalk, use layern.name$ where n is the layer index. For example,
to rename layer index 1 to Power, use the following: layer1.name$="Power";

9.4.6 Aligning layers

The layalign X-Function is used to align one or more layers relative to a source/reference layer.
The following example will bottom align layer 2 with layer 1 in the active graph window.
layalign igl:=1 destlayer:=2 direction:=bottom;
The following example will left align layers 2, 3 and 4 with layer 1 in the active graph window.
layalign igl:=1 destlayer:=2:4 direction:=left;
The following example will left align all layers in Graph3 with respect to layer 1. The 2:0 notation
means for all layers, starting with layer 2 and ending with the last layer in the graph.
layalign igp:=graph3 igl:=1 destlayer:=2:0 direction:=left;

9.4.7 Linking Layers

The laylink X-Function is used for linking layers to one another. It is used to link axes scales as well
as layer area/position.
The following example will link all X axes in all layers in the active graph to the X axis of layer 1. The
Units will be set to % of Linked Layer.
laylink igl:=1 destlayers:=2:0 XAxis:=1;

9.4.8 Setting Layer Unit

The laysetunit X-Function is used to set the unit for the layer area of one or more layers.

9.5 Creating and Accessing Graphical Objects

Graphical Objects could be many types, Line, Polyline, Rectangle, Cycle, Polygon, Arrow, Text,
Image, etc. Once an object is created and attached to a layer, you can see it by invoking the list -o
command option. The following section shows you how to create, change, and delete an object by
LabTalk.

9.5.1 Creating Objects

9.5.1.1 Creating Labels

179
 LabTalk Scripting Guide

A label is one type of graphic object and can be created using the Label command. If no name is
specified when creating labels by the label -n command, Origin will name the labels automatically
with "Textn", where n is the creation index.
When creating labels, you can use escape sequences in a string to customize the text display. These
sequences begin with the backslash character (\). Enter the following script to see how these escape
sequences work. When there are spaces or multiple lines in your label text, quote the text with a
double quote mark.
label "You can use \b(Bold Text)
Subscripts and Superscripts like X\=(\i(i), 2)
\i(Italic Text)
\ab(Text with Overbar)
or \c4(Color Text) in your Labels";

The following script creates a new text label on your active graph window with the value from column
1, row 5 of sheet1 in book3. It works for both string and numeric.
label -s %([book3]Sheet1,1,5);
The following script creates a new text label on your active graph window from the value in row 1 of
column 2 of sheet2 in book1. Note the difference from the above example - the cell(i,j) function takes
row number as first argument. It works for a numeric cell only.
label -s $([book1]Sheet2!cell(1,2));
Besides, you can address worksheet cell values as your label contents. The following script creates a
new text label on your active graph window from the value in row 1 of column 2 of sheet2 in book1.
The value is displayed with 4 significant digits.
label -s $([book1]Sheet2!cell(1,2), *4);

The %( ) notation does not allow formatting and displays the value with full precision.
You need to use $( ) notation if you wish to format the numeric value.

9.5.1.2 Creating Legends

A graph legend is just a text label with the object name Legend. It has properties common to all
graphical objects. To output a list of all properties of the legend, simply enter the following:
legend.=

To view the object name of any graphical object right-click on it and select
Programming Control from the context menu.

To update or reconstruct the graph legend, use the legendupdate X-function, which has the following
syntax:
legendupdate [mode:=optionName]
The square brackets indicate that mode is optional, such that legendupdate may be used on its
own, as in:
legendupdate;
which will use the default legend setting (short name) or use mode to specify what you would like
displayed:
legendupdate mode:=0;
which will display the Comment field in the regenerated legend for the column of data plotted. All
possible modes can be found in Help: X-Functions: legendupdate:
Note that either the index or the name of the mode may be used in the X-function call, such that the
script lines,

180
 Graphing

legendupdate mode:=comment;
legendupdate mode:=0;
are equivalent and produce the same result.
The custom legend option requires an additional argument, demonstrated here:
legendupdate mode:=custom custom:=@WS;
All available custom legend options are given in the Text Label Options.
The following example shows how to use these functions and commands to update legends.
// Import sample data;
newbook;
string fn$ = system.path.program$ +
"Samples\Curve Fitting\Enzyme.dat";
impasc fname:=fn$;
string bn$ = %H;
// Create a two panels graph
newpanel 1 2;
// Add dataplot to layers
for (ii=1; ii<=2; ii++)
{
plotxy iy:=[bn$]1!wcol(ii+1) plot:=201 ogl:=$(ii);
}
// Upate whole page legends by worksheet comment + unit
legendupdate dest:=0 update:=0 mode:=custom custom:=@ln;
// Modify the legend settings for each layers
doc -e LW {
// Set legend font size
legend.fsize = 28;
// Set legend font color
legend.color = color(blue);
// Move legend to upper-left of the layer
legend.x = layer.x.from + legend.dx / 2;
legend.y = layer.y.to - legend.dy / 2;
};
Note: To modify the text of the legend, you can also use the label command. One reason to use this
would be if you wanted to display more than one text entry for each dataplot. The script below will
update the legend text to display both the worksheet name and the X column's Comment:
label -sl -n legend "\l(1) %(1, @WS) %(1X, @LC)";

9.5.1.3 Creating Lines

Objects like lines, rectangles, are graphic objects, and you can use draw command to create them.
In the example below, you can see how to use the -l and -v switches to draw a Vertical Line. The line
will be drawn at the midpoint of the X axis, where X1 and X2 are system variables that store the X
From and X To scale values respectively.
draw -l -v (X1+(X2-X1)/2);
To make the line movable, use the -lm switch.
draw -lm -v (X1+(X2-X1)/2);

9.5.2 Working on Objects

9.5.2.1 Position of Objects
Object position can either be controlled when creating it, or changed by object properties. The
following table lists how these properties and commmands works:

181
 LabTalk Scripting Guide

Property / Command Unit Reference Point

label -p Percentage Top-left

label -px Pixel of Screen Top-left

object.top / object.left Pixel of Page Top-left

object.x / object.y Layer coordinates Center of Object

object.x1 / object.y1 Layer coordinates Top-left

Notes: The pixel of a page can be found from the Print/Dimensions tab of Plot Details dialog.
For example:
win -T Plot; // Create an empty graph
// Create a text object at the layer center,
// named as "MyText", and the context is "Hello World"
label -p 50 50 -n MyText Hello World;
sec -p 1;
// Place the label at (1, 5)
MyText.x1 = 1;
MyText.y1 = 5;

9.5.2.2 Change Object Properties

All graphical objects can use objectName.= to get or set object properties. Take label as example,
the object.x and object.y properties specify the x and y position of the center of an object, and
object.dx and object.dy specify the object width and height. These four properties are all using axis
units, so we can combine these four properties with layer.axis.from and layer.axis.to to place the
label in the proper position on a layer.
The following script example shows how to use label properties to place labels.
// Import sample data
newbook;
string fname$ = system.path.program$ +
"Samples\Curve Fitting\Enzyme.dat";
impasc;
string bn$ = %H;
plotxy ((,2), (,3));
// Create a label and name it "title"
// Be note the sequence of option list, -n should be the last option
// -j is used to center the text
// -s enables the substitution notation
// -sa enables conversion of \n (new line)
// Subsitution is used to get text from column comments
label -j 1 -s -sa -n title
Enzyme Reaction Velocity\n%([bn$]1!col(2)[c]$) vs. %([bn$]1!col(3)[c]$);
// Set font
title.font=font(Times New Roman);
// Set label font size
title.fsize = 28;
// Set label font color
title.color = color(blue);
// Placing label
title.x = layer.x.from + (layer.x.to - layer.x.from) / 2;

182
 Graphing

title.y = layer.y.to + title.dy / 2;

// Placing legend
legend.y = layer.y.from + (layer.y.to - layer.y.from) / 2;
legend.x = layer.x.to - legend.dx / 2;

9.5.3 Deleting an Object

To delete objects, use the label command with -r, -ra, and -rc switches:
Switch Description

label -r objectName Delete the specified object

label -ra objectNamePrefix Delete all objects whose names start with objectNamePrefix

label -rc objectName Remove specified object, with the connected objects

183
10 Importing

10.1 Importing

This chapter covers the following topics:

 Importing Data

 Importing Images

Origin provides a collection of X-Functions for importing data from various file formats such as ASCII,
CSV, Excel, National Instruments DIAdem, pCLAMP, and many others. The X-Function for each file
format provides options relevant to that format in addition to common settings such as assigning the
name of the import file to the book or sheet name.
All X-Functions pertaining to importing have names that start with the letters imp. The table below
provides a listing of these X-Functions. As with all X-Functions, help-file information is available at
Script or Command line by entering the name of the X-Function with the -h option. For instance:
entering impasc -h in the Script window will display the help file immediately below the command.
Name Brief Description

impASC Import ASCII file/files

impBin2d Import binary 2d array file

impCSV Import csv file

impDT Import Data Translation Version 1.0 files

Import EarthProbe (EPA) file. Now only EPA file is supported for EarthProbe
impEP
data.

impExcel Import Microsoft Excel 97-2007 files

impFamos Import Famos Version 2 files

impFile Import file with pre-defined filter.

impHEKA Import HEKA (dat) files

impIgorPro Import WaveMetrics IgorPro (pxp, ibw) files

impImage Import a graphics file

impinfo Read information related to import files.

185
 LabTalk Scripting Guide

impJCAMP Import JCAMP-DX Version 6 files

impJNB Import SigmaPlot (JNB) file. It supports version lower than SigmaPlot 8.0.

impKG Import KaleidaGraph file

impMatlab Import Matlab files

Import ETAS INCA MDF (DAT, MDF) files. It supports INCA 5.4 (file version
impMDF
3.0).

Import Minitab file (MTW) or project (MPJ). It supports the version prior to
impMNTB
Minitab 13.

impNetCDF Import netCDF file. It supports the file version lower than 3.1.

impNIDIAdem Import National Instruments DIAdem 10.0 dat files

Import National Instruments TDM and TDMS files(TDMS does not support
impNITDM
data/time format)

impODQ Import *.ODQ files.

Import pCLAMP file. It supports pClamp 9 (ABF 1.8 file format) and pClamp 10
imppClamp
(ABF 2.0 file format).

impSIE Import nCode Somat SIE 0.92 file

impSPC Import Thermo File

impSPE Import Princeton Instruments (SPE) file. It supports the version prior to 2.5.

impWav Import waveform audio file

reimport Re-import current file

You can write your own import routines in the form of X-Functions as well. If the name of a user-
created X-Function begins with imp and it is placed in the \X-Functions\Import and Export
subfolder of the EXE, UFF or Group paths, then such functions will appear in the File|Import menu.
The following sections give examples of script usage of these functions for importing data, graphs,
and images.

10.2 Importing Data

The following examples demonstrate the use of X-Functions for importing data from external files.
The examples import ASCII files, but the appropriate X-Function can be substituted based on your
desired filetype (i.e., CSV, Matlab); syntax and supporting commands will be the same. Since these
examples import Origin sample files, they can be typed or pasted directly into the Script or Command
window and run.

10.2.1 Import an ASCII Data File Into a Worksheet or Matrix

186
 Importing

This example imports an ASCII file (in this case having a *.txt extension) into the active worksheet or
matrix. Another X-Function, findfiles, is used to find a specific file in a directory (assigned to the
string path$) that contains many other files. The output of the findfiles X-Function is a string variable
containing the desired filename(s), and is assigned, by default, to a variable named fname$. Not
coincidentally, the default input argument for the impASC X-Function is a string variable called
fname$.
string path$ = system.path.program$ + "Samples\Import and Export\";
findfiles ext:=matrix_data_with_xy.txt;
impASC;

10.2.2 Import ASCII Data with Options Specified

This example makes use of many advanced options of the impASC X-Function. It imports a file to a
new book, which will be renamed by the options of the impASC X-Function. Notice that there is only
one semi-colon (following all options assignments) indicating that all are part of the call to impASC.
string fn$=system.path.program$ + "Samples\Spectroscopy\HiddenPeaks.dat";
impasc fname:=fn$
options.ImpMode:=3 /* start with a new book */
options.Sparklines:=0 /* turn off sparklines */
options.Names.AutoNames:=0 /* turn off auto rename */
options.Names.FNameToSht:=1 /* rename sheet to file name */
options.Miscellaneous.LeadingZeros:=1; /* remove leading zeros */

10.2.3 Import Multiple Data Files

This example demonstrates importing multiple data files to a new workbook; starting a new worksheet
for each file.
string fns, path$=system.path.program$ + "Samples\Curve Fitting\";
findfiles fname:=fns$ ext:="step1*.dat"; // find matching files in 'path$'
int n = fns.GetNumTokens(CRLF); // Number of files found
string bkName$;
newbook s:=0 result:=bkName$;
impasc fname:=fns$ // impasc has many options
options.ImpMode:=4 // start with new sheet
options.Sparklines:=2 // add sparklines if < 50 cols
options.Cols.NumCols:=3 // only import first three columns
options.Names.AutoNames:=0 // turn off auto rename
options.Names.FNameToBk:=0 // do not rename the workbook
options.Names.FNameToSht:=1 // rename sheet to file name
options.Names.FNameToShtFrom:=4 // trim file name after 4th letter
options.Names.FNameToBkComm:=1 // add file name to workbook comment
options.Names.FNameToColComm:=1 // add file name to columns comments
options.Names.FPathToComm:=1 // include file path to comments
orng:=[bkName$]A1!A[1]:C[0] ;

10.2.4 Import an ASCII File to Worksheet and Convert to Matrix

This example shows two more helpful X-Functions working in conjunction with impASC; they are
dlgFile, which generates a dialog for choosing a specific file to import, and w2m which specifies the
conversion of a worksheet to a matrix. It should be noted that the w2m X-Function expects linearly
increasing Y values in the first column and linearly increasing X values in the first row: test this with
matrix_data_with_xy.txt in the Samples\Import and Export\ folder.
dlgfile g:=ascii; // Open file dialog
impAsc; // Import selected file

187
 LabTalk Scripting Guide

// Use the worksheet-to-matrix X-Function, 'w2m', to do the conversion

w2m xy:=0 ycol:=1 xlabel:=row1

10.2.5 Related: the Open Command

Another way to bring data into Origin is with the Open (Command).
Open has several options, one of which allows a file to be open for viewing in a notes window:
open -n fileName [winName]
This line of script opens the ASCII file fileName to a notes window. If the optional winName is not
specified, a new notes window will be created.
To demonstrate with an existing file, try the following:
%b = system.path.program$ + "Samples\Import and Export\ASCII simple.dat";
open -n "%b";

10.2.6 Import with Themes and Filters

10.2.6.1 Import with a Theme
When importing from the Origin GUI, you can save your import settings to a theme file. Such theme
files have a *.OIS extension and are saved in the \Themes\AnalysisAndReportTable\ subfolder of
the Origin User Files Folder (UFF). They can then be accessed using an X-Function with the -t
option switch. The import is performed according to the settings saved in the theme file specified.
string fn$=system.path.program$ + "Samples\Spectroscopy\HiddenPeaks.dat";
// Assume that a theme file named "My Theme.OIS" exists
impasc fname:=fn$ -t "My Theme";

10.2.6.2 Import with an Import Wizard Filter File

Custom importing of ASCII files and simple binary files can be performed using the Import Wizard
GUI tool. This tool allows extraction of variables from file name and header, and further customization
of the import including running a script segment at the end of the import, which can be used to
perform post-processing of imported data. All settings in the GUI can be saved as an Import Filter
File to disk. Such files have extension of .OIF and can be saved in multiple locations.
Once an import wizard filter file has been created, the impfile X-Function can be used to access
the filter and perform custom importing using the settings saved in the filter file.
string fname$, path$, filtername$;
// point to file path
path$ = system.path.program$ + "Samples\Import and Export\";
// find files that match specification
findfiles ext:="S*.dat";
// point to Import Wizard filter file
string str$ = "Samples\Import and Export\VarsFromFileNameAndHeader.oif";
filtername$ = system.path.program$ + str$;
// import all files using filter in data folder
impfile location:=data;

10.2.7 Import from a Database

Origin provides four functions for Database Queries. The basic functionality of Database importing is
encapsulated in two functions as shown in this example using the standard Northwind database
provided by Microsoft Office:
// The dbedit function allows you to create the query and connection
// strings and attach these details to a worksheet
dbedit exec:=0

188
 Importing

sql:="Select Customers.CompanyName, Orders.OrderDate,

[Order Details].Quantity, Products.ProductName From
((Customers Inner Join Orders On Customers.CustomerID = Orders.CustomerID)
Inner Join [Order Details] On Orders.OrderID = [Order Details].OrderID)
Inner Join Products On Products.ProductID = [Order Details].ProductID"
connect:="Provider=Microsoft.Jet.OLEDB.4.0;User ID=;
Data Source=C:\Program Files\Microsoft Office\OFFICE11\SAMPLES\Northwind.mdb;
Mode=Share Deny None;Extended Properties="";
Jet OLEDB:System database="";
Jet OLEDB:Registry Path="";
Jet OLEDB:Database Password=***;
Jet OLEDB:Engine Type=5;
Jet OLEDB:Database Locking Mode=1;
Jet OLEDB:Global Partial Bulk Ops=2;
Jet OLEDB:Global Bulk Transactions=1;
Jet OLEDB:New Database Password="";
Jet OLEDB:Create System Database=False;
Jet OLEDB:Encrypt Database=False;
Jet OLEDB:Don't Copy Locale on Compact=False;
Jet OLEDB:Compact Without Replica Repair=False;
Jet OLEDB:SFP=False;Password="

// The dbimport function is all that's needed to complete the import

dbimport;
Two additional functions allow you to retrieve the details of your connection and query strings and
execute a Preview/Partial import.
Name Brief Description

dbEdit Create, Edit, Load or Remove a query in a worksheet.

dbImport Execute the database query stored in a specific worksheet.

Read the sql string and the connection string contained in a database query in
dbInfo
a worksheet.

Execute a limited import (defaults to 50 rows) of a query. Useful in testing to

dbPreview
verify that your query is returning the information you want.

10.3 Importing Images

The ImpImage X-Function supports importing image files into Origin from script. By default, the image
is stored in Origin as an image (i.e., RGB values). You have the option to convert the image to
grayscale.
Multiple-file importing is supported. By default, multiple images will be appended to the target page by
creating new layers. If importing to a matrix, each matrix-layer will be renamed to the corresponding
imported file's name.

10.3.1 Import Image to Matrix and Convert to Data

This example imports a single image file to a matrix and then converts the (RGB color) image to
grayscale values, storing them in a new matrix.

189
 LabTalk Scripting Guide

newbook mat:=1; // Create a new matrix book

fpath$ = "Samples\Image Processing and Analysis\car.bmp";
string fname$ = system.path.program$ + fpath$;

// Imports the image on path 'fname$' to the active window

//(the new matrix book)
impimage;

// Converts the image to grayscale values,and puts them in a new matrix

// 'type' specifies bit-depth: 0=short (2-byte/16-bit, default);
// 1=byte (1-byte/8-bit)
img2m type:=byte;

10.3.2 Import Single Image to Matrix

This example imports a series of *.TIF images into a new Matrix Book. As an alternative to the
img2m X-Function (shown above), the keyboard shortcuts Ctrl+Shift+d and Ctrl+Shift+i toggle
between the matrix data and image representations of the file.
newbook mat:=1;
fpath$ = "Samples\Image Processing and Analysis\";
string fns, path$ = system.path.program$ + fpath$;
// Find the files whose names begin with 'myocyte'
findfiles fname:=fns$ ext:="myocyte*.tif";
// Import each file into a new sheet (options.Mode = 4)
impimage options.Mode:=4 fname:=fns$;

10.3.3 Import Multiple Images to Matrix Book

This example imports a folder of JPG images to different Matrix books.
string pth1$ = "C:\Documents and Settings\All Users\"
string pth2$ = "Documents\My Pictures\Sample Pictures\";
string fns, path$ = pth1$ + pth2$;
// Find all *.JPG files (in 'path$', by default)
findfiles fname:=fns$ ext:="*.jpg";
// Assign the number of files found to integer variable 'n'
// 'CRLF' ==> files separated by a 'carriage-return line-feed'
int n = fns.GetNumTokens(CRLF);
string bkName$;
string fname$;
// Loop through all files, importing each to a new matrix book
for(int ii = 1; ii<=n; ii++)
{
fname$ = fns.GetToken(ii, CRLF)$;

//create a new matrix page

newbook s:=0 mat:=1 result:=bkName$;
//import image to the first layer of the matrix page,
//defaut file name is fname$
impimage orng:=[bkName$]msheet1;
}

10.3.4 Import Image to Graph Layer

You also can import an Image to an existing GraphLayer. Here the image is only for display (the data
will not be visible, unless it is converted to a matrix, see next example).

190
 Importing

string fpath$ = "Samples\Image Processing and Analysis\cell.jpg";

string fn$ = system.path.program$ + fpath$;
insertImg2g fname:=fn$ ipg:=graph1;

191
11 Exporting

11.1 Exporting

This chapter covers the following topics:

 Exporting Worksheets

 Exporting Graphs

 Exporting Matrices

 Exporting Videos

Origin provides a collection of X-Functions for exporting data, graphs, and images. All X-Functions
pertaining to exporting have names that start with the letters exp. The table below provides a listing
of these X-Functions. As with all X-Functions, help-file information is available at Script or Command
line by entering the name of the X-Function with the -h option. For instance: entering expgraph -h in
the Script window will display the help file immediately below the command.
Name Brief Description

expASC Export worksheet data as ASCII file

expGraph Export graph(s) to graphics file(s)

expImage Export the active Image into a graphics file

expMatASC Export matrix data as ASCII file

expNITDM Export workbook data as National Instruments TDM and TDMS files

expWAV Export data as Microsoft PCM wave file

expWks Export the active sheet as raster or vector image file

img2GIF Export the active Image into a gif file

11.2 Exporting Worksheets

11.2.1 Export a Worksheet
Your worksheet data may be exported either as an image (i.e., PDF) or as a data file.

193
 LabTalk Scripting Guide

11.2.1.1 Export a Worksheet as an Image File

The expWks X-Function can be used to export the entire worksheet, the visible area of the
worksheet, or worksheet selection, to an image file such as JPEG, EPS, or PDF:
// Export the active worksheet to an EPS file named TEST.EPS,
// saved to the D:\ drive.
expWks type:=EPS export:=active filename:="TEST" path:="D:";
The expWks X-Function also provides options for exporting many worksheets at the same time using
the export option, which if unspecified simply exports the active worksheet.
In the following example, export:=book exports all worksheets in the current workbook to the desired
folder path:
expWks type:=PDF export:=book path:="D:\TestImages" filename:=Sheet#;
Worksheets are saved in the order they appear in the workbook from left to right. Here, the naming
has been set to number the sheets in that order, as in 'Sheet1', 'Sheet2', etc. If more than 9 sheets
exist, filename:=Sheet## will yield names such as 'Sheet01'.
Other options for export are project, recursive, folder, and specified.
The expWks X-Function is particularly useful in exporting custom report worksheets that user may
create by placing graphs and other relevant analysis results in a single sheet for presentation, using
formatting features such as merging and coloring cells.

11.2.1.2 Export a Worksheet as a Multipage PDF File

The expPDFw X-Function allows exporting worksheets to multi-page PDF files. This X-Function is
then useful to export large worksheets, including custom report sheets, where the worksheet has
more content than can fit in one page for the current printer settings. This X-Function offers options
such as printing all sheets in a book or all sheets in the project, and options for including a cover
page and adding page numbering.

11.2.1.3 Export a Worksheet as a Data File

In this example, worksheet data is output to an ASCII file with tabs separating the columns using the
expAsc X-Function:
// Export the data in Book 2, Worksheet 3 using tab-separators to
// an ASCII file named TEST.DAT, saved to the D:\ drive.

expASC iw:=[Book2]Sheet3 type:=0 path:="D:\TEST.DAT" separator:=TAB;

Note, in this example, that type simply indicates the type of file extension, and may be set to any of
the following values (type:=dat is equivalent to type:=0):
 0=dat:*.dat,

 1=text:Text File(*.txt),

 2=csv:*.csv,

 3=all:All Files(*.*)

11.3 Exporting Graphs

Here are three examples of exporting graphs using the X-Function expGraph called from LabTalk:

11.3.1 Export a Graph with Specific Width and Resolution (DPI)

194
 Exporting

Export a graph as an image using the expGraph X-Function. The image size options are stored in
the nodes of tree variable named tr1, while resolution options (for all raster type images) are stored in
a tree named tr2.
One common application is to export a graph to a desired image format specifying both the width of
the image and the resolution. For example, consider a journal that requires, for a two-column article,
that graphs be sent as high-resolution (1200 DPI), *.tif files that are 3.2 inches wide:
// Export the active graph window to D:\TestImages\TEST.TIF.
// Width = 3.2 in, Resolution = 1200 DPI

expGraph type:=tif path:="D:\TestImages" filename:="TEST"

tr1.unit:=0
tr1.width:=3.2
tr2.tif.dotsperinch:=1200;
Possible values for tr1.unit are:
 0 = inch

 1 = cm

 2 = pixel

 3 = page ratio

Note: this is a good example of accessing data stored in a tree structure to specify a particular type of
output. The full documentation for tr1 can be found in the online and product (CHM) help.

11.3.2 Exporting All Graphs in the Project

Exporting all of the graphs from an Origin Project can be achieved by combining the doc -e
command, which loops over all specified objects in a project with the expGraph X-Function.
For example, to export all graphs in the current project as a bitmap (BMP) image, as above:
doc -e P
{
// %H is a string register that holds the name of the active window.
expGraph type:=bmp path:="d:\TestImages" filename:=%H
tr1.unit:=2
tr1.width:=640;
}
Several examples of doc -e can be found in Looping Over Objects.

11.3.3 Exporting Graph with Path and File Name

The string registers, %G and %X, hold the current project file name and path. Combine with the label
command, you can place these information on page while exporting a graph. For example:
// Path of the project
string proPath$ = system.path.program$ + "Samples\Graphing\Multi-Curve
Graphs.opj";
// Open the project
doc -o %(proPath$);
// Add file path and name to graph
win -a Graph1;
label -s -px 0 0 -n ForPrintOnly \v(%X%G.opj);
// Export graph to disk D
expGraph type:=png filename:=%H path:=D:\;
// Delete the file path and name

195
 LabTalk Scripting Guide

label -r ForPrintOnly;

11.4 Exporting Matrices

Matrices can store image data as well as non-image data in Origin. In fact, all images in Origin are
stored as matrices, whether or not they are rendered as a picture or displayed as pixel values. A
matrix can be exported no matter which type of content it holds.
Exporting matrices with script is achieved with two X-Functions: expMatAsc for a non-image matrix
and expImage for an image matrix.

11.4.1 Exporting a Non-Image Matrix

To export a matrix that holds non-image data to an ASCII file use the expMatAsc X-Function.
Allowed export extenstions are *.dat (type:=0), *.txt (type:=1), *.csv (type:=2), and all file types
(type:=3).
// Export a matrix (in Matrix Book 1, Matrix Sheet 1) to a file of
// the *.csv type named TEST.CSV with xy-gridding turned on.

expMatASC im:=[MBook1]MSheet1 type:=2 path:="D:\TEST.CSV" xygrid:=1;

11.4.2 Exporting an Image Matrix

Matrix windows in Origin can contain multiple sheets, and each sheet can contain multiple matrix
objects. A matrix object can contain an image as RGB values (default, reported as three numbers in a
single matrix cell, each matrix cell corresponds to a pixel), or as gray-scale data (a single gray-scale
number in each matrix cell).
For example, a user could import an image into a matrix object (as RGB values) and later convert it to
gray-scale data (i.e., the gray-scale pixel values) using the Image menu. Whether the matrix object
contains RGB or gray-scale data, the contents of the matrix can be exported as an image file to disk,
using the expImage X-Function. For example, the following script command exports the first matrix
object in Sheet 1 of matrix book MBook 1:
// Export the image matrix as a *.tif image:
expImage im:=[MBook1]1!1 type:=tif fname:="c:\flower"
When exporting to a raster-type image format (includes JPEG, GIF, PNG, TIF), one may want to
specify the bit-depth as well as the resolution (in dots-per-inch, DPI). This is achieved with the
expImage options tree, tr. The X-Function call specifying these options might look like this:
expImage im:=[MBook1]MSheet1! type:=png fname:="D:\TEST.PNG"
tr.PNG.bitsperpixel:="24-bit Color"
tr.PNG.dotsperinch:=300;
All nodes of the tree tr, are described in the online or product (CHM) help.

11.5 Exporting Videos

To export group of graphs as a video, you need to use the Video Writer (vw) object. In order to export
a video with actual frames, you must create a video writer object, write some windows to it as frames
and then release the video writer. You can only work with one video writer at a time, i.e. each time
you create a video writer object with the vw.Create( ) method, you must use vw.Release( ) to release
the video writer before you can use the vw.Create( ) method again.
We provide several example scripts showing how to create, write graphs to, or release a video writer
object. You can also view a full example in the LabTalk Examples category.

196
 Exporting

11.5.1 Create a Video Writer Object

To export a video, first create a video writer object with the vw.Create( ) method. At a minimum, you
need to specify the file name (including the complete file path) of the video. You can also specify the
codec value for the compression method, frames per second and video dimensions, at this stage.
For example, this script creates a video file named "test.avi" in an existing file path D:\Exported
Videos\ with other settings as default (i.e. no compression, 1 frame per second, 640 px as width and
480 px as height):
vw.Create("D:\Exported Videos\test.avi");
//The above script is the same as the script below
//vw.Create("D:\Exported Videos\test.avi", 0, 1, 640, 480);
You can also define the compression method with FourCC code. For example, the script below uses
WMV1 compressed format to create the video:
//Define codec with four character code
int codec = vw.FourCC('W', 'M', 'V', '1');
//Create a 800*600 video file as test.avi under user files folder
vw.Create(%Y\My Video.avi, codec, 1, 800, 600)
To check if the video creation is successful, use vw.Create( ). The vw.Create( ) method returns 0 if
the video is created, and returns a non-zero value if the creation fails. For example:
//If file path D:\AAA exist,the following should return 0
//If the file path does NOT exist, it will return error code
int err = vw.Create(D:\AAA\test.avi);
if(err==0)
type "video creation is successful";
else
type "video creation failure, the error code is $(err)";

11.5.2 Write Graph(s) to a Video Writer Object

Once a video writer object is created, you can start to write graphs into it with the vw.WriteGraph( )
method. In addition to graph windows, you can write other windows including function plots,
workbooks, matrixes, and layout pages.
This example script writes the current active window to the video.
vw.WriteGraph( );
You can specify the window name and also the number of frames to write. For example, the following
script will add Graph1 as 5 frames:
vw.WriteGraph(Graph1,5);
You can make use of a loop structure to, for example, add all graphs in a video, so that you do not
need to write multiple lines of script. The example below writes all graph windows in the project to the
video. Each graph will be inserted as 2 frames.
doc -e P
{
vw.WriteGraph(,2);
}
You can return an error code from this method as in the last example of the create video writer
session. If the return value is 0, it means that writing the graph (or other window) was successful.

11.5.3 Release a Video Writer Object

For each video writer object, it is essential to release the video writer to generate the video. The
method used in this case is vw.Release( ).

197
 LabTalk Scripting Guide

The following script shows a complete example of generating a video file "example.avi" in the user
files folder with a newly created empty graph window.
int err = vw.Create(%Y\example.avi);
//Write existing graphs into the video if the video can be created.
if(0 == err)
{
//Create an empty graph window with default template
win -t plot;
vw.WriteGraph( );
}
//Release the video writer
vw.Release( );
The vw.Release( ) method also has a return value. If it is 0 then the video generation is successful; if
it is 1, it indicates that the video generation failed.

198
12 The Origin Project

12.1 The Origin Project

The Origin Project contains all of your data, operations, graphs, and reports. This chapter
discusses techniques for managing the elements of your project using script, and is presented in
the following sections:

 Managing the Project

 Accessing Metadata

 Looping Over Objects

 Protecting Project Data

12.2 Managing the Project

12.2.1 The DOCUMENT Command
Document is a native LabTalk command that lets you perform various operations related to the
Origin Project. The syntax for the document command is
document -option value;
Notes:
 value is not applicable for some options and is left out of the command

 For additional capabilities please see the Doc (Object).

Internally, Origin updates a property that indicates when a project has been modified. Attempting to
Open a project when the current project has been modified normally triggers a prompt to Save the
current project. The document command has options to control this property.

12.2.1.1 Start a New Project

// WARNING! This will turn off the Save project prompt
document -s;
// ''doc'' is short for ''document'' and ''n'' is short for ''new''
doc -n;

12.2.1.2 Open/Save a project

Use the doc -o command to open a project and the save command to save it.

199
 LabTalk Scripting Guide

// Open an Origin Project file

string fname$ = SYSTEM.PATH.PROGRAM$ + "Origin.opj";
doc -o %(fname$); // Abbreviation of ''document -open''
// Make some changes
%(Data1,1) = data(0,100);
%(Data1,2) = 100 * uniform(101);
// Save the project with a new name in new location
fname$ = SYSTEM.PATH.APPDATA$ + "My Project.opj";
save %(fname$);

12.2.1.3 Append projects

Continuing with the previous script, we can Append other project file(s). Origin supports only one
project file at a time so the existing project plus the appended project become the new project.
// Append an Origin Project file to the current file
fname$ = SYSTEM.PATH.PROGRAM$ + "Origin.opj";
doc -a %(fname$); // Abbreviation of ''document -append''
// Save the current project - which is still ''My Project.opj''
save;
// Save the current project with a new name to a new location
save C:\Data Files\working.opj;

12.2.1.4 Save/Load Child Windows

In Origin, a child window - such as a graph, workbook, matrix or Excel book - can be saved as a
single file. Append can be used to add the file to another project. The appropriate extension is added
automatically for Workbook, Matrix and Graph whereas you must specify .XLS for Excel windows.
// The save command acts on the active window
save -i C:\Data\MyBook;
Append can be used to load Child Window Types :
// Workbook(*.OGW), Matrix(*.OGM), Graph(*.OGG), Excel(*.XLS)
dlgfile group:=*.ogg;
// fname is the string variable set by the dlgfile X-Function
doc -a %(fname$);
For Excel, you can specify that an Excel file should be imported rather than opened as Excel
doc -ai "C:\Data\Excel\Current Data.xls";
Notes windows are a special case with special option switch:
// Save notes window named Notes1
save -n Notes1 C:\Data\Notes\Today.TXT;
// Read text file into notes window named MyNotes
open -n C:\Data\Notes\Today.txt MyNotes;

12.2.1.5 Saving External Excel Book

This is introduced in Origin 8.1, to allow an externally linked Excel book to be saved using its current
file name:
save -i;

12.2.1.6 Refresh Windows

You can refresh windows with the following command:
doc -u;

12.2.2 Project Explorer X-Functions

200
 The Origin Project

The following X-Functions provide DOS-like commands to create, delete and navigate through the
subfolders of the project:
Name Brief Description

pe_dir Show the contents of the active folder

pe_cd Change to another folder

pe_move Move a Folder or Window

pe_path Report the current path

pe_rename Rename a Folder or Window

pe_mkdir Create a Folder

pe_rmdir Delete a Folder

In this example :
doc -s; // Clear Origin's 'dirty' flag
doc -n; // Start a new project
pe_cd /; // Go to the top level
pe_mkdir "Test Subjects"; // Create a folder
pe_cd "Test Subjects"; // Navigate to that folder
pe_mkdir "Trials"; // Create a sub-folder
pe_mkdir "Results"; // and another
pe_cd /; // Return to the top level
pe_mkdir "Control Subjects"; // Create another folder
pe_cd "Control Subjects"; // Navigate to that folder
pe_mkdir "Trials"; // Create a sub-folder
pe_mkdir "Results"; // and another
pe_cd /; // Return to the top level
pe_mkdir "Comparison"; // Create a folder

201
 LabTalk Scripting Guide

we create a folder structure that looks like this in Project explorer :

Note that if you have Open in Subfolder enabled in Tools : Options : [Open/Close] then you will have
an additional folder named Folder1.

12.3 Accessing Metadata

Metadata is information which refers to other data. Examples include the time at which data was
originally collected, the operator of the instrument collecting the data and the temperature of a sample
being investigated. Metadata can be stored in Projects, Pages, Layers and Columns.

12.3.1 Column Label Rows

Metadata is most visible in a worksheet where column headers may contain information such as Long
Name (L), Units (U), Comments(C), Sampling Interval and various Parameter rows, including User-
Defined parameters.
The row indices for column label rows are assigned to characters, which are given in the Column
Label Row reference table. Examples of use follow.

12.3.1.1 Read/Write Column Label Rows

At times you may want to capture or set the Column Label Rows or Column Header string from script.
Access the label row by using the corresponding label row characters as a row index.
Note: Numeric cell access does not supported to use label row characters.
Here are a few examples of reading and writing column header strings:
Book1_A[L]$ = Time; // Set the Long Name of column A to '''Time'''
Book1_A[U]$ = sec; // Set the Units of column A to '''sec'''
string strC$ = col(2)[C]$; // Read the Comments of column2 into strC$
// Get value from first system parameter row
double syspar1 = %(col(2)[p1]$);
Col(1)[L]$="Temperature"; // set Col(1) long name to "Temperature"
range bb = 2; // declare a range variable for Col(2)
// Set the long name of Col(2) to that of Col(1) with the string " Data"
// appended
bb[L]$=Col(1)[L]$+" Data";

202
 The Origin Project

Note: For Origin 8.0, LabTalk variables took precedence over Column Label Row characters, for
example:
int L = 4; // For Origin 8.0 and earlier ...
Col(B)[L]$= // Returns the value in row 4 of Col(B), as a string
But for Origin 8.1, this has been changed so that the column label rows (L, U, C, etc.) will take
precedence:
int L = 4; // For Origin 8.1 ...
Col(B)[L]$= // Returns the Long Name of Col(B), as a string
The following example shows how to create and access user parameter rows
// Show the first user parameter row
wks.userParam1 = 1;
// Assign the 1st user parameter row a custom name
wks.userParam1$ = "Temperature";
// Write to a specific user parameter row of a column
col(2)[Temperature]$ = "96.8";
// Get a user-defined parameter row value
double temp = %(col(2)[Temperature]$);

12.3.1.2 Show/Hide Column Labels

You can set which column header rows are displayed and in what order by wks.labels object method.
For the active worksheet, this script specifies the following column header rows (in the order given):
Long Name, Unit, the first System-Parameter, the First User-Parameter, and Comments:
range ww = !;
ww.labels(LUP1D1C);

12.3.2 Even Sampling Interval

Origin users can set the sampling interval (X) for a data series (Y) to something other than the
corresponding row numbers of the data points (default).

12.3.2.1 Accessing the Sampling Interval Column Label Row

When this is done, a special header row is created to remind the user of the custom interval (and
initial value) applied. To access the text in this header row, simply use the E row-index character.
This header is effectively read-only and cannot be set to an arbitrary string, but the properties from
which this string is composed may be changed with either column properties (see the wks.col object)
or the colint X-Function.
// Read the Sampling Interval header text of Column 1 to a string variable
string sampInt$ = Col(1)[E]$;
// If an initial value of 2 and increment of 0.5 was set for Col(1),
// the output will be:
sampInt$=; // "x0 = 2"
// "dx = 0.5"

To see a Sampling Interval header, you can try the following steps:

1. Create a new worksheet and delete the X-column

2. Right-click at the top of the remaining column (i.e., B(Y)), such that then entire

column is selected, and select Set Sampling Interval from the drop-down

203
 LabTalk Scripting Guide

menu.

3. Set the initial and step values to something other than 1.

4. Click OK, and you will see a new header row created which lists the values you

specified.

The next example demonstrates how to do this from script, using X-functions.
Also, when you import certain types of data, e.g. *.wav, the sampling interval will show
as a header row.

12.3.2.2 Sampling Interval by X-Function

Sampling Interval is special in that its display is formatted for the user's information.
Programmatically, it is accessed as follows
// Use full formal notation of an X-Function
colint rng:=col(1) x0:=68 inc:=.25 units:=Degrees lname:="Temperature";
// which in shorthand notation is
colint 1 68 .25 Degrees "Temperature";
The initial value and increment can be read back using worksheet column properties:
double XInitial = wks.col1.xinit;
double XIncrement = wks.col1.xinc;
string XUnits$ = wks.col1.xunits$;
string XName$ = wks.col1.xname$;
Note: While these properties will show up in a listing of column properties (Enter wks.col1.= in the
Script window to display the property names for column 1), unless a sampling interval is established:
 The strings wks.col1.xunits$ and wks.col1.xname$ will have no value.

 The numeric values wks.col1.xinit and wks.col1.xinc will each have a value of 1,

corresponding to the initial value and increment of the row numbers.

12.3.3 Trees
Trees are a data type supported by LabTalk, and we also consider trees a form of metadata since
they give structure to existing data. They were briefly introduced in the section dealing with Data
Types and Variables, but appear again because of their importance to X-functions.
Many X-functions input and output data in tree form. And since X-functions are one of the primary
tools accessible from LabTalk script, it is important to recognize and use tree variables effectively.

12.3.3.1 Access Import File Tree Nodes

After importing data into a worksheet, Origin stores metadata in a special tree-like structure at the
page level. Basic information about the file can be retrieved directly from this structure:
string strName, strPath;
double dDate;
// Get the file name, path and date from the structure
strName$ = page.info.system.import.filename$;
strPath$ = page.info.system.import.filepath$;

204
 The Origin Project

dDate = page.info.system.import.filedate;
// Both % and $ substitution methods are used
ty File %(strPath$)%(strName$), dated $(dDate,D10);
This tree structure includes a tree with additional information about the import. This tree can be
extracted as a tree variable using an X-Function:
Tree MyFiles;
impinfo ipg:=[Book2] tr:=MyFiles;
MyFiles.=; // Dump the contents of the tree to the script Window
Note: The contents of the impinfo tree will depend on the function used to import.
If you import multiple files into one workbook (using either New Sheets, New Columns or New Rows)
then you need to load a particular tree for each file as the Organizer only displays the system
metadata from the last import:
Tree trFile;
int iNumFiles;
// Use the function first to find the number of files
impinfo trInfo:=trFile fcount:=iNumFiles;
// Now loop through all files - these are indexed from 0
for( idx = 0 ; idx < iNumFiles ; idx++ )
{
// Get the tree for the next file
impinfo findex:=idx trInfo:=trFile;
string strFileName, strLocation;
//
strFileName$ = trFile.Info.FileName$;
strLocation$ = trFile.Info.DataRange$;
ty File %(strFileName$) was imported into %(strLocation$);
}

12.3.3.2 Access Report Page Tree

Analysis Report pages are specially formatted Worksheets based on a tree structure. You can get
this structure into a tree variable using the getresults X-Function and extract results.
// Import an Origin Sample file
string fpath$ = "Samples\Curve Fitting\Gaussian.dat";
string fname$ = SYSTEM.PATH.PROGRAM$ + fpath$;
impasc;
// Run a Gauss fit of the data and create a Report sheet
nlbegin (1,2) gauss;
nlfit;
nlend 1 1;
// An automatically-created string variable, __REPORT$,
// holds the name of the last Report sheet created:
string strLastReport$ = __REPORT$;
// This is the X-Function which gets the Report into a tree
getresults tr:=MyResults iw:=%(strLastReport$);
// So now we can access those results
ty Variable\tValue\tError;
separator 3;
ty y0\t$(MyResults.Parameters.y0.Value)\t$(MyResults.Parameters.y0.Error);
ty xc\t$(MyResults.Parameters.xc.Value)\t$(MyResults.Parameters.xc.Error);
ty w\t$(MyResults.Parameters.w.Value)\t$(MyResults.Parameters.w.Error);
ty A\t$(MyResults.Parameters.A.Value)\t$(MyResults.Parameters.A.Error);

12.3.3.3 User Tree in Page Storage

205
 LabTalk Scripting Guide

Information can be stored in a workbook, matrix book or graph page using a tree structure. The
following example shows how to create a section and add subsections and values to the active page
storage area.
// Add a new section named Experiment
page.tree.add(Experiment);
// Add a sub section called Sample;
page.tree.experiment.addsection(Sample);
// Add values to subsection;
page.tree.experiment.sample.RunNumber = 45;
page.tree.experiment.sample.Temperature = 273.8;
// Add another subsection called Detector;
page.tree.experiment.addsection(Detector);
// Add values;
page.tree.experiment.detector.Type$ = "InGaAs";
page.tree.experiment.detector.Cooling$ = "Liquid Nitrogen";
Once the information has been stored, it can be retrieved by simply dumping the storage contents:
// Dump entire contents of page storage
page.tree.=;
// or programmaticaly accessed
temperature = page.tree.experiment.sample.temperature;
string type$ = page.tree.experiment.detector.Type$;
ty Using %(type$) at $(temperature)K;
You can view such trees in the page Organizer for Workbooks and Matrixbooks.

12.3.3.4 User Tree in a Worksheet

Trees stored at the Page level in a Workbook can be accessed no matter what Sheet is active. You
can also store trees at the sheet level:
// Here we add two trees to the active sheet
wks.tree.add(Input);
// Dynamically create a branch and value
wks.tree.input.Min = 0;
// Add another value
wks.tree.input.max = 1;
// Add second tree
wks.tree.add(Output);
// and two more values
wks.tree.output.min = -100;
wks.tree.output.max = 100;

// Now dump the trees

wks.tree.=;
// or access it
ty Input $(wks.tree.input.min) to $(wks.tree.input.max);
ty Output $(wks.tree.output.min) to $(wks.tree.output.max);

// Access a sheet-level tree using a range

range rs = [Book7]Sheet2!;
rs!wks.tree.=;
You can view such trees in the page Organizer for Workbooks and Matrixbooks.

12.3.3.5 User Tree in a Worksheet Column

Individual worksheet columns can also contain metadata stored in tree format. Assigning and
retrieving tree nodes is very similar to the page-level tree.

206
 The Origin Project

// Create a COLUMN tree

wks.col2.tree.add(Batch);
// Add a branch
wks.col2.tree.batch.addsection(Mix);
// and two values in the branch
wks.col2.tree.batch.mix.ratio$ = "20:15:2";
wks.col2.tree.batch.mix.BatchNo= 113210;
// Add branch dynamically and add values
wks.col2.tree.batch.Line.No = 7;
wks.col2.tree.batch.Line.Date$ = 3/15/2010;

// Dump the tree to the Script Window

wks.col2.tree.=;
// Or access the tree
batch = wks.col2.tree.batch.mix.batchno;
string strDate$ = wks.col2.tree.batch.Line.Date$;
ty Batch $(batch) made on %(strDate$) [$(date(%(strDate$)))];
You can view these trees in the Column Properties dialog on the User Tree tab.

12.4 Looping Over Objects

There may be instances where it is desirable to perform a certain task or set of tasks on every object
of a particular type that exists in the Origin project. For example, you might want to rescale all of your
project graph layers or add a new column to every worksheet in the project. The LabTalk document
command (or doc) facilitates this type of operation. Several examples are shown here to illustrate the
doc command.

12.4.1 Looping over Objects in a Project

The document command with the -e or -ef switch (or doc -e command), is the primary means for
looping over various collections of objects in an Origin Project. This command allows user to execute
multiple lines of LabTalk script on each instance of the Origin Object found in the collection.

12.4.1.1 Looping over Workbooks and Worksheets

You can loop through all worksheets in a project with the doc -e LB command. The script below loops
through all worksheets, skipping the matrix layers:
//loop over all worksheets in project to print their names
//and the number of columns on each sheet
doc -e LB {
if(exist(%H,2)==0) //not a workbook, must be a matrix
continue;
int nn = wks.nCols;
string str=wks.Name$;
type "[%H]%(str$) has $(nn) columns";
}
The following example shows how to loop and operate on data columns that reside in different
workbooks of a project.
Open the sample project file available since Origin 8.1 SR2:
\\Samples\LabTalk Script Examples\Loop_wks.opj
In the project there are two folders for two different samples and a folder named Bgsignal for the
background signals alone. Each sample folder contains two folders named Freq1 and Freq2, which
correspond to data at a set frequency for the specific sample.

207
 LabTalk Scripting Guide

The workbook in each Freq folder contains three columns including DataX, DataY and the frequency,
which is a constant. The workbook's name in the Bgsignal folder is Bgsig. In the Bgsig workbook,
there are three columns including DataX and two Y columns whose long names correspond to set
frequencies in the workbook in each Freq folder.
The aim is to add a column in each workbook and subtract the background signal for a particular
frequency from the sample data for the same frequency. The following Labtalk script performs this
operation.
doc -e LB
{ //Loop over each worksheet.
if(%H != "Bgsig") //Skip the background signal workbook.
{
Freq=col(3)[1]; //Get the frequency.
wks.ncols=wks.ncols+1; //Add a column in the sample sheet.
//bg signal column for Freq using long name.
range aa=[Bgsig]1!col("$(Freq)");
wcol(wks.ncols)=col(2)-aa; //Subtract the bg signal.
wcol(wks.ncols)[L]$="Remove bg signal"; //Set the long name.
}
}
For increased control, you may also loop through the books and then loop through the sheets in your
code, albeit a bit more slowly than the code above.
The following example shows how to loop over all workbooks in the current/active Project Explorer
Folder, and then loop over each sheet inside each book that is found:
int nbooks = 0;
// Get the name of this folder
string strPath;
pe_path path:=strPath;
// Loop over all Workbooks ...
// Restricted to the current Project Explorer Folder View
doc -ef W {
int nsheets = 0;
// Loop over all worksheets in each workbook
doc -e LW {
type Sheet name: %(layer.name$);
nsheets++;
}
type Found $(nsheets) sheet(s) in %H;
type %(CRLF);
nbooks++;
}
type Found $(nbooks) book(s) in folder %(strPath$) of project %G;
Additionally, we can replace the internal loop using Workbook properties:
int nbooks = 0;
// Get the name of this folder
string strPath;
pe_path path:=strPath;
// Loop over all Workbooks ...
// Restricted to the current Project Explorer Folder View
doc -ef W {
// Loop over all worksheets in each workbook
loop(ii,1,page.nlayers) {
range rW = [Book1]$(ii)!;
type Sheet name: %(rw.name$);
}
type Found $(page.nlayers) sheet(s) in %H;

208
 The Origin Project

type %(CRLF);
nbooks++;
}
// Final report - %G contains the project name
type Found $(nbooks) book(s) in folder %(strPath$) of project %G;

12.4.1.2 Looping Over Graph Windows

Here we loop over all plot windows (which include all Graph, Function Plots, Layout pages and
embedded Graphs).
doc -e LP
{
// Skip over any embedded graphs or Layout windows
if(page.IsEmbedded==0&&exist(%H)!=11)
{
string name$ = %(page.label$);
if(name.Getlength()==0 ) name$ = %H;
type [%(name$)]%(layer.name$);
}
}
The following script prints the contents of all graph windows in the project to the default printer driver.
doc -e P print; // Abbreviation of ''document -each Plot Print''

12.4.1.3 Looping Over Workbook Windows

The document -e command can be nested as in this example that loops over all Y datasets within all
Worksheets:
doc -e W
{
int iCount = 0;
doc -e DY
{
iCount++;
}
if( iCount < 2 )
{ type Worksheet %H has $(wks.ncols) columns,;
type $(iCount) of which are Y columns; }
else
{ type Worksheet %H has $(wks.ncols) columns,;
type $(iCount) of which are Y columns; }
}

12.4.1.4 Looping over Columns and Rows

This example shows how to loop over all columns and delete every nth column
int ndel = 3; // change this number as needed;
int ncols = wks.ncols;
int nlast = ncols - mod(ncols, ndel);
// Need to delete from the right to the left
for(int ii = nlast; ii > 0; ii -= ndel)
{
delete wcol($(ii));
}
This example shows how to delete every nth rows in a worksheet.
int ndel = 3; // change this number as needed

209
 LabTalk Scripting Guide

range rr = col(1); // Get a range for column 1

nrows = rr.GetSize(); // Get the number of rows
int nlast = nrows - mod(nrows, ndel);
// Need to delete from the bottom to the top
for(int ii = nlast; ii > 0; ii -= ndel)
{
range rr = wcol(1)[$(ii):$(ii)];
mark -d rr;
}
This script calculates the logarithm of four columns on Sheet1, placing the result in the corresponding
column of Sheet2:
for(ii=1; ii<=4; ii++)
{
range ss = [book1]sheet1!col($(ii));
range dd = [book1]sheet2!col($(ii));
dd = log(ss);
}

12.4.1.5 Looping Over Graphic Objects

You can loop over all Graphic Objects in the active layer. By wrapping this with two other options we
can cover an entire project.
// For each Plot
doc -e P
{
// For each Layer in each Plot
doc -e LW
{
// For each Graphic Object in each Layer in each Plot
doc -e G
{ // Set Legend background to Shadow
if("%B"=="Legend") %B.background = 2;
// Set timestamp color to Blue
if("%B"=="timestamp") %B.color = color(blue);
}
}
}

12.4.2 Perform Peak Analysis on All Layers in Graph

This example shows how to loop over all layers in a graph and perform peak analysis on datasets in
each layer using a pre-saved Peak Analyzer theme file. It assumes the active window is a multi-layer
graph, and each layer has one data curve. It further assumes a pre-saved Peak Analyzer theme
exists.
// Block reminder messages before entering loop.
// This is to avoid either reminder message from popping up
// about Origin switching to the report sheet
type -mb 0;
// Loop over all layers in graph window
doc -e LW
{
// Perform peak analysis with preset theme
sec;
pa theme:="My Peak Fit";
watch;

210
 The Origin Project

/* sec and watch are optional,

they print out time taken for fitting data in each layer */
}
// Un-block reminder message
type -me;

12.5 Protecting Project Data

LabTalk commands to enable various protections on worksheets and workbooks were introduced in
Origin 9.1. This included a project-level Admin mode to control who could modify object-level
protections. You can control protection attributes of Origin objects (e.g. a workbook) without involving
Admin mode, but any such protections are not secured. Anyone can run LabTalk commands to
remove these protections.
To secure protection, you must setup an Admin password for the Origin project and then Origin
object protections cannot be altered until the correct password is entered. When security is not an
issue (e.g. you just want to prevent accidental modification or deletion of a certain book or sheet) you
can add object-level protections without an Admin password. For more information on setting up an
Admin password, see Admin Mode.

12.5.1 Project-level Protections

There are two types of project-level password protections:
 You can add a password to the Origin project and prevent unauthorized persons from opening

the OPJ. This method is accessible both from the GUI and from LabTalk script.

 You can add an Admin password to the project and prevent unauthorized editing of the OPJ.

This method does not restrict access to the OPJ; nor does it prevent a user from editing and

saving the OPJ to a new file name. This method is LabTalk script-accessible only.

12.5.1.1 Password Protection Against Opening the OPJ

When this type of password protection is enabled, you must enter a password to open the Origin
project (OPJ). This applies to opening by appending, opening by script, etc. To password protect a
project from being opened without permission:
 With the project file open, open the Script window or Command window and type

doc -pwd
This opens the Password dialog where you can set or change the project password.
 For GUI access to this feature, click Tools: Protection: Protect Project and enter a password.

12.5.1.2 Password Protection against Modifying the OPJ: Admin Mode

The concept of an Admin mode has been added to the Origin Project. Once a project is protected by
an Admin password, the project cannot be modified, nor can workbook and worksheet protection
features be changed without being logged into the OPJ as Admin.
To establish Admin protections for the OPJ, open the Script window and type:
doc -pwa [password] //adds Admin password ''password'' to the OPJ

211
 LabTalk Scripting Guide

As indicated by the square brackets, choosing a password is optional. If you do not choose a
password, you will not be required to supply one when logging into Admin mode.
Once you have created a password, or accepted the default ("origin"), log into Admin mode by
entering the following at the command line:
doc -pw [password] // log into Admin Mode. If password was specifed, give
password
Additional commands:
doc -pwx // logout of Admin Mode. No access to protections
doc -pwr // remove password. Must be logged in to execute
doc -pwta // list all books & sheets with protections enabled
For complete documentation on the document command see the document command.

12.5.1.3 App Title Bar Indication of Admin Mode

The Origin title bar indicates the Admin state of the Origin project:
 No Admin mode for OPJ (normal mode).

 Admin mode enabled for OPJ but user is not logged in as Admin.

 Admin mode enabled for OPJ and user is logged in as Admin.

12.5.1.4 Admin Mode and Saving the OPJ

Once a project has Admin mode enabled, it cannot be overwritten from Origin without logging in.
When an Admin-enabled OPJ is open, you may modify the OPJ in an unprotected area (see
Workbook- and Worksheet-level Protections) without logging in and you will see an asterisk(*)
appended to the file name in the Origin title bar.
 Unmodified file

 Modified file

The asterisk indicates that the OPJ has been modified, but you will not be able to save the OPJ
unless you log in before saving. You can exit the OPJ without saving and without logging in.

12.5.2 Worksheet- and Workbook-level Protections

The following protections can be applied without establishing an Admin mode. However, note that
without Admin mode, there is nothing to prevent others with file access from removing these
protections.
Protections can be applied or removed at the sheet level using the following command syntax:
layer -lw hex(hex value)
Protections can be applied or removed at the book level using the following command syntax:
page -lw hex(hex value)

212
 The Origin Project

There is a general inheritance rule on protection flags: Once you set protection on a book, then all
sheets inside the book will inherent the flags from the book. The exception to this rule is the Delete
flag. You must separately control book and sheet deletion flags (i.e. You may not want to allow book
deletion, but still allow deletion of individual sheets).

12.5.2.1 Layer and Page Protection Flags

For layer or page protections, hex value takes on the following:
Hex
Description
Value

-- Turn on all protection bits.

0 Remove all protections from the active worksheet/workbook.

2 Data: Include all the cells in a worksheet, data cells or label cells.

Structure: Keep the columns in the sheet unchanged. Prevent insert/delete columns
80
or moving columns, but allow rows to be changed.

100 Rename: Prevent changing sheet name (not supported for workbook).

400 Delete: Prevent object from being deleted.

Note: Before applying protections, please read the note on Exclusion Zones.

12.5.2.2 Layer and Page Protection Examples

The following examples demonstrate that multiple protection flags can be combined (hex values are
additive) to give greater control over what is protected.

Examples: Setting worksheet write access flags

lay -lw hex(82); //set active sheet to protect data and structure
lay -lw; //protect everything
lay -lw 2; //protect only data
lay -lw hex(180); //no insert/del cols/rows, no sheet rename
lay -lw 0; //remove all protections on the current sheet
... where hex value is derived from values in the above table.

Examples: Setting workbook write access flags

page -lw; //lock book and all sheets, no changes, cannot delete book or
sheets
page -lw hex(482); //lock delete, structure change and data edit

// prepare the book for locking active sheet but

// allow analysis results to be added to book
lay -lw hex(582); //no del, no rename, no add/insert/move col/rows, no edit

page -lw hex(400); //no del book

... where hex value is derived from values in the above table.

213
 LabTalk Scripting Guide

Note: As of Origin 2015 SR1, the command ...

page -lw; // lock book and all sheets

... does not prevent renaming of the workbook.

12.5.2.3 Print out current protection flags

layer -lt // print out current sheet protection flags
page -lt // print out current page protection flags
 For complete documentation on the layer command see the layer command.

 For complete documentation on the page command see the page command.

12.5.2.4 Exclusion Zones on a Read-Only Sheet

When you have locked a worksheet from modifications, all the cells in the sheet become read-only.
There may be instances -- e.g. you are setting up a sheet as a form -- where you want users to be
able to selectively modify the sheet. The following explains how to create and manage sheet
Exclusion Zones.

Commands to manage Exclusion Zones

layer -les n
... where n can be one of the following:
Value Description

0 Clear all Exclusion Zones from the active sheet.

Add the current selection, one range or multiple via CTRL+select, as new Exclusion
1
Zones.

2 List the Exclusion Zones in the Script window.

Note: You can only make Exclusion Zone modifications when the sheet is unprotected. To set the
sheet up as a form, you should (1) add all the needed Exclusion Zones, then (2) protect the sheet
from modification with lay -lw

12.5.2.5 Protecting Graphs

Although the script commands outlined here were implemented for workbooks and worksheets, the
Delete flag is general and can be used to protect graphs, as in the following example:
repeat 10 {win -t plot}; //create 10 graph windows
win -o graph4 {page -lw hex(400)}; //set graph4 protection
doc -e P {win -c}; //loop to delete all graph in opj. Graph4 will be
protected.

12.5.2.6 Script Example

214
 The Origin Project

The following script sets up a workbook with a locked data sheet and protects the workbook from
deletion. The OPJ can then be saved and shared with others who can view, graph, and analyze the
data, but cannot edit or delete.
Analysis results are output to additional sheets, so routines that generate output such as Smooth
should be configured to send output to another sheet, as the data sheet in this example will be
protected from modifications.
// Import a sample file
newbook;
string fname$=system.path.program$+"Samples\Curve Fitting\Gaussian.dat";
impasc;
// Set password and login - change mypwd to your desired password string
doc -pwa mypwd;
doc -pw mypwd;
// Protect data sheet structure, prevent editing, deleting
lay -lw hex(482);
// Protect page from deletion
page -lw hex(400);
// logout
doc -pwx;
// Now you can save the OPJ and others can view data, graph, and also analyze
// Analysis results can go into new sheets, not new cols in same sheet

215
13 Analysis and Applications

13.1 Analysis and Applications

Origin supports functions that are valuable to certain types of data analysis and specific mathematic
and scientific applications. The following sections provide examples on how to use some of these
functions, broken down by categories of use.

Topics covered in this section:

 LT Mathematics

 LT Statistics

 LT Curve Fitting

 Signal Processing

 Peaks and Baseline

 Image Processing

13.2 Mathematics
13.2.1 Mathematics
In this section we feature examples of four common mathematical tasks in data processing:

Topics covered in this section:

 Average Multiple Curves

 Differentiation

 Integration

217
 LabTalk Scripting Guide

 Interpolation

13.2.2 Average Multiple Curves

Multiple curves (XY data pairs) can be averaged to create a single curve, using the avecurves X-
Function. This X-Function provides several options such as using the input X values for the output
curve, or generating uniformly spaced X values for the output and then interpolating the input Y data
before averaging.
The following example demonstrates averaging with linear interpolation:
// Load sample data using existing 'loadDSC.ogs' script
string fpath$ = "Samples\LabTalk Script Examples\LoadDSC.ogs";
string LoadPath$=system.path.program$ + fpath$;
// If the data does not load properly, then stop script execution.
if(!run.section(%(LoadPath$), Main, 0)) break 1;
// Data should now be loaded now into the active workbook ...
// Get the name of the active workbook, %H points to the active workbook
string dscBook$=%H;

// Perform average on all data using linear interpolation

avecurves iy:=[dscBook$](1:end)!(1,2)
rd:=[<input>]<new name:="Averaged Data">!
method:=ave
interp:=linear;
Once averaged, the data and the result can be plotted:
// plot all the data and the averaged curve, using the plotxy X-Function:
plotxy [dscBook$](1:end)!(1,2) plot:=200;

13.2.3 Differentiation
13.2.3.1 Finding the Derivative
The following example shows how to calculate the derivative of a dataset. Note that the differentiate
X-Function is used, and that it allows higer-order derivatives as well:
// Import the data
newbook;
fname$ = system.path.program$ + "\Samples\Spectroscopy\HiddenPeaks.dat";
impasc;

// Calculate the 1st and 2nd derivatives of the data in Column 2:

// Output defaults to the next available column, Column 3

differentiate iy:=Col(2);
// Output goes into Column 4 by default
differentiate iy:=Col(2) order:=2;

// Plot the source data and the results

// Each plot uses Column 1 as its x-values

plotstack iy:=((1,2), (1,3), (1,4)) order:=top;

13.2.3.2 Finding the Derivative with Smoothing

218
 Analysis and Applications

The differentiate X-Function also allows you to obtain the derivatives using Savitsky-Golay
smoothing. If you want to use this capability, set the smooth variable to 1. Then you can customize
the smoothing by specifying the polynomial order and the points of window used in the Savitzky-
Golay smoothing method. The example below illustrates this.
// Import a sample data with noise
newbook;
fpath$ = "\Samples\Signal Processing\fftfilter1.DAT";
fname$ = system.path.program$ + fpath$;
impasc;
bkname$=%h;

// Differentiate using Savitsky-Golay smoothing

differentiate iy:=col(2) smooth:=1 poly:=1 npts:=30;

// Plot the source data and the result

newpanel row:=2;
plotxy iy:=[bkname$]1!2 plot:=200 ogl:=1;
plotxy iy:=[bkname$]1!3 plot:=200 ogl:=2;

13.2.4 Integration
The integ1 X-Function is capable of finding the area under a curve using integration. Both
mathematical and absolute areas can be computed. In the following example, the absolute area is
calculated:
//Import a sample data
newbook;
fname$ = system.path.program$ + "Samples\Mathematics\Sine Curve.dat";
impasc;

//Calculate the absolute area of the curve and plot the integral curve
integ1 iy:=col(2) type:=abs plot:=1;
Once the integration is performed, the results can be obtained from the integ1 tree variable:
// Dump the integ1 tree
integ1.=;
// Get a specific value
double area = integ1.area;
The X-Function also allows specifying variable names for quantities of interest, such as:
double myarea, ymax, xmax;
integ1 iy:=col(2) type:=abs plot:=1 area:=myarea y0:=ymax x0:=xmax;
type "area=$(myarea) %(CRLF)ymax=$(ymax) %(CRLF)xmax=$(xmax)";
Integration of two-dimensional data in a matrix can also be performed using the integ2 X-Function.
This X-Function computes the volume beneath the surface defined by the matrix, with respect to the
z=0 plane.
// Perform volume integration of 1st matrix object in first matrix sheet
range rmat=[MBook1]1!1;
integ2 im:=rmat integral:=myresult;
type "Volume integration result: $(myresult)";

13.2.5 Interpolation
Interpolation is one of the more common mathematical functions performed on data, and Origin
supports interpolation in two ways: (1) interpolation of single values and datasets through range
notation and (2) interpolation of entire curves by X-Functions.

219
 LabTalk Scripting Guide

13.2.5.1 Using XY Range

An XY Range (subrange specified by X values is available) once declared can be used as a function.
The argument to this function can be a scalar - which returns a scalar - or a vector - which returns a
vector. In either case, the X dataset should be increasing or decreasing. For example:
newbook;
wks.ncols = 4;
col(1) = data(1,0,-.05);
col(2) = gauss(col(1),0,.5,.2,100);
range rxy = (1,2);
rxy(.67)=;
range newx = 3; // Use column as X column data
newx = {0, 0.3333, 0.6667, 1.0}; // Create our new X data
range newy = 4; // This is the empty column we will interpolate into
newy = rxy(newx);
You can then use such range variables as a function with the following form:
XYRangeVariable(RangeVariableOrScalar[,connect[,param]])
where connect is one of the following options:
line
straight line connection
spline
spline connection
bspline
b-spline connection
and param is smoothing parameter, which applies only to bspline connection method. If param=-1,
then a simple bspline is used, which will give same result as bspline line connection type in line plots.
If 'param >=0, the NAG nag_1d_spline_function is used.
Notes: When using XY range interpolation, you should guarantee there are no duplicated x values if
you specify spline or bspline as the connection method. Instead, you can use interpolation X-
Functions.

From Worksheet Data

The following examples show how to perform interpolation using range as function, with data from a
worksheet as the argument.
Example1: The following code illustrates the usage of the various smoothing parameters for bspline:
col(1)=data(1,9); // Fill column 1 with row data
col(2)=normal(9); // Fill column 2 with random values
col(3)=data(1,9,0.01); // Fill Col(3) with desired X values
wks.col3.type = 4;
range bb=(1,2); // Declare range using cols 1,2;
// Compute interpolated values using different parameter settings
loop(i, 4, 10) {
wcol(i)=bb(col(3), bspline, $(i*0.1));
}
Example2: With an XY range, new Y values can be obtained at any X value using code such as:
// Generate some data
newbook;
wcol(1)={1, 2, 3, 4};
wcol(2)={2, 3, 5, 6};
// Define XYrange
range rr =(1,2);
// Find Y value by linear interpolation at a specified X value.
rr(1.23) = ; // ANS: rr(1.23)=2.23

220
 Analysis and Applications

// Find Y value by linear interpolation for an array of X values.

wcol(3)={1.5, 2.5, 3.5};
range rNewX = col(3);
// Add new column to hold the calculated Y values
wks.addcol();
wcol(4) = rr(rNewX);
Example3: To find X values given Y values, simply reverse the arguments in the examples above. In
the case of finding X given Y, the Y dataset should be increasing or decreasing.
// Generate some data
newbook;
wcol(1)={1, 2, 3, 4};
wcol(2)={2, 3, 5, 6};
// Define XYrange
range rr =(2,1); //swapping the X and Y
// Find X value by linear interpolation at a specified Y value.
rr(2.23) = ; // ANS: rr(2.23)=1.23;
// Add new column to hold the calculated X values
wks.addcol();
range rNewX = wcol(3);
// Find X value by linear interpolation for an array of Y values:
wcol(4)={2.5, 3.5, 5.5};
range rNewY = wcol(4);
rNewX = rr(rNewY);

From Graph

You can also use range interpolation when a graph page is active.
Example 1: Interpolate an array of values.
// Define range on active plot:
range rg = %C;
// Interpolate for a scalar value using the line connection style:
rg(3.54)=;
// Interpolate for an array of values:
// Give the location of the new X values:
range newX = [Book2]1!1;
// Give the location where the new Y values (output) should go:
range newY = [Book2]1!2;
// Compute the new Y values:
newY = rg(newX);
Example 2: Specify the interpolation method.
// Define range on specific plot:
range -wx rWx = 2; // Use X of 2nd plot in active layer
range -w rWy = 2; // Use Y of 2nd plot in active layer
range rr = (rWx,rWy); // Construct an XY range from two ranges
// Give the location where the new X values (output) should go:
range newX = [Book2]1!1;
newX = {5,15,25};
range newY1 = [Book2]1!2; // Range for new Y
range newY2 = [Book2]1!3; // Range for new Y
// Find new Y values by linear interpolation for an array of X values:
newY1 = rr(newX);
// Find new Y values by bspline interpolation for an array of X values:
newY2 = rr(newX,bspline);

13.2.5.2 Using Arbitrary Dataset

221
 LabTalk Scripting Guide

For two arbitrary datasets with the same length, where both are increasing or decreasing, Origin
allows you to interpolate from one dataset to the other at a given value. The datasets can be a range
variable, dataset variable, or column. The form to perform such interpolation is:
dataset1(value, dataset2)
which will perform interpolation on the group of XY data constructed by dataset2 and dataset1, and it
will return the so-called Y (dataset1) value at the given so-called X (dataset2) value. For example:
// Using datasets
dataset ds1 = {1, 2, 3, 4};
dataset ds2 = {2, 3, 5, 6};
// Return interpolated value in ds2 where X in ds1 is 1.23
ds2(1.23, ds1) = ; // Return 2.23
// Return interpolated value in ds1 where X in ds2 is 5.28
ds1(5.28, ds2) = ; // Return 3.28

// Using ranges
newbook;
wks.ncols = 3;
range r1 = 2; // Column 2 in active worksheet
r1 = {1, 2, 3, 4};
range r2 = 3; // Column 3 in active worksheet;
r2 = {2, 3, 5, 6};
r2(1.23, r1) = ;
r1(5.28, r2) = ;

// Using columns
col(3)(1.23, col(2)) = ;
col(2)(5.28, col(3)) = ;

13.2.5.3 Creating Interpolated Curves

X-Functions for Interpolation of Curves

Origin provides three X-Functions for interpolating XY data and creating a new output XY data pair:
Name Brief Description

interp1xy Perform interpolation of XY data and generate output at uniformly spaced X

Perform interpolation of XY data and generate output at a given set of X

interp1
values

interp1trace Perform interpolation of XY data that is not monotonic in X

Using Existing X Dataset

The following example shows how to use an existing X dataset to find interpolated Y values:
// Create a new workbook with specific column designations
newbook sheet:=0;
newsheet cols:=4 xy:="XYXY";
// Import a sample data file
fname$ = system.path.program$ + "Samples\Mathematics\Interpolation.dat";
impasc;

222
 Analysis and Applications

// Interpolate the data in col(1) and col(2) with the X values in col(3)
range rResult=col(4);
interp1 ix:=col(3) iy:=(col(1), col(2)) method:=linear ox:=rResult;

//Plot the original data and the result

plotxy iy:=col(2) plot:=202 color:=1;
plotxy iy:=rResult plot:=202 color:=2 size:=5 ogl:=1;

Uniformly Spaced X Output

The following example performs interpolation by generating uniformly spaced X output:

//Create a new workbook and import a data file
fname$ = system.path.program$ + "Samples\Mathematics\Sine Curve.dat";
newbook;
impasc;

//Interpolate the data in column 2

interp1xy iy:=col(2) method:=bspline npts:=50;
range rResult = col(3);

//Plot the original data and the result

plotxy iy:=col(2) plot:=202 color:=1;
plotxy iy:=rResult plot:=202 color:=2 size:=5 ogl:=1;

Interpolating Non-Monotonic Data

The following example performs trace interpolation on data where X is not monotonic:
//Create a new workbook and import the data file
fname$ = system.path.program$ + "Samples\Mathematics\circle.dat";
newbook;
impasc;

//Interpolate the circular data in column 2 with trace interpolation

interp1trace iy:=Col(2) method:=bspline;
range rResult= col(4);

//Plot the original data and the result

plotxy iy:=col(2) plot:=202 color:=1;
plotxy iy:=rResult plot:=202 color:=2 size:=1 ogl:=1;
Note that the interpolation X-Functions can also be used for extrapolating Y values outside of the X
range of the input data.

13.2.5.4 Matrix Interpolation

The minterp2 X-Function can be used to perform interpolation/extrapolation of matrices.
// Create a new matrix book and import sample data;
newbook mat:=1;
filepath$ = "Samples\Matrix Conversion and Gridding\Direct.dat";
string fname$=system.path.program$ + filepath$;
impasc;
// Interpolate to a matrix with 10 times the x and y size of the original
range rin = 1; // point to matrix with input data;
int nx, ny;
nx = rin.ncols * 10;
ny = rin.nrows * 10;

223
 LabTalk Scripting Guide

minterp2 method:=bicubic cols:=nx rows:=ny ;

OriginPro also offers the interp3 X-Function which can be used to perform interpolation on 4-
dimensional scatter data.

13.3 Statistics
13.3.1 Statistics
This is an example-based section demonstrating support for several types of statistical tests
implemented in script through X-Function calls.

Topics covered in this section:

 Descriptive statistics

 Hypothesis Testing

 Nonparametric Tests

 Survival Analysis

13.3.2 Descriptive statistics

Origin provides several X-Functions to compute descriptive statistics, some of the most common are:
Name Brief Description

colstats Columnwise statistics

corrcoef
Correlation Coefficient
(Pro Only)

freqcounts Frequency counts of a data set.

mstats
Compute descriptive statistics on a matrix
(Pro Only)

rowstats Statistics of a row of data

stats Treat selected columns as a complete dataset; compute statistics of the dataset.
For a full description of each of these X-Functions and its inputs and outputs, please see the
Descriptive Statistics.

13.3.2.1 Descriptive Statistics on Columns and Rows

224
 Analysis and Applications

The colstats X-Function can perform statistics on columns. By default, it outputs the mean, the
standard deviation, the number of data points and the median of each input column. But you can
customize the output by assigning different values to the variables. In the following example, colstats
is used to calculate the means, the standard deviations, the standard errors of the means, and the
medians of four columns.
//Import a sample data with four columns
newbook;
fname$ = system.path.program$ + "Samples\Statistics\nitrogen_raw.txt";
impasc;

//Perform statistics on column 1 to 4

colstats irng:=1:4 sem:=<new> n:=<none>;
The rowstats X-Function can be used in a similar way. The following example calculates the means
of the active worksheet; the results are placed in a new added column at the first of the worksheet.
Note: mean and sd are defaulted to be <new> in output, if not needed, set to <none>.
newbook;
fname$ = system.path.program$ + "Samples\Statistics\engine.txt";
impasc; //Import a sample data

wunstackcol irng1:=1 irng2:=2; //Unstack columns

wtranspose type:=all ow:=<new>; //Transpose worksheet
range rr1 = 1:2;
delete rr1;
range rr2 = 2;
delete rr2; //delete empty columns
int nn = wks.ncols;
wks.addcol();
wks.col$(nn+1).lname$ = Mean;
wks.col$(nn+1).index = 2; //Add mean column
wks.addcol();
wks.col$(nn+2).lname$ = Sum;
wks.col$(nn+2).index = 3; //Add sum column

//Row statistics to get sum and average, saved to corresponding column.

rowstats irng:=4[1]:end[end] sum:=3 mean:=2 sd:=<none>;

13.3.2.2 Frequency Count

If you want to calculate the frequency counts of a range of data, use the freqcounts X-Function.
//Open a sample workbook
%a = system.path.program$ + "Samples\Statistics\Body.ogw";
doc -a %a;

//Count the frequency of the data in column 4

freqcounts irng:=4 min:=35 max:=75 stepby:=increment intervals:=5;

13.3.2.3 Correlation Coefficient

corrcoef X-Function can be used to compute the correlation coefficient between two datasets.
//import a sample data
newbook;
fname$ = system.path.program$ + "Samples\Statistics\automobile.dat";
impasc;

//Correlation Coefficient

225
 LabTalk Scripting Guide

corrcoef irng:= (col(c):col(g)) rt:= <new name:=corr>

13.3.3 Hypothesis Testing

Origin/OriginPro supports the following set of X-Functions for hypothesis testing:
Name Brief Description

rowttest2 (Pro
Perform a two-sample t-test on rows.
Only)

ttest1 Compare the sample mean to the hypothesized population mean.

ttest2 Compare the sample means of two samples.

Determine whether two sample means are equal in the case that they are
ttestpair
matched.

vartest1
Determine whether the sample variance is equal to a specified value.
(Pro Only)

vartest2
Determine whether two sample variances are equal.
(Pro Only)
For a full description of these X-functions, including input and output arguments, please see the
Hypothesis Testing.

13.3.3.1 One-Sample T-Test

If you need to know whether the mean value of a sample is consistent with a hypothetical value for a
given confidence level, consider using the one-sample T-test. Note that this test assumes that the
sample is a normally distributed population. Before we apply the one-sample T-test, we should verify
this assumption.
//Import a sample data
newbook;
fname$ = system.path.program$ + "Samples\Statistics\diameter.dat";
impasc;

//Normality test
swtest irng:=col(a) prob:=p1;
if (p1 < 0.05)
{
type "The sample is not likely to follow a normal distribution."
}
else
{
// Test whether the mean is 21
ttest1 irng:=col(1) mean:=21 tail:=two prob:=p2;
if (p2 < 0.05) {
type "At the 0.05 level, the population mean is";
type "significantly different from 21."; }
else {
type "At the 0.05 level, the population mean is NOT";
type "significantly different from 21."; }
}

226
 Analysis and Applications

13.3.3.2 Two-Sample T-Test

The ttest2 X-Function is provided for performing two-sample t-test. The example below shows how
to use it and print the results.
// Import sample data
newbook;
string fpath$ = "Samples\Statistics\time_raw.dat";
string fname$ = system.path.program$ + fpath$;
impAsc;

// Perform two-sample t-test on two columns

// Sample variance is not assumed to be equal
ttest2 irng:=(col(1), col(2)) equal:=0;

// Type some results

type "Value of t-test statistic is $(ttest2.stat)";
type "Degree of freedom is $(ttest2.df)";
type "P-value is $(ttest2.prob)";
type "Conf. levels in 95% is ($(ttest2.lcl), $(ttest2.ucl))";
The rowttest2 X-Function can be used to perform a two-sample T-test on rows. The following
example demonstrates how to compute the corresponding probability value for each row:
// Import sample data
newbook;
string fpath$ = "Samples\Statistics\ANOVA\Two-Way_ANOVA_raw.dat";
fname$ = system.path.program$ + fpath$;
impasc;

// Two-sample T-test on a row

rowttest2 irng1:=(col(a):col(c)) irng2:=(col(d):col(f))
tail:=two prob:=<new>;

13.3.3.3 Pair-Sample T-Test

Origin provides the ttestpair X-Function for pair-sample t-test analysis, so to determine whether the
means of two same-sized and dependent samples from a normal distribution are equal or not, and
calculates the confidence interval for the difference between the means. The example below first
imports a data file, and then perform pair-sample t-test, and then output the related results.
// Import sample data
newbook;
string fpath$ = "Samples\Statistics\abrasion_raw.dat";
string fname$ = system.path.program$ + fpath$;
impasc;

// Perform pair-sample t-test one two columns

// Hypothetical means difference is 0.5
// And Tail is upper tailed
ttestpair irng:=(col(1), col(2)) mdiff:=0.5 tail:=upper;

// Type the results

type "Value of paired-sample t-test statistic is $(ttestpair.stat)";
type "Degree of freedom for the paired-sample t-test is $(ttestpair.df)";
type "P-value is $(ttestpair.prob)";
type "Conf. levels in 95% is ($(ttestpair.lcl), $(ttestpair.ucl))";

13.3.3.4 One-Sample Test for Variance

227
 LabTalk Scripting Guide

X-Function vartest1 is used to perform a chi-squared variance test, so to determine whether the
sample from a normal distribution could have a given hypothetical vaiance value. The following
example will perform one-sample test for variance, and output the P-value.
// Import sample data
newbook;
string fpath$ = "Samples\Statistics\vartest1.dat";
string fname$ = system.path.program$ + fpath$;
impasc;

// Perform F-test
// Tail is two tailed
// Test variance is 2.0
// P-value stored in variable p
vartest1 irng:=col(1) var:=2.0 tail:=two prob:=p;

// Ouput P-value
p = ;

13.3.3.5 Two-Sample Test for Variance (F-Test)

F-test, also called two-sample test for variance, is performed by using vartest2 X-Function.
// Import sample data
newbook;
string fpath$ = "Samples\Statistics\time_raw.dat";
string fname$ = system.path.program$ + fpath$;
impasc;

// Perform F-test
// And Tail is upper tailed
vartest2 irng:=(col(1), col(2)) tail:=upper;

// Output the result tree

vartest2.=;

13.3.4 Nonparametric Tests

Hypothesis tests are parametric tests when they assume the population follows some specific
distribution (such as normal) with a set of parameters. If you don't know whether your data follows
normal distribution or you have confirmed that your data do not follow normal distribution, you should
use nonparametric tests.
Origin provides support for the following X-Functions for non-parametric analysis, they are available
in OriginPro
Name Brief Description

Test whether the location (median) of a population distribution is the

signrank1
same with a specified value

Test whether or not the medians of the paired populations are equal.
signrank2/sign2
Input data should be in raw format.

Test whether the two samples have identical distribution. Input data
mwtest/kstest2
should be Indexed.

kwanova/mediantest Test whether different samples' medians are equal, Input data should be

228
 Analysis and Applications

arranged in index mode.

Compares three or more paired groups. Input data should be arranged

friedman
in index.
As an example, we want to compare the height of boys and girls in high school.
//import a sample data
newbook;
fname$ = system.path.program$ + "Samples\Statistics\body.dat";
impasc;

//Mann-Whitney Test for Two Sample

//output result to a new sheet named mynw
mwtest irng:=(col(c), col(d)) tail:=two rt:=<new name:=mynw>;

//get result from output result sheet

page.active$="mynw";

getresults tr:=mynw;

//Use the result to draw conclusion

if (mynw.Stats.Stats.C3 <= 0.05); //if probability is less than 0.05
{
type "At 0.05 level, height of boys and girls are differnt.";
//if median of girls height is larger than median of boy's height
if (mynw.DescStats.R1.Median >= mynw.DescStats.R2.Median)
type "girls are taller than boys.";
else
type "boys are taller than girls."
}
else
{
type "The girls are as tall as the boys."
}

13.3.5 Survival Analysis

Survival Analysis is widely used in the biosciences to quantify survivorship in a population under
study. Origin supports three widely used tests, they are available in OriginPro:
Name Brief Description

kaplanmeier Kaplan-Meier (product-limit) Estimator

phm_cox Cox Proportional Hazards Model

weibullfit Weibull Fit

For a full description of these X-functions, including input and output arguments, please see the
Survival Analysis.

13.3.5.1 Kaplan-Meier Estimator

If you want to estimate the survival ratio, create survival plots and compare the quality of survival
functions, use the kaplanmeier X-Function. It uses product-limit method to estimate the survival

229
 LabTalk Scripting Guide

function, and supports three methods for testing the equality of the survival function: Log Rank,
Breslow and Tarone-Ware.
As an example, scientists are looking for a better medicine for cancer resistance. After exposing
some rats to carcinogen DMBA, they apply different medicine to two different groups of rats and
record their survival status for the first 60 hours. They wish to quantify the difference in survival rates
between the two medicines.
// Import sample data
newbook;
fname$ = system.path.program$ + "Samples\Statistics\SurvivedRats.dat";
impasc;

//Perform Kaplan-Meier Analysis

kaplanmeier irng:=(1,2,3) censor:=0 logrank:=1
rd:=<new name:="sf">
rt:=<new name:="km">;

//Get result from survival report tree

getresults tr:=mykm iw:="km";

if (mykm.comp.logrank.prob <= 0.05)

{
type "The two medicines have significantly different"
type "effects on survival at the 0.05 level ...";
type "Please see the survival plot.";

//Plot survival Function

page.active$="sf";
plotxy iy:=(?, 1:end) plot:=200 o:=[<new template:=survivalsf>];

}
else
{
type "The two medicines are not significantly different.";
}

13.3.5.2 Cox Proportional Hazard Regression

The phm_cox X-Function can be used to obtain the parameter estimates and other statistics
associated with the Cox Proportional hazards model for fixed covariates. It can then forecast the
change in the hazard rate along with several fixed covariates.
For example, we want to study on 66 patients with colorectal carcinoma to determine the effective
prognostic parameter and the best prognostic index (a prognostic parameter is a parameter that
determines whether a person has a certain illness). This script implements the phm_cox X-Function
to get the relevant statistics.
//import a sample data
newbook;
string fpath$ = "Samples\Statistics\ColorectalCarcinoma.dat";
fname$ = system.path.program$ + fpath$;
impasc option.hdr.LNames:=1
option.hdr.units:=0
option.hdr.CommsFrom:=2
option.hdr.CommsTo:=2;

//Perform Cox Regression

phm_Cox irng:=(col(1),col(2),col(3):end) censor:=0 rt:=<new name:="cox">;

230
 Analysis and Applications

//Get result from report tree

page.active$="cox";
getresults tr:=cox;

type "Prognostic parameters determining colorectal carcinoma are:";

page.active$="ColorectalCarcinoma";
loop(ii, 1, 7)
{
// If probability is less than 0.05,
// we can say it is effective for survival time.
if (cox.paramestim.param$(ii).prob<=0.05)
type wks.col$(ii+2).comment$;
}

13.3.5.3 Weibull Fit

If it is known apriori that data are Weibull distributed, use the weibullfit X-Function to estimate the
weibull parameters.
//import a sample data
newbook;
fname$ = system.path.program$ + "Samples\Statistics\Weibull Fit.dat ";
impasc;

//Perform Weibull Fit

weibullfit irng:=(col(a), col(b)) censor:=1;

13.4 Curve Fitting

13.4.1 Curve Fitting
The curve fitting features in Origin are some of the most popular and widely used. Many users do not
realize that the X-Functions performing the fitting calculations can be used just as easily from script
as they can from Origin's graphical user interfaces. The following sections address curve fitting using
LabTalk Script.

Topics covered in this section:

 Linear, Polynomial and Multiple Regression

 Non-linear Fitting

13.4.2 Linear, Polynomial and Multiple Regression

In LabTalk scripts, three simple quick use X-Functions, fitLR, fitPoly, and fitMR, are available for
performing linear regression, polynomial regression, and multiple linear regression, respectively. And
the -h switch can be used to see the argument list.

231
 LabTalk Scripting Guide

13.4.2.1 Linear Regression

fitLR finds a best fit straight line to a given dataset.
newbook; // create a new book

// file name
string strFile$ = system.path.program$ + "Samples\Curve Fitting\Linear
Fit.dat";
impasc fname:=strFile$; // import the data

wks.addcol(FitData); // add a column for fitted data, named FitData

// perform linear fit on the first ten points of column 1 (X) and column 2
(Y)
// and the fitted data is output to FitData column
fitLR iy:=(1,2) N:=10 oy:=col(FitData);
// a tree object named fitLR is created, and contains the output values
fitLR.a = ; // output the fitted intercept
fitLR.b = ; // output the fitted slope
fitLR.= ; // output all the results, which include fitted intercept and
slope
More examples about linear regression can be found in Curve Fitting sample page, or under Fitting
category in XF Script Dialog (press F11 to open).

13.4.2.2 Polynomial Regression

Polynomial fitting is a special case wherein the fitting function is mathematically non-linear, but an
analytical (non-iterative) solution is obtained. In LabTalk, fitPoly is used to control polynomial fitting.
newbook; // create a new book;

// file name
string strFile$ = system.path.program$ + "Samples\Curve Fitting\Polynomial
Fit.dat";
impasc fname:=strFile$; // import data
wks.addcol(PolyCoef); // add a new column for polynomial coefficients
wks.addcol(FittedX); // add a new column for fitted X values
wks.addcol(FittedY); // add a new column for fitted Y values

// perform polynomial fitting on column 1 (X) and column 3 (Y)

// polynomial order is 3
fitPoly iy:=(1,3) polyorder:=3 coef:=col(PolyCoef)
oy:=(col(FittedX),col(FittedY));

// the results are stored in the tree named fitPoly, output it

fitPoly.= ;
Additionally, fitPoly provides the outputs for adjusted residual sum of squares, coefficient of
determination, and errors in polynomial coefficients. For more detailed examples, please refer to
Curve Fitting sample page, or Fitting category in XF Script Dialog (press F11 to open).

13.4.2.3 Multiple Linear Regression

Multiple linear regression studies the relationship between several predictor variables and a response
variable, which is an extension of simple linear regression.
// create a new book and import some data
newbook;

232
 Analysis and Applications

fn$ = system.path.program$ + "Samples\Curve Fitting\Multiple Linear

Regression.dat";
impasc fn$;
wks.addcol(FitValue); // add a column for fitted values of dependent

// perform multiple linear regression

// column D is dependent, and column A, B, and C are independents
// the output results are stored in a tree, tr
fitMR dep:=col(D) indep:=col(A):col(C) mrtree:=tr odep:=col(FitValue);
tr.= ; // output the result tree
For more examples, please refer to Curve Fitting sample page, or Fitting category in XF Script
Dialog (press F11 to open).

13.4.2.4 Run Operation Classes to Perform Regression

The X-Functions depicted above are for simple quick use only to perform linear, polynomial and
multiple regression. That is to say, some quantities are not available when using these three X-
Functions. For full access to all quantities, the X-Function xop is provided to invoke the internal menu
commands (operation commands), so to run the corresponding operation classes to perform
regression. The following example shows how to use the X-Function xop to perform linear fit, and
generate a report.
// create a new book and import data
newbook;
fname$ = system.path.program$ + "Samples\Curve Fitting\Linear Fit.dat";
impasc fname$;

tree lrGUI; // GUI tree for linear fit

// initialize the GUI tree, with the FitLinear class
xop execute:=init classname:=FitLinear iotrgui:=lrGUI;

// specify the input data in the GUI tree

lrGUI.GUI.InputData.Range1.X$ = col(A);
lrGUI.GUI.InputData.Range1.Y$ = col(C);

// perform linear fit and generate a report with the prepared GUI tree
xop execute:=report iotrgui:=lrGUI;

xop execute:=cleanup; // clean up linear fit operation objects after fitting

13.4.3 Non-linear Fitting

Non-linear fitting in LabTalk is X-function based and proceeds in three steps, each calling (at least)
one X-function:
1. nlbegin: Begin the fitting process. Define input data, type of fitting function, and input

parameters.

2. nlfit: Perform the fit calculations

3. nlend Choose which parameters to output and in what format

Besides nlbegin, you can also start a fitting process according to your fitting model or data by the
following X-Functions:
 nlbeginr: Fitting multiple dependnet/independent variables' model

233
 LabTalk Scripting Guide

 nlbeginm: Fitting a matrix

 nlbeginz: Fitting XYZ worksheet data

13.4.3.1 Script Example

Here is a script example of the steps outlined above:
// Begin non-linear fitting, taking input data from Column 1 (X) and
// Column 2 (Y) of the active worksheet,
// specifying the fitting function as Gaussian,
// and creating the input parameter tree named ParamTree:
nlbegin iy:=(1,2) func:=gauss nltree:=ParamTree;
// Optional: let the peak center be fixed at X = 5
ParamTree.xc = 5; // Assign the peak center an X-value of 5.
ParamTree.f_xc = 1; // Fix the peak center (f_xc = 0 is unfixed).
// Perform the fit calculations:
nlfit;
// Optional: report results to the Script Window.
type Baseline y0 is $(ParamTree.y0),;
type Peak Center is $(ParamTree.xc), and;
type Peak width (FWHM) is $(ParamTree.w);
// end the fitting session without a Report Sheet
nlend;

13.4.3.2 Notes on the Parameter Tree

The data tree that stores the fit parameters has many options besides the few mentioned in the
example above. The following script command allows you to see all of the tree nodes (names and
values) at one time, displaying them in the Script Window.
// To see the entire tree structure with values:
ParamTree.=;
Note: since the non-linear fitting procedure is iterative, parameter values for the fit that are not fixed
(by setting the fix option to zero in the parameter tree) can and will change from their initial values.
Initial parameters can be set manually, as illustrated in the example above by accessing individual
nodes of the parameter tree, or can be set automatically by Origin (see the nlfn X-function in the
table below).

13.4.3.3 Table of X-functions Supporting Non-Linear Fitting

In addition to the three given above, there are a few other X-functions that facilitate non-linear fitting.
The following table summarizes the X-functions used to control non-linear fitting:
Name Brief Description

Start a LabTalk nlfit session on XY data from worksheet or graph.

Note:
nlbegin
This X-Function fits one independent/dependent model only. For multiple
dependent/independent functions, use nlbeginr instead.

Start a LabTalk nlfit session on worksheet data. It is used for fitting multiple
nlbeginr
dependent/independent variables functions.

nlbeginm Start a LabTalk nlfit session on matrix data from matrix object or graph

234
 Analysis and Applications

nlbeginz Start a LabTalk nlfit session on XYZ data from worksheet or graph

nlfn Set Automatic Parameter Initialization option

nlpara Open the Parameter dialog for GUI editing of parameter values and bounds

nlfit Perform iterations to fit the data

nlend End the fitting session and optionally create a report

For a full description of each of these X-functions and its inputs and outputs, please see the X-
function Reference.

13.4.3.4 Qualitative Differences from Linear Fitting

Unlike linear fitting, a non-linear fit involves solving equations to which there is no analytical solution,
thus requiring an iterative approach. But the idea---calling X-functions to perform the analysis---is the
same. Whereas a linear fit can be performed in just one line of script with just one X-function call (see
the Linear Fitting section), a non-linear fit requires calling at least three X-functions.

13.5 Signal Processing

Origin provides a collection of X-functions and LabTalk functions for signal processing, ranging from
smoothing noisy data to Fourier Transform (FFT), Inverse Fourier Transform (IFFT), Short-time FFT,
Convolution and Correlation, FFT Filtering, and Wavelet analysis.
The X-Functions are available under the Signal Processing category and can be listed by typing the
following command:
lx cat:="signal processing*";
Some functionality such as Short-time FFT and Wavelets are only available in OriginPro.
The LabTalk functions for signal processing are available under Signal Processing Functions, which
are used to separately compute FFT results such as amplitude, phase, etc., for multiple datasets and
arrange their results in desired columns. Meanwhile, one can utilize these functions to compare DC
offset removed magnitudes among different datasets.
The following sections provide some short examples of calling the signal processing X-Functions and
LabTalk functions from script.

13.5.1 Smoothing
Smoothing noisy data can be performed by using the smooth X-Function.
// Smooth the XY data in columns 1,2 of the worksheet
// using SavitzkyGolay method with a third order polynomial
range r=(1,2); // assume worksheet active with XY data
smooth iy:=r meth:=sg poly:=3;
To smooth all plots in a layer, you can loop over the plots as below:
// Count the number of data plots in the layer and save result in
//variable "count"
layer -c;
// Get the name of this Graph page
string gname$ = %H;
// Create a new book named smooth - actual name is stored in bkname$

235
 LabTalk Scripting Guide

newbook na:=Smoothed;
// Start with no columns
wks.ncols=0;
loop(ii,1,count) {
// Input Range refers to 'ii'th plot
range riy = [gname$]!$(ii);
// Output Range refers to two, new columns
range roy = [bkname$]!($(ii*2-1),$(ii*2));
// Savitsky-Golay smoothing using third order polynomial
smooth iy:=riy meth:=sg poly:=3 oy:=roy;
}

13.5.2 FFT and IFFT

The following example shows how to individually obtain the FFT results by LabTalk functions listed
under Signal Processing Functions.
newbook;
// Import the signal data
string fname$ = system.path.program$ + "Samples\Signal
Processing\fftfilter1.DAT";
impASC fname:=fname$;

// Add 5 columns to store different quantities

worksheet -a 5;
// Set column label to distinguish
col(B)[L]$ = "Raw Signal";

// Set data type to complex prior to store complex results from FFT analysis
wks.col3.numerictype = 11;
col(C)[L]$ = "FFT Complex";

// Calculate FFT complex results

col(C) = fftc(col(B)); //with no shift

col(D)[L]$ = "Frequency";
wks.col4.type = 4; //Set X column type

// Compute the frequencies based on time data in column A

col(D) = fftfreq(col(A)[2]-col(A)[1], wks.col1.nrows);

col(E)[L]$ = "Magnitude";

// Get FFT magnitude results

col(E) = fftmag(col(C)); // Use fftmag(col(C), 2) to obtain Two-Sided and
Shifted magnitude

col(F)[L]$ = "Phase";
col(F) = fftphase(col(C)); // Use fftphase(col(C), 2, 1, 0) to obtain Two-
sided, unwrapped phase with radian unit

wks.col7.numerictype = 11;
col(G)[L]$ = "Shifted FFT Complex";
col(G) = fftshift(col(C));

// Update sparklines for calculated results

sparklines sel:=0 c1:=4 c2:=6;

236
 Analysis and Applications

// Auto adjust column width to fit content

wautosize;
The following example shows how to obtain the IFFT result from shifted FFT complex result.
//Continue from the example above, suppose we have shifted FFT results in
column G
// Add 2 more columns to store different quantities
worksheet -a 2;
// Label columns to distinguish
col(H)[L]$ = "Unshifted FFT Complex";
// Set the data type to be complex
wks.col8.numerictype = 11;
// Unshift the shifted FFT results before doing IFFT
col(H) = ifftshift(col(G));

col(I)[L]$ = "IFFT result";

wks.col9.numerictype = 11;
// Compute inverse FFT from unshifted FFT results
col(I) = invfft( col(H) );
The following example shows how to specify a window in FFT analysis.
newbook;
// Import the signal data
string fname$ = system.path.program$ + "Samples\Signal Processing\Chirp
Signal.dat.";
impASC fname:=fname$;

// Define a range variable for input signal

range rSignal = col(B);
int wSize = rSignal.nrows;

col(C)[L]$ = "Apply Blackman window";

col(C) = col(B) * windata(6, wSize); // Apply Blackman window

col(D)[L]$ = "Amplitude";
col(D) = fftamp( fftc(col(C)) ); //Without Origin window correction
The following example shows how to perform fft analysis on multiple columns using loop and arrange
obtained amplitude and phase columns side by side. You can also calculate FFT results for multiple
columns directly on worksheet by selecting multiple columns on the worksheet, and right click to
select Set Multiple Columns Values....
//Prepare multiple column data for FFT analysis
newbook;
int nc = 5, ii;
wks.ncols = 4*nc+2;
//Fill x column with time data
col(A) = data(0, 1-1e-3, 1e-3);
//Fill five columns with sum of an f1 Hz sinusoid and an f2 Hz sinusoid
for( ii = 1; ii<=nc; ii++ )
{
double f1, f2;
f1 = 50 + 20*ii;
f2 = 100 + 20*ii;
wcol(ii+1)[L]$ = "Data$(ii)";
wcol(ii+1) = (2+ii)*sin(2*pi*f1*col(A))+(8-ii)*sin(2*pi*f2*col(A))+rnd();
}

//Subtract mean before FFT to remove DC offset

237
 LabTalk Scripting Guide

for( ii = 1; ii<=nc; ii++ )

{
wcol(nc+ii+1)[C]$ = "Subtract mean of Data$(ii)";
wcol(nc+ii+1) = wcol(ii+1)-mean( wcol(ii+1) );
}

//Calculate frequency for FFT results

wks.col$(2*nc+2).type = 4; //Set X column type
wcol(2*nc+2)[L]$ = "Frequency";
wcol(2*nc+2) = fftfreq( col(A)[2]-col(A)[1], wks.col1.nrows );

//Calculate FFT amplitude and phase for five columns

for( ii = 1; ii<=nc; ii++ )
{
//FFT amplitude result
wcol(2*nc+ii+2)[L]$ = "Amplitude";
wcol(2*nc+ii+2)[C]$ = "Data$(ii)";
wcol(2*nc+ii+2) = fftamp( fftc( wcol(nc+ii+1) ) );

//FFT phase result

wcol(3*nc+ii+2)[L]$ = "Phase";
wcol(3*nc+ii+2)[C]$ = "Data$(ii)";
wcol(3*nc+ii+2) = fftphase( fftc( wcol(nc+ii+1) ) );
}

//Plot FFT amplitude and phase results for five columns in two layers
plotstack iy:=($(2*nc+2),$(2*nc+3):$(4*nc+2)) portrait:=0 order:=0 layer:=2
number:="5 5";

13.5.3 FFT and Filtering

The following example shows how to perform 1D FFT of data using the fft1 X-Function.
// Import a sample file
newbook;
fname$ = system.path.program$ + "Samples\Signal Processing\fftfilter1.dat";
impasc;
// Perform FFT and get output into a named tree
Tree myfft;
fft1 ix:=2 rd:=myfft rt:=<none>;
// You can list all trees using the command: list vt
Once you have results in a tree, you can do further analysis on the output such as:
// Copy desired tree vector nodes to datasets
// Locate the peak and mean frequency components
dataset tmp_x=myfft.fft.freq;
dataset tmp_y=myfft.fft.amp;
// Perform stats and output results
percentile = {0:10:100};
diststats iy:=(tmp_x, tmp_y) percent:=percentile;
type "The mean frequency is $(diststats.mean)";
The following example shows how to perform signal filtering using the fft_filters X-Function:
// Import some data with noise and create graph
newbook;
string filepath$ = "Samples\Signal Processing\";

238
 Analysis and Applications

string filename$ = "Signal with High Frequency Noise.dat";

fname$ = system.path.program$ + filepath$ + filename$;
impasc;
plotxy iy:=(1,2) plot:=line;

// Perform low pass filtering

fft_filters filter:=lowpass cutoff:=1.5;

13.6 Peaks and Baseline

This section deals with Origin's X-Functions that perform peak and baseline calculations, especially
valuable for analyses pertaining to spectroscopy.

13.6.1 X-Functions For Peak Analysis

The following table lists the X-Functions available for peak analysis. You can obtain more information
on these functions from the X-Function Reference help file.
Name Brief Description

pa Perform peak analysis with a pre-saved Peak Analyzer theme file.

paMultiY Perform batch processing of peak analysis on multiple Y datasets

pkFind Pick peaks.

fitpeaks Fit multiple peaks.

blauto Create baseline anchor points.

interp1xy Interpolate the baseline anchor points to create baseline.

subtract_ref Subtract existing baseline dataset from source data.

smooth Smooth the input prior to performing peak analysis.

integ1 Perform integration on the selected range or peak.

For peaks that do not require baseline treatment or other advanced options, you can
also use peak functions to perform nonlinear fitting. For more information on non-
linear fitting from script, please see the Curve Fitting section.

The following sections provide examples on peak analysis.

13.6.2 Creating a Baseline

This example imports a sample data file and creates baseline anchor points using the blauto X-
Function.
newbook;

239
 LabTalk Scripting Guide

filepath$ = "Samples\Spectroscopy\Peaks on Exponential Baseline.dat";

fname$ = system.path.program$ + filepath$;
impASC;

//Create 20 baseline anchor points

range rData = (1,2), rBase =(3, 4);
blauto iy:=rData number:=20 oy:=rBase;
Plot the data and anchor points in same graph:
// plot a line graph of the data
plotxy rData 200 o:=[<new>];
// plot baseline pts to same layer as scatter
plotxy rBase 201 color:=2 o:=1!;

13.6.3 Finding Peaks

This example uses the pkFind X-Function to find peaks in XY data:
// Import sample pulse data
newbook;
fname$ = system.path.program$ + "Samples\Spectroscopy\Sample Pulses.dat";
impASC;
// Find all positive peaks above a peak height value of 0.2
range rin=(1,2);
range routx = 3, routy=4;
pkfind iy:=rin dir:=p method:=max npts:=5 filter:=h value:=0.2
ocenter:=<none> ocenter_x:=routx ocenter_y:=routy;
Now graph the data as line plot and the peak x,y as scatter:
plotxy iy:=rin plot:=200;
// Set x output column as type X and plot the Y column
routx.type = 4;
plotxy iy:=routy plot:=201 color:=2 o:=1;

13.6.4 Integrating and Fitting Peaks

X-Functions specific to the goals of directly integrating peaks, or fitting multiple peaks, do not exist.
Therefore, to perform peak fitting or integration, one must first use the Peak Analyzer dialog to
create and save a theme file. Once a theme file has been saved, the pa or paMultiY X-Functions can
be utilized to perform integration and peak fitting from script.

13.7 Image Processing

Origin 8 offers enhanced image processing capabilities compared with earlier versions of Origin. A
few examples of basic image processing are shown below, along with LabTalk scripts for performing
the necessary tasks.
To view a list of all X-Functions available for image processing, please type the following command:
lx cat:="image*";
Some of the X-Functions are only available in OriginPro.

13.7.1 Rotate and Make Image Compact

240
 Analysis and Applications

This example rotates, trims the margins, and applies an auto-level to make the image more compact
and clear.,

//Create a new folder in the Project Explorer

pe_mkdir RotateTrim path:=aa$;
pe_cd aa$;

//Create a matrix and import an image into it

window -t m;
string fpath$ = "samples\Image Processing and Analysis\rice.bmp";
string fname$ = System.path.program$ + fpath$;
impimage;
window -r %h Original;

//Get the dimension of the original image

matrix -pg DIM nCol1 nRow1;

window -d; //Duplicate the image

window -r %h Modified;

imgRotate angle:=42;
imgTrim t:=17;

matrix -pg DIM nCol2 nRow2; //Get the dimension of the modified iamge

imgAutoLevel;// Apply auto leveling to image

window -s T; //Tile the windows horizontally

//Report
window -n n Report;
old = type.redirection;
type.redirection = 2;
type.notes$=Report;
type "Dimension of the original image: ";
type " $(nCol1) * $(nRow1)\r\n"; // "754 * 668"
type "Dimension of the modified image: "; // "688 * 601"
type " $(nCol2) * $(nRow2)\r\n";
type.redirection = old;

241
 LabTalk Scripting Guide

We can also rotate, resize, and adjust the color scale of the image in new image window.
Minimum Origin Version Required: 2016 SR0
fname$ = SYSTEM.PATH.PROGRAM$ + "Samples\Image Processing and
Analysis\Rice.bmp";
cvopen fname:=fname$; //open the image in new image window;

cvRotate angle:=-42 interp:=0 resize:=0 trim:=1; //rotate and resize the

image
cvGray img:=<active>;
cvHistEq img:=<active>; //equalizes the histogram

13.7.2 Edge Detection

Subtract background from Cells image then detect the edges.

//Create a new folder in the Project Explorer

pe_mkdir EdgeDetection path:=aa$;
pe_cd aa$;

//Create a matrix and import the cell image into it

window -t m;
string fpath$ = "samples\Image Processing and Analysis\cell.jpg";
string fname$ = System.path.program$ + fpath$;
impimage;
cell$ = %h;

242
 Analysis and Applications

//Create a matrix and import the background image into it

window -t m;
string fpath$ = "samples\Image Processing and Analysis\bgnd.jpg";
string fname$ = System.path.program$ + fpath$;
impimage;
cellbk$ = %h;

//Subtract background and pre-processing

//x, y is the offset of Image2
imgSimpleMath img1:=cellbk$ img2:=cell$ func:=sub12 x:=7 y:=13 crop:=1;
//specify the lowest and highest intensity to be convert to binary 0 or 1.
imgBinary t1:=65 t2:=255;
// the dimensions of median filter is 18
imgMedian d:=18;

//Edge detection
// the threshold value 12 used to determine edge pixels,
// and shv(Sobel horizontal & vertical) Edge detection filter is applied.
imgEdge t:=12 f:=shv;
edge$ = %h;

//Add the edges back to the cell image

imgSimpleMath img1:=edge$ img2:=cell$ func:=add;
window -z;

13.7.3 Apply Rainbow Palette to Gray Image

This example shows how to convert a gray image to rainbow color.

pe_mkdir Conversion path:=aa$;

pe_cd aa$;

//Create a matrix and import a sample image

window -t m;
path$ = System.path.program$;

243
 LabTalk Scripting Guide

fname$ = path$ + "samples\Image Processing and Analysis\myocyte8.tif";

impimage;
window -r %h Original;

window -d; //Duplicate the image

window -r %h newimage;

imgC2gray; //Convert to gray

//Apply pallete
fname$ = System.path.program$ + "palettes\Rainbow.PAL";
imgpalette palfile:=fname$;

window -s T; //Tile the windows horizontally

Add Palettes to gray scale image in new image window

Minimum Origin Version Required: 2016 SR0
fname$ = SYSTEM.PATH.PROGRAM$ + "Samples\Image Processing and
Analysis\cell.jpg";
cvopen fname:=fname$; //open the image in new image window;

cvGray img:=<active>;
cvPalette img:=<active> fname:="C:\Program
Files\OriginLab\Origin2016\Palettes\Lite Cyan.pal";

13.7.4 Converting Image to Data

When an image is imported into a matrix object, it is kept as type Image, indicated by the icon I on
the top right corner of the window. For certain mathematical operations such as 2D FFT the type
needs to be converted to Data, which would then be indicated by the icon D at the top right corner.
This script example shows importing multiple images into a matrix book and converting them to type
data:
// Find files using wildcard
string path$=system.path.program$+"Samples\Image Processing and Analysis";
findFiles ext:="*tif*";

// Create a new matrix book and import all images as new sheets
newbook mat:=1;
impImage options.FirstMode:=0 options.Mode:=4;
// Loop over all sheets and convert image to byte data
doc -e LW {
img2m om:=<input> type:=1;
}

244
14 User Interaction

14.1 User Interaction

There may be times when you would like to provide a specific type of input to your script that would
be difficult to automate. For instance, you wish to specify a particular data point on a graph, or a
certain cell in a worksheet as input to one or more functions called from script. To do this, LabTalk
supports ways of prompting the user for input while running a script.
In general, consecutive lines of a script are executed until such a user prompt is encountered.
Execution of the script then halts until the user has entered the desired information, and then
proceeds. The following sections demonstrate several examples of programming for this type of user
interaction:

Topics covered in this section:

 Getting Numeric and String Input

 Getting Points from Graph

 Bringing Up a Dialog

14.2 Getting Numeric and String Input

This section gives examples of prompting for three types of user input during script execution:
1. Yes/No response

2. Single String

3. Multi-Type Input (GetN)

The User Interface Module (UIM) alllows users to build complex

user interface controls. See the UIM Objects page.

14.2.1 Get a Yes/No Response

The GetYesNo command can be used to get a Yes or No response from the user. The command
takes three arguments:
Syntax: getyesno stringMessageToUser numericVariableName windowTitle
For example, entering the following line in the Script Window will generate a pop-up window titled
Check Sign of X and ask the user the Yes/No question Should X be positive? with the options Yes,
No, and Cancel as clickable buttons. If Yes is selected, xpos will be assigned a value of 1. If No is

245
 LabTalk Scripting Guide

selected, xpos will be assigned the value 0. If Cancel is selected, xpos will be assigned the value 0,
#Command Error! will be printed, and script execution will stop.
getyesno "Should X be positive?" xpos "Check Sign of X"
If additional script processing is required in any event, this command should be called from elsewhere
and the numeric value can be tested. In the following example, getyesno is called from its own
section of code and the two string inputs are passed as arguments to the section(note, a multi-section
LabTalk script will not work if simply pasted to the script window; save to file and run):
[Main]
// Here is the calling code
int iVal = -1;
run.section(,myGetYesNo,"Create a Graph of results?" "Graphing Option");
if( iVal > 0 )
{
type "Graph generated"; // Yes response
}
else
{
type "Graph NOT generated"; // No or Cancel response
}

// 'myGetYesNo' section
[myGetYesNo]
getyesno (%1) iVal (%2);

14.2.2 Get a String

GetString can be used for user entry of a single string.
%B = "";
GetString (Enter as Last, First) Last (Your Name);
// Cancel stops here unless using technique as in GetYesNo
if("%B"!="Last")
{
type User entered %B.;
}
else
{
type User clicked OK, but did not modify text;
}

14.2.3 Get Multiple Values

The GetN or GetNumber dialog prompts a user for a number, a string or a list entry (in previous
versions of Origin only numeric values were possible, hence the name). Starting with Origin 8.1,
GetNumber will accept both string variables (i.e., string str1$) and string registers (i.e., %A) for string
input. Previous versions support string registers only. GetN currently accepts up to 7 variables in
addition to the dialog title.
With the increased functionality of GetN in Origin 8.1, string variables can be used in the command
call. In this case, the strings must first be declared. It is always a good practice to create variables by
declaration rather than by assignment alone; for more see Scope of (String) Variables. For example:
// First, declare the variables to be used:
double nn = 3.2;
string measurement$="length", units$="inches", event$="Experiment #2";

// Use GetN dialog to collect user data:

246
 User Interaction

getn
(Value) nn
(Measurement Type) measurement$
(Units) units$
(Event Name) event$
(Dialog Title);
brings up the following dialog, prompting the user for input:

The values entered in this dialog will be assigned to the declared variables. If the variables have an
initial value (before GetN is called), that value will show up in the input box, otherwise the input box
will appear blank. In either case, the initial value can be changed or kept.
To check the data entered, run the following line of script:
// Output the data:
type In %(event$), the %(measurement$) was $(nn) %(units$);

This next example script assumes a Graph is the active window and prompts for information then
draws a line and labels it. The call to GetN uses string registers and pre-defined lists as inputs.
%A=Minimum;
iColor = 15;
dVal = 2.75;
iStyle = 2;

// Opens the GetN dialog ...

// The extra %-sign in front of %A interprets the string register
// literally, instead of treating it as a variable name.
getn (Label Quantile) %%A
(Color) iColor:@C
(Style) iStyle:@D
(Value) dVal
(Set Quantile);

draw -n %A -l -h dVal; // Draws a horzontal, named line

%A.color = iColor; // Sets the line color
%A.linetype = iStyle; // Sets the line style

// Creates a text label named QLabel at the right end of the

// line
label -s -a x2 dVal -n QLabel %A;

%A.Connect(QLabel,1); // Connects the two objects

Note : The script requires that %A should be a single word and that object QLabel does not exist.

247
 LabTalk Scripting Guide

The following character sequences, beginning with the @ character, access pre-defined lists for GetN
arguments:
List Description

@B List of Object Background attributes

@C Basic Color List

@D Line Style List

@P Pattern List

@S Font Size List

@T Font List

@W Line Width List

@Z Symbol Size List

Note that the value returned when a list item is selected within the GetN dialog is the index of the
item in the list. For instance, if one of your GetN entries is:
(Font Size) fs:@S
and you select 18 from the drop-down list in the dialog, the variable fs will hold the value 8, since 18
is the 8th item in the list.

Below is another example script that allows a user to change a Symbol Plot to a Line + Symbol Plot
or the reverse:
get %C -z iSymbolSize; // Get current Symbol Size
get %C -cl iLineColor; // Get current Line color
iUseLine = 0;
// Now open the dialog to the user
getn (Symbol Size) iSymbolSize
(Use Line) iUseLine:2s
(Line Color) iLineColor:@C
(Set Plot Style);
// If User asked for Line
if(iUseLine == 1)
{
set %C -l 1; // Turn on the line
set %C -cl iLineColor; // Set the line color
}
// .. if not
else
set %C -l 0; // Turn off line
set %C -z iSymbolSize; // Set Symbol size

248
 User Interaction

14.3 Getting Points from Graph

Any of the Tools in the Origin Tools Toolbar can be initiated from script, but three can be linked to
macros and programmed to do more.
To program tools, define the pointproc macro to execute appropriate code. The pointproc macro
runs when the user double-clicks or single-clicks and presses the Enter key.

14.3.1 Screen Reader

This script puts a label on a graph using the Screen Reader tool.
dotool 2; // Start the Screen Reader Tool
dotool -d; // Allow a single click to act as double click
// Here we define our '''pointproc''' macro
def pointproc {
label -a x y -n MyLabel Hello;
dotool 0; // Reset the tool to Pointer
done = 1; // Set the variable to allow infinite loop to end
}
// Script does not stop when using a tool,
// so further execution needs to be prevented.
// This infinite loop waits for the user to select the point
for( done = 0 ; done == 0; ) sec -p .1;
// A .1 second delay gives our loop something to do:
type Continuing script ...;
// Once the macro has run, our infinite loop is released

14.3.2 Data Reader

The Data Reader tool is similar to the Screen Reader, but the cursor locks on to actual data points. If
defined, a quittoolbox macro runs if user presses Esc key or clicks the Pointer Tool to stop the Data
Reader.
This example assumes a graph window is active and expects the user to select three points on their
graph.
@global = 1;
dataset dsx, dsy; // Create two datasets to hold the X and Y values
dotool 3; // Start the tool
// Define the macro that runs for each point selection
def pointproc {
dsx[count] = x; // Get the X coordinate
dsy[count] = y; // Get the Y coordinate
count++; // Increment count
if(count == 4) dotool 0; // Check to see if we have three points
else type -a Select next point;
}
// Define a macro that runs if user presses Esc key,
// or clicks the Pointer Tool:
def quittoolbox {
// Error : Not enough points
if(count < 4) ty -b You did not specify three datapoints;
else
{
draw -l {dsx[1],dsy[1],dsx[2],dsy[2]};
draw -l {dsx[2],dsy[2],dsx[3],dsy[3]};
draw -l {dsx[3],dsy[3],dsx[1],dsy[1]};

249
 LabTalk Scripting Guide

double ds12 = dsx[1]*dsy[2] - dsy[1]*dsx[2];

double ds13 = dsy[1]*dsx[3] - dsx[1]*dsy[3];
double ds23 = dsy[3]*dsx[2] - dsy[2]*dsx[3];
area = abs(.5*(ds12 + ds13 + ds23));
type -b Area is $(area);
}
}
count = 1; // Initial point
type DoubleClick your first point (or SingleClick and press Enter);
The following example allows user to select arbitrary number of points until Esc key is pressed or
user clicks on the Pointer tool in the Tools toolbar.
@global = 1;
dataset dsx, dsy; // Create two datasets to hold the X and Y values
dotool 3; // Start the tool
// Define the macro that runs for each point selection
def pointproc {
count++; // Increment count
dsx[count] = x; // Get the X coordinate
dsy[count] = y; // Get the Y coordinate
}

// Define a macro that runs if user presses Esc key,

// or clicks the Pointer Tool:
def quittoolbox {
count=;
for(int ii=1; ii<=count; ii++)
{
type $(ii), $(dsx[ii]), $(dsy[ii]);
}
}
count = 0; // Initial point
type "Click to select point, then press Enter";
type "Press Esc or click on Pointer tool to stop";

Pressing Enter key to select a point works more reliably than double-clicking on the
point.

You can also use the getpts command to gather data values from a graph.

14.3.3 Data Selector

The Data Selector tool is used to set a Range for a dataset. A range is defined by a beginning row
number (index) and an ending row. You can define multiple ranges in a dataset and Origin analysis
routines will use these ranges as input, excluding data outside these ranges.
Here is a script that lets the user select a range on a graph.
// Start the tool
dotool 4;
// Define macro that runs when user is done
def pointproc {
done = 1;
dotool 0;
}
// Wait in a loop for user to finish by pressing ...
// (1) Enter key or (2) double-clicking

250
 User Interaction

for( done = 0 ; done == 0 ; )

{
sec -p .1;
}
// Additional script will run once user completes tool.
ty continuing ..;
When using the Regional Data Selector or the Regional Mask Tool you can hook into the quittoolbox
macro which triggers when a user presses Esc key:
// Start the Regional Data Selector tool with a graph active
dotool 17;
// Define macro that runs when user is done
def quittoolbox {
done = 1;
}
// Wait in a loop for user to finish by pressing ...
// (1) Esc key or (2) clicking Pointer tool:
for( done = 0 ; done == 0 ; )
{
sec -p .1;
}
// Additional script will run once user completes tool.
ty continuing ..;
And we can use an X-Function to find and use these ranges:
// Get the ranges into datasets
dataset dsB, dsE;
mks ob:=dsB oe:=dsE;
// For each range
for(idx = 1 ; idx <= dsB.GetSize() ; idx++ )
{
// Get the integral under the curve for that range
integ %C -b dsB[idx] -e dsE[idx];
type Area of %C from $(dsB[idx]) to $(dsE[idx]) is $(integ.area);
}

List of Tools in Origin Tools Toolbar. Those in bold are useful in programming.
Tool
Description
Number

Pointer - The Pointer is the default condition for the mouse and makes the
0
mouse act as a selector.

ZoomIn - A rectangular selection on a graph will rescale the axes to the

1
rectangle. (Graph only)

2 Screen Reader - Reads the location of a point on a page.

3 Data Reader - Reads the location of a data point on a graph. (Graph only)

Data Selector - Sets a pair of Data Markers indicating a data range. (Graph
4
only)

251
 LabTalk Scripting Guide

5 Draw Data - Allows user the draw data points on a graph. (Graph only)

6 Text - Allows text annotation to be added to a page.

7 Arrow - Allows arrow annotation to be added to a page.

8 Curved Line - Allows curved line annotation to be added to a page.

9 Line - Allows line annotation to be added to a page.

10 Rectangle - Allows rectangle annotation to be added to a page.

11 Circle - Allows circle annotation to be added to a page.

12 Closed Polygon - Allows closed polygon annotation to be added to a page.

13 Open Polygon - Allows open polygon annotation to be added to a page.

14 Closed Region - Allows closed region annotation to be added to a page.

15 Open Region - Allows open region annotation to be added to a page.

ZoomOut - Zooms out (one level) when clicking anywhere in a graph. (Graph
16
only)

17 Regional Data Selector - Allows selection of a data range. (Graph only)

18 Regional Mask Tool - Allows masking a points in a data range. (Graph only)

14.4 Bringing Up a Dialog

X-Functions whose names begin with dlg may be called in your scripts to facilitate dialog-based
interaction.
Name Brief Description

dlgChkList Prompt to select from a list

dlgFile Prompt with an Open File dialog

dlgPath Prompt with an Open Path dialog

dlgRowColGoto Go to specified row and column

252
 User Interaction

dlgSave Prompt with a Save As dialog

dlgTheme Select a theme from a dialog

Possibly the most common such operation is to select a file from a directory. The following line of
script brings up a dialog that pre-selects the PDF file extension (group), and starts at the given path
location (init):
dlgfile group:=*.pdf init:="C:\MyData\MyPdfFiles";
type %(fname$); // Outputs the selected file path to Script Window
The complete filename of the file selected in the dialog, including path, is stored in the variable
fname$. If init is left out of the X-Function call or cannot be found, the dialog will start in the User
Files folder.
The dlgsave X-Function works for saving a file using a dialog.
dlgsave ext:=*.ogs;
type %(fname$); // Outputs the saved file path to Script Window

253
15 Working with Excel
Origin can use Excel Workbooks directly within the Origin Workspace. The Excel Workbooks can be
stored within the project or linked to an external Excel file (*.xls, *.xlsx). An external Excel Workbook
which was opened in Origin can be converted to internal, and an Excel Workbook created within
Origin can be saved to an external Excel file.
To create a new Excel Workbook within Origin ..
window -tx;
The titlebar will include the text [Internal] to indicate the Excel Workbook will be saved in the Origin
Project file.
To open an external Excel file ..
document -append D:\Test1.xls;
The titlebar will include the file path and name to indicate the Excel file is saved external to the Origin
Project file.
You can save an internal Excel Workbook as an external file at which point it becomes a linked
external file ..
// The Excel window must be active. win -o can temporarily make it active
window -o Book5 {
// You must include the file path and the .xls extension
save -i D:\Test2.xls;
}
You can re-save an external Excel Workbook to a new location creating a new file and link leaving
the original file on disk ..
// Assume the Excel Workbook is active
// %X holds the path of an opened Origin Project file
save -i %XNewBook.xls;

255
16 Running R in Origin

16.1 Running R in Origin

There are a couple of ways to interact with R from Origin.
 Using the R Console and the Rserve Console. These tools allow Origin users to issue R

commands within the Origin environment and transfer data between the two applications either

using a dialog interface, or by using commands. For examples, see Data Analysis in Origin

with R Console.

 Using the LabTalk objects R and RS (RServe) . The R and RS LabTalk objects can execute R

commands and pass variables and datasets between Origin and R.

To make use of the R object and R Console, you need to have R installed locally. To use the RS
object and the Rserve Console, you will need to have the R packages installed on the server side,
and communicate to the server computer with Origin on the client side.
 For information on obtaining and installing R locally, see this topic.

 For information on setting up an R server, see this topic.

Minimum Origin Version Required: 2016 SR0

16.1.1 Execute R Command in Script Window

We can use LabTalk objects R and RS to execute R commands and pass variables between LabTalk
and R. The examples below work for both R and RServe (replace "R" with "RS").

16.1.1.1 Initialize R or RS
Before running R command in Labtalk, you can initialize the R application by running:
if( R.Init()<0 )
{
type -b "Please install R software first.";
return;
}
in the Script Window.
To initialize the RS object, please refer to Script below, and view this page for parameters setting.
if(RS.Init(***.***.**.**, 12306, user, password)<0) // Address is Rserve PC
IP, e.g: 192.168.18.75
{
type -b "Initialize failed.";
return;
}

16.1.1.2 Execute R and RS command

257
 LabTalk Scripting Guide

Execute R command
R.Exec(rand<-sample(x = 1:6, size = 50, replace = TRUE));
R.Exec(rand);
and perform analysis:
R.Exec(sum<-summary(rand));
R.Exec(sum);
The summary could be shown in this way:
Min. 1st Qu. Median Mean 3rd Qu. Max.
1.00 2.00 3.50 3.56 5.00 6.00
Execute Multiple R Command Lines
R.Exec("array<-1:25;dim(array)<-c(5,5);array") // Run multiple R command
lines separated by semicolon
Execute RS command
string fname$ = system.path.program$ + "Samples\Curve Fitting\Sensor01.dat";
impasc;
range r1 = 1:2;

//send data from worksheet to R vector

RS.Send(%(r1), RR, 2); //send the range to R data.frame

RS.Exec(fit<-lm(RR$Sensor.Output~RR$Displacement)); //perform linear fit

RS.Exec(fit);

Execute R/RS command example

In addition, a practical example is introduced in this page Perform Logistic regression in R by

using LabTalk.

16.1.1.3 Execute .R file

If you want to execute a *.R file in your computer, you can use the syntax below in Script Window:
R.Exec(source(".R file path"));
For example:
R.Exec(source("D:\\RData\\test.R"));

16.1.1.4 Send Origin Dataset to R Console

//Active a workbook
R.Send("1!1", arr1, 0); // Send Column 1 in Sheet 1 current workbook to R as
variable ''array'' (type vector)
range rx=1; // Use range notation rx to refer to column 1 in active worksheet
R.Send(%(rx), rlabel, 0); // Send column 1 to R as variable rlabel (type
vector)
// Suppose the values of first columns are: 1, 2, 3, --
range rr = 1; // Refer to first column in active worksheet
R.Send(%(rr), temp, 0); // Send first column as R variable temp

16.1.1.5 Receive R Variable as Origin Dataset

R.Receive("1!1",RMat,1) // Receive R Matrix Variable RMat to first matrix
object in current matrixbook and first matrix sheet
R.Receive("1!1",df$vec1,0); //Receive data member 'vec1' in R data frame 'df'
to column as a vector

258
 Running R in Origin

//Suppose there is a logical vector temp with value [1] FALSE FALSE TRUE
range rl=1;
R.Receive(%(rl),temp,0); // Column 1 in active sheet would be 0,0,1 instead

16.1.1.6 Pass Variables between Labtalk and R

R and RS objects have four member functions: GetReal, SetReal, GetStr, and SetStr which are
used to pass numeric and string variables between Labtalk and R, for example:
You define numeric or string variable in R Serve Console,
Rvar=16
Rstr="height"
You can pass value to LabTalk variable in this way:
R.GetReal(LTVar, RVar)
R.GetStr(LTStr$, RStr)
//pass a real number in a R list 'e1' to a Labtalk variable
R.GetReal(LTVar,e1$a);
Or you define a numeric or string variable in LabTalk, you can pass the value to R variable in this
way:
R.SetReal(LTVar, RVar)
R.SetStr(LTStr$, RStr)

16.1.2 Utilizing R Console or Rserve Console

We can use the R Console (or Rserve Console ) to run R commands directly in the dialog input box,
then, pass the resulting values into an Origin worksheet using buttons << and >>. Data can be
exchanged in multiple formats (vector, matrix, data.frame) between R and Origin worksheet (or matrix
sheet) by using R console (or Rserve Console).
The following graph shows how to generate random data with a binomial distribution and pass it to an
Origin worksheet.

259
 LabTalk Scripting Guide

16.2 Examples: Perform Logistic regression in R by using

LabTalk
Logistic regression models a relationship between predictor variables and a categorical response
variable. The following example shows how to perform a Logistic regression on data
Origin2016\Samples\Statistics\LogRegData.dat by using Labtalk R object and RS objectin Script
window.
We first read data into Origin worksheet, and send the data as R data frame. Then perform Logistic
Regression on imported data by using R command glm, finally create a new Origin worksheet as the
summary table for fitting results, and send the results including parameters, residual, aic and
dispersion...calculated by R into summary table worksheet.

16.2.1.1 R Object
//R object example to call R in LabTalk
//run.section(testRex,LogisticRoex)

//Import sample data

newbook;
string fn = system.path.program$ + "Samples\Statistics\LogRegData.dat";
impasc fname:=fn$ options.sparklines:=0;

//Check whether R is installed

if( R.Init()<0 )
{
type -b "Please install R software first.";
return;
}

//Send imported data in Origin to R's data frame variable dfy

//Data frame dfy includes four columns: Age, Salary, Gender and Career_Change
//Gender and Career_Change columns are category data
R.Send("!", dfy, 2);

//Perform Logistic Regression on imported data

//Results are stored in R's list variable yr
R.Exec( "yf<-glm( Career_Change ~ Age + Salary + Gender,
family=binomial(logit), data=dfy)" );
R.Exec("yr<-summary(yf)");

//New a workbook to output R's result

newbook;
page.longname$ = "Logistic Regression Result";

//Send R's coefficients matrix in list object to Origin's worksheet

//and start at 1st column in the worksheet
R.Receive("1", yr$coefficients);

int nc = wks.ncols;
wks.ncols = nc + 6;

//Calculate the exp of parameters

wcol( nc+1 )[L]$ = "Exp of Parameter";
wcol( nc+1 ) = exp( wcol(2) );

//Set label and column Long Name for calculated result

260
 Running R in Origin

wcol( nc+2 )[1]$ = "Residual";

wcol( nc+3 )[L]$ = "DF";

wcol( nc+4 )[L]$ = "Deviance";
wcol( nc+5 )[L]$ = "AIC";
wcol( nc+6 )[L]$ = "Dispersion Parameter for Binomial Family";

//Send R's residual info to Origin's worksheet

double dfr, devr, aic, rlev;
//Get LabTalk double variables from list object's element variables in R
R.GetReal( dfr, yr$df.residual );
R.GetReal( devr, yr$deviance );
R.GetReal( aic, yr$aic );
R.GetReal( rlev, yr$dispersion );

//Set worksheet's cells with LabTalk double variables

wcol( nc+3 )[1] = dfr;
wcol( nc+4 )[1] = devr;

wcol( nc+5 )[1] = aic;

wcol( nc+6 )[1] = rlev;

//Clear all R variables

R.Reset();

16.2.1.2 RS Object
You need to Setup R Serve before running this example.
//RS example to call Rserve in LabTalk
//Import sample data
newbook;
string fn = system.path.program$ + "Samples\Statistics\LogRegData.dat";
impasc fname:=fn$ options.sparklines:=0;

//Connect Rserve. An Rserve should be set up first.

if( RS.Init( ***.***.***.***, 12306 )<0 ) //input the IP address of the
server side here
{
type -b "Fail to connect R server.";
return;
}

//Send imported data in Origin to R's data frame variable dfy

//Data frame dfy includes four columns: Age, Salary, Gender and Career_Change
//Gender and Career_Change columns are category data
RS.Send("!", dfy, 2);

//Perform Logistic Regression on imported data

//Results are stored in R's list variable yr
RS.Exec( "yf<-glm( Career_Change ~ Age + Salary + Gender,
family=binomial(logit), data=dfy)" );
RS.Exec("yr<-summary(yf)");

//New a workbook to output R's result

newbook;
page.longname$ = "Logistic Regression Result";

261
 LabTalk Scripting Guide

//Send R's coefficients matrix in list object to Origin's worksheet

//and start at 1st column in the worksheet
RS.Receive("1", yr$coefficients);

int nc = wks.ncols;
wks.ncols = nc + 6;

//Calculate the exp of parameters

wcol( nc+1 )[L]$ = "Exp of Parameter";
wcol( nc+1 ) = exp( wcol(2) );

//Set label and column Long Name for calculated result

wcol( nc+2 )[1]$ = "Residual";

wcol( nc+3 )[L]$ = "DF";

wcol( nc+4 )[L]$ = "Deviance";
wcol( nc+5 )[L]$ = "AIC";
wcol( nc+6 )[L]$ = "Dispersion Parameter for Binomial Family";

//Send R's residual info to Origin's worksheet

double dfr, devr, aic, rlev;
//Get LabTalk double variables from list object's element variables in R
RS.GetReal( dfr, yr$df.residual );
RS.GetReal( devr, yr$deviance );
RS.GetReal( aic, yr$aic );
RS.GetReal( rlev, yr$dispersion );

//Set worksheet's cells with LabTalk double variables

wcol( nc+3 )[1] = dfr;
wcol( nc+4 )[1] = devr;

wcol( nc+5 )[1] = aic;

wcol( nc+6 )[1] = rlev;

//Clear all R variables

RS.Reset();

262
17 Working with Python
Origin provides embedded python environment, so that you can either run python in Origin (support
both command line and .py file), or use a PyOrigin module to access Origin from Python.
The embedded Python in Origin could be either version 3.3.5 or version 2.7.8. By default, it is Python
version 3.3 running in Origin. To switch to use Python version 2.7, open Script Window and select
menu Edit: Script Execution: Python 2.7. It can be also switched by a system variable @PYV.
When @PYV = 3 (Default), the embedded Python is 3.3.5, while if @PYV = 2, it is 2.7.8. To set value
for a system variable, click Tools:System Variables to open the Set System Variables dialog.
The following document page is written based on the assumption that Python 3.3.5 is used in Origin.
Minimum Origin Version Required: 2015 SR0

17.1 Run Python in Origin

In Origin, you can run Python command line, or Python files (.py extension). Additionally, you could
evaluate a Python expression in Origin as well.

17.1.1 Run Python Command Line

To run python command line in Origin, use any of the following approaches:
 In the Script Window, make sure Edit:Script Execution:Python 3.3 is selected, then highlight

the Python command line and hit Enter key to directly execute the command.

OR

263
 LabTalk Scripting Guide

 Use the run -py command option switch in LabTalk, for example, make sure Edit:Script

Execution:LabTalk is selected and run the following script:

// Define the Python command line(s) as a LabTalk string variable

str$ = "a = 2 ** 8;print(a)";
// Execute Python command lines
run -py %(str$);

// ** is the Exponent operator in Python

//It should return 256, i.e. 2 to the power 8
OR
 Use the run.python() object method in LabTalk, for example, also make sure Edit:Script

Execution:LabTalk is selected and run the following script:

run.python(myname='Origin';print(myname));
//Should output 'Origin'

To execute multiple Python commands or a Python module in the Script Window, set
the system variable @PYI to 0 to turn off interactive mode. Choose Tools:System
Variables to open the Set System Variables dialog, enter Variable = pyi and enter a
Value = 0.

17.1.2 Run Python File

In order to run a Python file (with .py extension) in Origin, use either of the following LabTalk
command/object:
 Use the run -pyf command option switch in LabTalk, for example, make sure Edit:Script

Execution:LabTalk is selected and run the following script:

// Define a string for the file path and name of the .py file
string str$ = system.PATH.PROGRAM$ + "\Samples\Python\ListMember.py";
// Run the .py file
run -pyf "%(str$)";

// This .py file list all provided functions in PyOrigin module

OR
 Use the run -pyp command option switch to execute a Python file attached to the Origin project

file.

OR
 Use the run.python() object method in LabTalk, for example, make sure Edit:Script

Execution:LabTalk is selected and run the following script:

// Define a string for the file path

264
 Working with Python

string file_path$ = system.PATH.PROGRAM$ + "\Samples\Python\";

// Set path of the python file
run.python("%(file_path$)", 32);
// Run the .py file named as ListMember.py under the selected path
run.python("ListMember.py", 2);

// This .py file list all provided functions in PyOrigin module

17.1.3 Evaluate Python Expression

You can also evaluate a Python expression using either of the following LabTalk command/object
method
 Use run -pye command option switch, for example, make sure Edit:Script Execution:LabTalk

is selected and run the following script:

run -pye 10 % 4;

// It evaluates the Python expression 10 % 4, % is the Modulus operator in

Python
// It outputs the evaluated value 2, which is the remainder of 10 divided by
4
OR
 Use the run.python() object method in LabTalk, for example, also make sure Edit:Script

Execution:LabTalk is selected and run the following script:

run.python("10 % 4", 1);

// It also returns the evaluated value 2, which is the same as the example
above

17.2 Access Origin in Python

In your Python code, you can import the PyOrigin module and make use of the functions it provided
to access Origin object.

17.2.1 Import PyOrigin Module

To import the PyOrigin module, make sure to have the following command line in your .py file:
import PyOrigin
Note that PyOrigin module is supposed to be used for the interaction of the current Origin session
and Python extension, so the .py files with PyOrigin module imported can only be called from Origin
(See the above section of Run Python File in Origin), i.e. such .py files cannot be executed directly
from an external Python editor. (e.g. IDLE)

17.2.2 Inspect Functions Provided by PyOrigin

In order to inspect all the functions/global variable and classes/member functions accessible from
embedded Python, you can run the following LabTalk script in the Script Window:

265
 LabTalk Scripting Guide

//make sure the Script Execution Mode is LabTalk

string str$ = system.PATH.PROGRAM$ + "\Samples\Python\ListMember.py";
run -pyf "%(str$)";
The functions/classes/global variables provided by the PyOrigin module are very similar to their
counterpart in Origin, so you can refer to the Origin C Reference for detailed usage.
(Help:Programming:Origin C and go to Origin C Reference Chapter)

17.2.3 Examples to Working with Python in Origin

Several built-in Python examples are provided under Origin sample folder(<Origin EXE
Folder>\Samples\Python) in order to show how to work with Python in Origin, including how to send
data to worksheets, import data and plot, export graphs and publish graphs on a web page, etc. The
example *.py files can be run directly by some labtalk commands, and Origin example project files
with Python files attached can be run by clicking the customized buttons.

17.2.3.1 Run Python File and Send Data From Python to Origin
The Python file SendDataToWorksheet.py under <Origin EXE Folder>\Samples\Python is an
example to show how to send data from Python to Origin, it created a dialog using Python tkinter
module to get user input such as column format, number of rows, etc. Then these inputted
parameters will be passed to Origin.
In order to run this .py file, execute the following LabTalk script in the Script Window:
//Make sure the Script Execution Mode is LabTalk
//Make sure a worksheet is active in Origin
string str$ = system.PATH.PROGRAM$ +
"\Samples\Python\SendDataToWorksheet.py";
run -pyf "%(str$)";

17.2.3.2 Run and View Python File Attached to Origin Project

The example ImportMatrixPlotContour.opj under <Origin EXE Folder>\Samples\Python shows how
to import a matrix into Origin and plot it as a contour graph. It also shows the concept of attaching
Python files to Origin projects and execute.
To use this example, select File:Open to open the project file in Origin, you will see a workbook
Control Panel with two embedded buttons. Click the Import Matrix and Plot Contour button to run
the attached Python file, this is equivalent to running the following LabTalk script in Script Window:
run -pyp ImportMatrixPlotContour.py;
You can also click the Show Python Code button to view the attached Python file in Origin's Code
Builder. This is equivalent to the following LabTalk script:
%z = system.path.projectAttachedFilesPath$;
ed.open(%zImportMatrixPlotContour.py);
Alternatively, you could open the Code Builder (View: Code Builder or Alt + 4), and browse to the
Project folder in Workspace panel to access the attached Python file.

To attach your Python files to an Origin project, right click on the Project folder and
select Add Files... to include your Python file(s).

17.3 A Note to Use Python Extensions

266
 Working with Python

The embedded Python in Origin includes all the basic modules and the modules which are installed
to your Python application. If you want to use other Python extensions, e.g. PyQt4, numpy, scipy,
follow the procedure below:
1. Make sure the downloaded Python extension version is either version 3.3 or version 2.7 to be

compatible with the embedded Python version in Origin.

2. Make sure the downloaded Python extension corresponding to same CPU register size as the

Origin being running - 32 bit or 64 bit. To know whether current Origin verison is 32 bit or 64 bit,

you can directly read it from Origin program window title bar or type command " system.bits=;"

in Command Window or Script Window.

3. Make sure the installed Python extension path is properly appended so it can be directly used

by Python import command.

4. Make sure current Python running version is compatible with downloaded Python extension. By

default, it is Python version 3.3 running in Origin. To switch to use Python version 2.7, open

Script Window and select menu Edit: Script Execution: Python 2.7.

If the Python extension is installed in default path, such as C:\Program Files (x86)\Python\Lib\site-
packages\, you can directly use the package as shown in example below:
# For Python extension version 3.3 (default)

import numpy

x = numpy.array([[1, 2, 3], [4, 5, 6]], numpy.int32)

print(x)
Otherwise, you have to add its installation folder to the system path list before you import it. To add
the installation folder to system path list, the recommended approach is to run the following Python
statements in the embedded Python environment of Origin (either directly run statements, or run from
files):
import sys

# Replace the value of string variable py_ext_path

# with the actual Python extension installation path in your computer

py_ext_path = "C:\Python33\Lib\site-packages"

if py_ext_path not in sys.path:

sys.path.append(py_ext_path)
And after you have executed these Python statements, you will be able to access the Python
extension in the current Origin session using for example:
import PyQt4
But once you closed the current Origin session, you will need to add the Python extension path to
sys.path list once again.

267
LabTalk Scripting Guide

For example purpose, you can click desired version folder and find the compatible
packages to download in links Numpy and Scipy.

268
18 Automation and Batch Processing

18.1 Automation and Batch Processing

This chapter demonstrates using LabTalk script to automate analysis in Origin by creating Analysis
Templates, and using these templates to perform batch processing of your data:

Topics covered in this section:

 Analysis Templates

 Using Set Column Values to Create an Analysis Template

 Batch Processing

18.2 Analysis Templates

Analysis Templates are pre-configured workbooks which can contain multiple sheets including data
sheets, report sheets from analysis operations, and optional custom report sheets for presenting
results. The analysis operations can be set to recalculate on data change, thus allowing repeat use of
the analysis template for batch processing or manual processing of multiple data files.
The following script example opens a built-in Analysis Template, Dose Response Analysis.ogw, and
imports a data file into the data sheet. The results are automatically updated based on the new data.
string fPath$ = system.path.program$ + "Samples\Curve Fitting\";
string fname$ = fPath$ + "Dose Response Analysis.ogw";
// Append/open the analsys template to current project
doc -a %(fname$);
string bn$ = %H;
win -o bn$ {
// Import no inhibitor data
fname$ = fPath$ + "Dose Response - No Inhibitor.dat";
impASC options.Names.FNameToSht:=0
options.Names.FNameToBk:=0
options.Names.FNameToBkComm:=0
orng:=[bn$]"Dose Response - No Inhibitor";
// Import inhibitor data
fname$ = fPath$ + "Dose Response - Inhibitor.dat";
impASC options.Names.FNameToSht:=0
options.Names.FNameToBk:=0
options.Names.FNameToBkComm:=0
orng:=[bn$]"Dose Response - Inhibitor";
// Active the result worksheet
page.active$ = result;
}

269
 LabTalk Scripting Guide

To learn how to create Analysis Templates, please refer to the Origin tutorial: Creating and Using
Analysis Templates.

18.3 Using Set Column Values to Create an Analysis

Template
Many analysis tools in Origin provide a Recalculate option, allowing for results to update when
source data is modified, such as when importing new data to replace existing data. A workbook
containing such operations can be saved as an Analysis Template for repeated use with Batch
Processing.
The Set Column Values feature can also be used to create such Analysis Templates when custom
script is needed for your analysis.
In order to create Analysis Templates using the Set Column Values feature, the following steps are
recommended:
1. Set up your data sheet, such as importing a representative data file.

2. Add an extra column to the data sheet, or to a new sheet in the same workbook.

3. Open the Set Column Values dialog from this newly added column.

4. Enter the desired analysis script in the Before Formula Scripts panel. Note that your script

can call X-Functions to perform multiple operations on the data.

5. In you script, make sure to reference at least one column or cell of your data sheet that will get

replaced with new data. You can do this by defining a range variable that points to a data

column and then use that range variable in your script for computing your custom analysis

output.

6. Set the Recalculate drop-down in the dialog to either Manual or Auto, and press OK.

7. Use the File: Save Workbook as Analysis Template... menu item to save the Analysis

Template.

For an example on setting up such a template using script, please refer to the Origin tutorial: Creating
Analysis Templates using Set Column Value.

18.4 Batch Processing

One may often encounter the need to perform batch processing of multiple sets of data files or
datasets in Origin, repeating the same analysis procedure on each set of data. This can be achieved
in three different ways, and the following sections provide information and examples of each.

18.4.1 Processing Each Dataset in a Loop

One way to achieve batch processing is to loop over multiple files or datasets, and within the loop
process each dataset by calling appropriate X-Functions and other script commands to perform the
necessary data processing.

270
 Automation and Batch Processing

The following example shows how to import 10 files and perform a curve fit operation and print out
the fitting results:
// Find all files using wild card
string path$ = system.path.program$ + "Samples\Batch Processing"; // Path to
find files
// Find the files in the folder specified by path$ variable (default)
// The result file names are stored in the string variable fname$
// Separated by CRLF (default). Here wild card * is used, which means
// all files start with "T", and with the extension "csv"
findFiles ext:="T*.csv";

// Start a new book with no sheets

newbook sheet:=0;
// Loop over all files
for(int iFile = 1; iFile <= fname.GetNumTokens(CRLF); iFile++)
{
// Get file name
string file$ = fname.GetToken(iFile, CRLF)$;
// Import file into a new sheet
newsheet;
impasc file$;
// Perform gaussian fitting to col 2 of the current data
nlbegin iy:=2 func:=gaussamp nltree:=myfitresult;
// Just fit and end with no report
nlfit;
nlend;
// Print out file name and results
type "File Name: %(file$)";
type " Peak Center= $(myfitresult.xc)";
type " Peak Height= $(myfitresult.A)";
type " Peak Width= $(myfitresult.w)";
}

18.4.2 Using Analysis Template in a Loop

Custom templates for analysis can be created in Origin by performing the necessary data processing
from the GUI on a representative dataset and then saving the workbook, or the entire project, as an
Analysis Template. The following example shows how to make use of an existing analysis template
to perform curve fitting on 10 files:
// Find all files using wild card
string fpath$ = "Samples\Batch Processing\";
string path$ = system.path.program$ + fpath$; // Path to find files
// Find the files in the folder specified by path$ variable (default)
// The result file names are stored in the string variable fname$
// Separated by CRLF (default). Here wild card * is used, which means
// all files start with "T", and with the extension "csv"
findFiles ext:="T*.csv";

// Set path of Analysis Template

string templ$ = path$ + "Peak Analysis.OGW";
// Loop over all files
for(int iFile = 1; iFile <= fname.GetNumTokens(CRLF); iFile++)
{
// Open an instance of the analysis template
doc -a %(templ$);
// Import current file into first sheet

271
 LabTalk Scripting Guide

page.active = 1;
impasc fname.GetToken(iFile, CRLF)$
}

// Issue a command to update all pending operations

// in case the operations were set to manual recalculate in the template
run -p au;

18.4.3 Using Batch Processing X-Functions

Origin provides script-accessible X-Functions to perform batch processing, where there is no need to
loop over files or datsets. One simply creates a list of desired data to be processed and calls the
relevant X-Function. The X-Function then either uses a template or a theme to process all of the
specified data. Some of these X-Functions can also create an optional summary report that contains
results from each file/dataset that were marked for reporting by the user, in their custom analysis
template.
The table below lists X-Functions available for batch analysis:
Name Brief Description

Perform batch processing of multiple files or datasets using Analysis

batchProcess
Template, with optional summary report sheet

paMultiY Perform peak analysis of multiple Y datasets using Peak Analyzer theme
The following script shows how to use the batchProcess X-Function to perform curve fitting of data
from 10 files using an analysis template, with a summary report created at the end of the process.
// Find all files using wild card
string path$ = system.path.program$ + "Samples\Batch Processing\"; // Path
to find files
// Find the files in the folder specified by path$ variable (default)
// The result file names are stored in the string variable fname$
// Separated by CRLF (default). Here wild card * is used, which means
// all files start with "T", and with the extension "csv"
findFiles ext:="T*.csv";

// Set path of Analysis Template

string templ$ = path$ + "Peak Analysis.OGW";

// Call the Batch Processing X-Function

// Keep only the final summary sheet, delete intermediate books
batchProcess batch:=1 name:=templ$ data:=0 fill:="Raw Data"
append:="Summary" remove:=1 method:=impASC;

Batch processing using X-Functions can also be performed by calling Origin from an external
console; for more see Running Scripts From Console.

272
19 Function Reference

19.1 Function Reference

This section provides reference lists of functions, X-Functions and Origin C Functions that are
supported in LabTalk scripting:

Topics covered in this section:

 LabTalk-Supported Functions

 LabTalk-Supported X-Functions

19.2 LabTalk-Supported Functions

Below is a tabular listing of functions supported by the Set Values's F(x) menu, broken down by
category.

19.2.1 String Functions

Note: All of the following functions are available only in the Origin 8 SR6 or later version!

Name Brief Description

Takes an integer 1-255, returns the ASCII character.
examples:

 char(65)$ returns A.
Char(number)$
 char(col(B))$ returns ASCII characters

corresponding to integer values in col(B).

Takes a string, returns ASCII code for the first

character. examples:

Code(str$)  str$ = "abc"; code(str$) returns 97.

 code(col(D)) returns integers corresponding

273
 LabTalk Scripting Guide

to the ASCII code for the first character in the

string in col(D).

Takes two strings, returns 1 (identical) or 0 (not

identical). Option Case controls case sensitivity: 1 =
true (default), 0 = false. examples:

 str1$ = "ABC"; str2$ = "abc";

compare(str1$,str2$,0) returns 1.
Compare(str1$, str2$ [,Case])
 compare(col(F), col(G),1) returns "0"

when string or case does not match, or "1" when

string and case do match.

Takes two strings, returns 1 (identical, including case)

or 0 (not identical). examples:

 str1$ = "ABC"; str2$ = "abc";

exact(str1$,str2$) returns 0.
Exact(str1$, str2$)
 exact(col(F), col(G)) returns "0" if not an

exact string match or "1" if exact match (incl.

case).

Searches str1$ for str2$, returns the position from the

first character in str1$ (found) or -1 (not found).
Option StartPos controls start search position (default
= 1). Case sensitive. No wildcards. examples:

 str1$ = "abcde"; str2$ = "bc";

Find(str1$, str2$ [,StartPos]) find(str1$,str2$) returns 2.

 find(col(G),col(J)) searches the col(G)

string for the col(J) string, starting from the first

character; if found, returns the position of the

274
 Function Reference

col(J) string, in the col(G) string.

Takes a string str$, returns the leftmost n characters.

examples:

 str$ = "abcde"; Left(str$,3)$ returns

Left(str$, n)$ abc.

 left(col(G),3)$ returns the leftmost 3

characters in the col(G) string.

Takes a string str$, returns the number of

characters. examples:

 str$ = "abc ABC"; Len(str$) returns 7.

Len(str$)
 len(col(G)) returns the number of characters

in the col(G) string.

Takes a string str$, converts it to

lowercase. examples:

 str1$ = "ABCDE"; str2$ =

Lower(str$)$ Lower(str1$)$ returns abcde.

 lower(col(F))$ returns the strings in col(F) in

lower case.

Takes a delimited string, converts it to CSV. Option

quote to enclose output: 0 (default) = no quotes, 1 =
single quotes, 2 = double quotes. Option
output_delim: 0 = comma, 1 = semicolon. Option
MakeCSV(str1$[, quote, output_delim, input_delim$ specifies source string delimiter (not
input_delim$])$ needed if white space). examples:

 str1$ = "This is a test value";

MakeCSV(str1$, 1, 0)$ returns

275
 LabTalk Scripting Guide

'This','is','a','test','value'.

 makecsv(col(N),0,0)$ takes a space-

separated string in col(N) and returns a string of

comma-separated values.

This function compares the string find$ with another

string within$ to see whether their contents match
with each other. It returns 1 (True, match) or 0 (False,
not match). Note that wildcard characters "*" and "?"
are supported in the find$ string variable. Optionally
you can use case sensitive check, the option Case
controls case sensitivity: 0 (default) = false, 1 = true.
Match(within$,find$[,Case])
examples:
(2015 SR0)
 str1$ = "From: [email protected]";

str2$ = "F*com"; Match(str1$,str2$);

returns 1.

Search string within$, return an integer corresponding

to the start position of find$ or -1 (not found).
Supports "*"' and "?" wildcards. Option StartPos
specifies the position of the character at which to start
the search: 1 (default) = search from 1st character.
Option Case controls case sensitivity: 0 (default) =
false, 1 = true. examples:

 str1$ = "From: [email protected]";

MatchBegin(within$,find$[,StartPos,Case
]) str2$ = "From*@";

MatchBegin(str1$,str2$,1); returns 1.

 matchbegin(col(a)," ") returns the

starting position of the of the first white space in

col(a) or if none found, returns -1.

Search string within$, return an integer corresponding

MatchEnd(within$, find$[, StartPos,
to the end position of find$ or -1 (not found).
Case])
Supports "*" and "?" wildcards. Option StartPos

276
 Function Reference

specifies the position of the character at which to start

the search: 1 (default) = search from 1st character.
Option Case controls case sensitivity: 0 (default) =
false, 1 = true. examples:

 str1$ = "From: [email protected]";

str2$ = "From*@";

MatchEnd(str1$,str2$,1); returns 11.

 MatchEnd(col(A),col(B)) returns the

ending position of the col(b) string in col(a) or if

no match, returns -1.

Takes a string str$, returns n characters from

StartPos or if n not specified, returns everything from
StartPos. examples:

 str$ = "aabcdef"; Mid(str$,2,3)$

returns abc.

Mid(str$, StartPos [, n])$  str$ = "aabcdef"; Mid(str$,2)$ returns

abcdef.

 mid(col(a),1,3)$ returns the first three

characters of string in col(a).

Replace n characters in str1$, starting from StartPos,

with string replace$. String replace$ may differ in
length from n. examples:

 Replace(abcdefghijklmn,3,5,123456)$

Replace(str1$, StartPos, n, replace$)$ returns ab123456hijklmn.

 replace(col(a),1,4,"Replacement

string ")$ replaces the first four characters in

col(a) with string "Replacement string " (including

277
 LabTalk Scripting Guide

spaces).

Takes a string str$, returns the rightmost n

characters. examples:

 str$ = "abcde"; Right(str$,n)$ returns

Right(str$, n)$ cde.

 right(col(d),8) returns the rightmost 8

characters in the string in col(d).

Returns position of string find$ within string within$,

or if not found returns -1. Not case sensitive. No
wildcards. Option StartPos controls where to start
search (default = 1). examples:

 within$ = "abcde"; find$ = "BC";

Search(within$, find$[, StartPos]) Search(within$,find$) returns 2.

 search(col(c),"sample") returns the

position of the word "sample" in the string in

col(c).

Search string within$ for string find$, replace with

sub$. Option to substitute only the nth found
instance. examples:

 Substitute(abcdefabcdef,12,bcd,0)$

returns a12efa12ef.

Substitute(within$,sub$,find$ [, n])$  substitute(col(c),"experiment:

","expt.",1) searches string in col(a) and

substitutes "experiment: " for "expt.", replacing

only the first instance found.

Converts a double to string. Option fmt$ formats

Text(d[,fmt$])$
output and will take these values; if not specified,

278
 Function Reference

uses column's format settings. Use empty string "" to

use @SD digits. Use "*" to use Origin's global setting.
examples:

 Text(2.01232,"*3")$ returns 2.01.

 Text(Date(7/10/2014),D1)$ returns

Thursday, July 10, 2014.

 text(date(col(b)),D1)$ takes a column of

date data and returns a string in the format of

"Wednesday, March 05, 2014"

Takes string str$, returns substring corresponding to

index iToken. Option iDelimiter is ASCII value of
delimiter: 0 (default) = any white space; 32 = single
space; 124 = "|". Most symbol chars such as '_' (ASCII
95), '|'(ASCII 124) can be directly used as iDelimiter.
examples:

 str1$="This is my string";

Token(str1$,3)$ returns my.

Token(str$,iToken[, iDelimiter])$  token(col(c),2) returns the second token

(as delimited by white space) in the string in

col(c).

 token(col(b), 3, ':') returns the third

token as delimited by colon in the string in col(b).

Note: some symbol chars might not be directly used by

iDelimiter but their ASCII values always apply.
Takes string str$ and removes spaces. Parameter n
controls how space is removed: 0 (default) = leading +
trailing, 1 = remove all. examples:
Trim(str$[, n])$
 str1$ = " abc ABC "; Trim(str1$,0)$

returns abc ABC.

279
 LabTalk Scripting Guide

 trim(col(a),0) returns the string in col(c)

with leading and trailing spaces controlled.

Takes string str$, returns as uppercase. examples:

 str1$ = "abcde"; Upper(str1$)$ returns

ABCDE.
Upper(str$)$
 upper(col(c))$ returns the string in col(c) in

uppercase letters.

Takes string number str$, returns it as double.

examples:

 str$ = "+.50"; Value(str$) returns 0.5.

Value(str$) Note: see the atof() function.

 value(col(e)) takes a string number in col(e)

and returns it as a numeric of type double.

19.2.2 Math Functions

Name Brief Description
Returns the absolute value of x. example:

 abs(-2.5) returns 2.5; abs(0/0) returns --

(missing value);
abs(x)
 abs(col(b)) returns absolute value of every

element in col(b).

Given n1 elements, return the number of combinations of

n2 elements. example:
Combine(n1,n2)
 combine(4,2) returns 6.

280
 Function Reference

 combine(col(a),2 returns the number of

combinations of 2 elements for the value in col(a).

Takes the XY coordinates of two points, returns the

shortest distance. examples:

 distance(0,0,0,1) returns 1.
Distance(px1, py1, px2, py2)
 distance(col(g),col(h),col(i),col(j))

could also return 1.

Takes the XYZ coordinates of two points, returns the

shortest 3D distance. examples:

 distance3d(0,0,1,0,0,2) returns 1.
Distance3D(px1, py1, pz1, px2, py2,
pz2)  distance3d(col(a),col(b),col(c),col(d),c

ol(e),col(f)) could also return 1.

Returns e raised to the x power. Note: x > 667 returns

missing value. examples:

exp(x)  exp(0) returns 1.

 exp(col(a)) returns e raised to the value in col(a).

Returns the factorial of a non-negative integer. Note: n >

170 returns missing value; see the Log_gamma function.
examples:

fact(n)  fact(3) returns 6.

 fact(col(a)) returns factorial of value in col(a).

Returns the double factorial of a non-negative integer.

If n = odd, sequence is 1*3*5...(n-2)*n; if n = even,
factdouble(n)
sequence is 2*4*6...(n-2)*n; if n = 0, evaluates to 1. If n >
299, returns missing value. examples:

281
 LabTalk Scripting Guide

 factdouble(6) returns 48;

 factdouble(col(a)) returns the double factorial of

value in col(a).

Returns the fractional part of a double.

example:
frac(x)
 frac(3.1415) = ; returns 0.1415.

Takes the longitudes and latitudes of two points on a

sphere with radius r, returns the great-circle distances
between them. Option degree determines whether to use
degree or radian as the unit of longitudes and latitudes
HaversineDistance(lon1,lat1,lon2,lat (default is degree). example:
2,r[,degree])
(2017 SR0)  HaversineDistance(120, 30, 0, -60, 5000)

returns 11388.7402734106;

Takes a double x and returns the truncated integer.

examples:

int(x)  int(7.9) returns 7.

 int(col(a)) returns the truncated integer in col(a).

ln(x) Return the natural logarithm of x.

log(x) Return the base 10 logarithm of x.
Returns the integer modulus of integer n divided by integer
m (quotient rounds toward 0). examples:

 mod(16,7) returns 2.
mod(n, m)
 mod(col(a),col(b)) returns the integer modulus

of the value in col(a) divided by the value in col(b).

Returns the integer modulus of integer n divided by integer

mod2(n,m)
m (quotient rounds toward minus infinity). Quotient of ,

282
 Function Reference

which is used to calculate modulus, rounds toward .

When the input(s) are negative, the return may differ from

mod (it calculates quotient of rounds toward 0).

examples:

 mod(5,-3) returns -1

 mod(col(a),col(b)) returns the integer mod2 of

the value in col(a) divided by the value in col(b).

Takes a double x and rounds up/down to the nearest

nint(x) integer. The nint(x) function returns the same result as
round(x, 0).
Takes a value or a dataset, returns it with n significant
figures. examples:

 x = 1234567; prec(x, 3) returns 1230000.

prec(x, n)
 prec(col(b), 3) assigns the values in col(b) to the

target column, to 3 significant figures.

Returns the real modulus of double x divided by double y

(quotient rounds toward 0). Quotient of rounds toward

. examples:

rmod(x, y)  rmod(4.5, 2) returns 0.5.

 rmod(col(a),3) returns the rmod of col(a) divided

by 3.

Returns the real modulus of double x divided by double y

(quotient rounds toward minus infinity). Quotient of

rounds toward . examples:
rmod2(x, y)
 rmod2(-4.5, 2) returns 1.5.

 rmod(col(a),3) returns the rmod2 of col(a) divided

283
 LabTalk Scripting Guide

by 3.

Takes a value or dataset, returns the value or dataset to n

decimal places. Note: Origin 9.1 introduced a new
rounding algorithm. System variable @RNA toggles between
old and new methods (old behavior is @RNA=0; new
behavior is @RNA=1 (default)). examples:
round(x, n)  round(1.156, 1) returns 1.2.

 round(col(a),2) returns the values in col(a),

rounded to 2 decimal places.

Takes a real number x and returns its sign. If x > 0, returns

sign(x)
1; If x < 0, returns -1; If x = 0, returns 0.
sqrt(x) Takes a double x and returns the square root.
Takes a vector vd, returns the derivative of the data list.
Derivative(vd[,n]) No smoothing is performed. Option n is derivative order
(default = 1).
Takes two vectors vx and vy, returns the derivative of the
DerivativeXY(vx, vy [, n])
curve. Option n is derivative order (default = 1).
Integrate(vd) Integrate the area under a curve. Uses the Trapezoid Rule.
Integrate the area under curve (vx, vy). Vector vx contains
IntegrateXY(vx, vy)
x coordinates of curve; vy contains y coordinates.
Takes x coordinates vx and y coordinates vy and
interpolates/extrapolates a y coordinate at a given
coordinate x. Option method = 0 (linear, default), 1 (cubic
Interp(x,vX,vY[,method,bound,smo spline), 2 (cubic B-spline), 3 (Akima spline). When method
oth,extrap]) = 1, bound can equal 0 (natural) or 1 (not-a-knot). When
method = 2, smooth = non-negative value for smoothness.
(2015 SR0)
Option extrap can be applied when X values are outside
reference range: 0 (default) = extrapolate Y using last two
points; 1 = set all Y as missing values; 2 = use the Y value
of the closest input X.

19.2.3 Special Math Functions

Name Brief Description
Beta Function with parameters a and b.
beta(a, b)

284
 Function Reference

Incomplete Beta Function with parameters x, a, b.

incbeta(x, a, b)

The incomplete F-table function. Parameter x is the upper limit

of integration; parameter m is the degrees of freedom of the
incf(x, m, n)
numerator variance; parameter n is the degrees of freedom of the
denominator variance.
Compute Incomplete Gamma function at x, with parameter a.

incgamma(a,x)

where is the value of Gamma function at a. a > 0 and x ≥ 0.

inverf(x) Computes the inverse error function at x.
j0(x) Zero Order Bessel Function.
j1(x) First Order Bessel Function.
Bessel function of order n.

jn(x, n)

where is the gammaln(x) function.

y0(x) Zero order Bessel function of second kind.
y1(x) First order Bessel function of second kind.
nth order Bessel function of second kind.

yn(x, n) where

19.2.4 Trigonometric/Hyperbolic Functions

Note: Angular units (radians, degrees, gradians) depend upon system.math.angularunits property
(also set in Tools: Options: Numeric Format).

Name Brief Description

acos(x) Returns the arccosine of x. If x < -1 or x > 1, missing value ("--") is returned.
Returns the inverse hyperbolic cosine of x. If x is < 1, missing value ("--") is
acosh(x)
returned.
Returns the arccotangent of x. Input x can be any value. Values are returned in the
acot(x)
first or second quadrants.
acoth(x) Returns the inverse hyperbolic cotangent of |x| > 1.
Returns the arccosecant of |x|. If |x| is < 1, returns missing value ("--"). Values are
acsc(x)
returned in the first or fourth quadrants.

285
 LabTalk Scripting Guide

Returns the inverse hyperbolic cosecant of x. If x = 0 or x > ~3E153, returns

acsch(x)
missing value ("--").
Returns the angle (radians), measured between the positive X axis and the line
angle(x, y)
joining a point (x,y) and the origin (0,0).
Takes two pairs of x,y coordinates, returns the angle between the line defined by
the two points and the X axis. Option unit: 0 = radians default) or 1 (degrees);
Option direction: 0 (default) constrains the returned angular value to the first
(+x,+y) and fourth (+x,-y) quadrants; or 1, returns values from 0–2pi radians or 0–
360 degrees. examples:
Angleint1(p
x1, py1,
 angleint1(1,1,3,3,1) returns 45.
px2, py2 [,
unit,  angleint1(col(a),col(b),col(c),col(d),1,1) returns the angle in
direction])
degrees (0 - 360) between the line defined by two pairs of xy coordinates and

the X axis.

Returns the angle between two lines, one with endpoints (px1, py1) and (px2, py2),
the other with endpoints (px3, py3) and (px4, py4). If option unit = 0 (default),
returns radians; if unit = 1 returns degrees. Option direction specifies direction of
return value. If option direction = 0 (default), constrains the returned angular value
Angleint2(p to the first (+x,+y) and fourth (+x,-y) quadrants; if direction = 1, returns values
x1, py1, from 0–2pi radians or 0–360 degrees. examples:
px2, py2,
px3, py3,  angleint2(0,0,1,0,0,1,0,0,1,1) returns 90.
px4, py4 [,
unit,  angleint2(col(a),col(b),col(c),col(d),col(e),col(f),col(g),
direction])
col(h),1,1) returns the angle (degrees, 0 - 360) between two lines defined by

endpoints in col(a) - col(h).

Returns the arcsecant of x. If |x| is < 1, returns missing value ("--"). Values are
asec(x)
returned in the first or second quadrant.
Returns the inverse hyperbolic secant of x. 0 < x ≤ 1. Other values of x return a
asech(x)
missing value ("--").
asin(x) Returns the arcsine of x. -1 ≤ x ≤ 1. Other values of x return a missing value ("--").
asinh(x) Returns the inverse hyperbolic sine of x (any real number).
atan(x) Returns the arctangent of x (any real number).
Takes coordinates x,y (doubles), returns the angle between the positive X axis and
the point (x,y). A variation of the atan(x) function. Returns value between -π and π.
atan2(y,x)
Angle is (+) for counter-clockwise angles (y > 0) and (-) for clockwise angles (y <
0).

286
 Function Reference

Returns the inverse hyperbolic tangent of x. -1 < x < 1. Other values of x return a
atanh(x)
missing value ("--").
cos(x) Returns the cosine of x.
cosh(x) Returns the hyperbolic cosine of x.
cot(x) Returns the cotangent of x.
Returns the hyperbolic cotangent of x. Value x is any non-zero number. Note that
coth(x)
numbers of absolute value > 710 (approx.) return a missing value ("--").
csc(x) Returns the cosecant of x. If x = 0, returns missing value ("--").
Returns the hyperbolic cosecant of x. Value x is any non-zero number. Note: when
csch(x)
x > 710 (approx.), returns a missing value ("--").
Degrees(ang
Takes angle in radians and returns degrees.
le)
Radians(ang
Takes angle in degrees and returns radians.
le)
Returns the secant of x. Note: Do not confuse with the sec() function which returns
secant(x)
the seconds value of a date.
Returns the hyperbolic secant of x. Note that numbers of absolute value > 710
sech(x)
(approx.) return a missing value ("--").
sin(x) Returns the sine of x.
sinh(x) Returns the hyperbolic sine of x.
tan(x) Returns the tangent of x.
tanh(x) Returns the hyperbolic tangent of x.

19.2.5 Date and Time Functions

For an explanation of the Julian-date values as implemeneted in Origin, see Dates and Times in
Origin.
Name Brief Description
Takes a date-time string and returns Julian-date value. If
format$ is not specified, string is interpreted using system short
date format. Can take values 1 = default (MM/dd/yyyy) , 2
(dd/MM/yyyy) or 3 (yyyy/MM/dd) to control format for date
portion of first argument, without specifying format$ string.
examples:
Date(MM/dd/yy[, format$])
and Date(yy,mm,dd)  date(24-09-2009,"dd-MM-yyyy") returns 2455098.

 date(3/5/14) returns 2456721 (US) but date(5/3/14)

returns 2456721 (UK).

 date(2/1/1986 13:13, 2) returns 2446432.5506944

287
 LabTalk Scripting Guide

but date(2/1/1986 13:13, 1) returns

2446462.5506944.

 date(col(a)) returns a Julian-date value for the date-time

string in col(a).

or
Takes doubles yy as year, mm as month, dd as date and returns
the Julian-date value.
Takes a Julian-date value and returns a date string. examples:

 date2str(2456573.123, "dd/MM/yyyy HH:mm")$

returns 08/10/2013 02:57).

Date2str(d,format$)$
 date2str(col(b), "dd/MM/yyyy HH:mm")$ returns a

date string in the format "dd/MM/yyyy HH:mm".

Takes a Julian-date value (double) d and returns a portion of the

date specified by datepart$, as a double. Option n specifies start
of week for datepart$ = w or ww. examples:

 datepart(yyyy, 2457360.5107885) returns 2015.

 datepart(y, Today())=; returns the day number of the

current year (e.g. if today() = 2457363 = 12/7/2015 = 341).

DatePart(datepart$, d [, n])
(2016 SR1)  Datepart(s, col(A))=; returns the seconds portion of

the Julian-day values in column A (e.g. datepart(s,

2457360.5107885) returns 32).

 datepart(w, 2457360.5107885, 1)=; returns 6 but

datepart(w, 2457360.5107885)=; returns 5.

Takes a Julian-date value, returns the day number. If option n =

1, returns 1 to 31 (month); if n = 2, returns 1 to 366 (year).
Day(d, [,n]) examples:

 (Day(2454827.5982639, 2) returns 362.

288
 Function Reference

 day(col(b),1) takes a Julian-date value and returns the

day of the month.

Takes a Julian-date value, returns the hour as an integer. Returns

0 to 23 (0 = 12:00 A.M., 23 = 11:00 P.M.). examples:

 Hour(0.6997854) returns 16.

Hour(d)
 hour(col(b)) returns the hour from Julian-date value in

col(b).

Takes a Julian-date value, returns the minutes as an integer (0 to

59). examples:

 Minute(2454827.5982639) returns 21.

Minute(d)
 minute(col(b)) returns the minute from the Julian-date

value in col(b).

Takes a Julian-date value, returns the month as an integer (0 to

12). examples:

 month(2454821) returns 12.

Month(d)
 month(col(b) returns the month of the Julian-date value in

col(b).

Takes a Julian-date value, returns the month name. Month

format specified by option n: 1 = single character; 3(default) = 3
characters; 0 = full month name; -1 = 3 character English
regardless of language settings. examples:

MonthName(d[,n])$  MonthName(2454827.5982639, 0)$ returns December.

 monthname(col(b),0)$ returns the full month name for

Julian-date values in col(b).

Now() Returns the current date-time as a Julian-date value. examples:

289
 LabTalk Scripting Guide

 time2str(now()-date(col(a)),"HH:mm")$ returns a

time string (HH:mm) elapsed between current time and the

Julian-date value in col(a).

Takes a Julian-date value, returns a quarter of the year.

examples:

 Quarter(2454829.5745718) returns 4.
Quarter(d)
 quarter(col(b)) returns the quarter of the Julian-date

value in col(b).

Takes a Julian-date value or real number, returns the seconds as a

real value in the range 0 to 59.9999... examples:

 second(2454827.5982639) returns 30.00.

Second(d)
 second(col(a)) returns the seconds of a Julian date in

col(a).

Takes either HH,mm,ss or custom date-time string (HH:mm:ss =

default) and returns the Julian-date value. Optional Format$
argument specifies custom string format. examples:

 time(20:50:25) returns 0.8683449; time("2

Time(HH,mm,ss) and
Time(HH:mm:ss[,Format$]) 20,50,25", "DDD hh,mm,ss") returns 2.8683449.

 time(col(a)) returns Julian-date values for time data

formatted as HH:mm:ss in col(a).

Takes a Julian-date value, returns a time string of a specified

format. examples:

Time2str(d,format$)$  time2str(0.1875, "HH:mm")$ returns 04:30.

 time2str(col(b),DDD:HH)$ returns a time string

290
 Function Reference

formatted as DDD:HH.

Today() Returns the current date as a Julian-date value.

Takes a Julian-date value, returns the day of the week. Option n
specifies week start and end values: 0 (default) = Sunday (0-6), 1
= Sunday (1-7), 2 = Monday (0-6), or 3 = Monday (1-7).
examples:

WeekDay(d[,n])  weekday(2454825, 1) returns 5.

 weekday(col(b)) takes Julian-date values in col(b) and

returns the day of the week as a number.

Takes a Julian-date value (including time) or number defined by

n2, returns the weekday. Option n1 controls output string length:
-1 = 3 char cap; 0 = full name, 1st cap; 1 = 1 char cap;
3(default)= 3 char, 1st cap. Option n2 controls week start and end
values: 0 = 0(Sun) - 6(Sat); 1 = 1(Sun) - 7 (Sat); 2 = 0(Mon) -
6(Sun); 3(default) = 1(Mon) - 7(Sat). examples:
WeekDayName(d[,n1,n2])$
 WeekDayName(2454825,-1,0)$ returns THU.

 weekdayname(col(b),3,0)$ returns the day of the week

name, formatted as 3 char, 1st letter cap.

Takes a Julian-date value, returns the calendar week number of

the year (1 to 53). Option to specify week start (Sunday vs
Monday). examples:

 weeknum(date(1/11/2009)) returns 3.

 weeknum(date(col(c))) takes a column of date data

WeekNum(d[,n])
formatted as "MM/dd/yyyy" (col(c)), interprets it as a Julian-

date value using the date() function and then returns a week

number using the weeknum() function.

Takes a Julian-date value, returns the year as an integer(0100-

Year(d)
9999). examples:

291
 LabTalk Scripting Guide

 year(2454821) returns 2008.

 year(date(col(c))) takes a column of date data

formatted as "MM/dd/yyyy" (col(c)), interprets it as a Julian-

date value using the date() function and then returns the

four-digit year.

Takes a Julian-date value, returns year as a string. Form of

string is specified by option n: 0 = 2 digits, 1(default) = 2 digits
preceded by an apostrophe, or 2 = 4 digits. examples:

 YearName(2454827.5982639, 1)$ returns '08.

 yearName(date(col(c)),0)$ takes a column of date

YearName(d[,n])$
data formatted as "MM/dd/yyyy" (col(c)), interprets it as a

Julian-date value using the date() function and then returns

the two-digit year.

19.2.6 Signal Processing Functions

Name Brief Description
Takes a complex vector cx (usually FFT complex result),
returns the amplitude. Option side defines the output spectrum
(1 = one-sided, 2 = two sided and shift). examples:

 fftamp(fftc(col(B)), 2) returns the amplitude of

the FFT complex result(two-sided) of input signal in

fftamp(cx [,side])
(2015 SR1) column B.

 col(C) = col(B)-mean(col(B));

fftamp(fftc(col(C))) returns the amplitude result

with DC offset removed (one-sided).

fftc(cx) Takes a vector cx, returns the complex FFT result. Note that
(2015 SR1) the data type of output column needs to be set as complex (16)

292
 Function Reference

in advance. examples:

 fftc(col(B)) returns the FFT complex result of input

signal in column B

 fftc(rSignal) returns the FFT complex result of input

signal in range variable rSignal

Takes the sampling interval time and signal size n, returns the
frequencies for the FFT result. Option side defines the output
spectrum (1 = one-sided, 2 = two sided), shift defines whether
to shift for two-sided. ( 0 = no shift, 1 = shift).examples:

fftfreq(time, n[, side , shift])  fftfreq(0.001, 100) returns a dataset that starts

(2015 SR1) from 0 to 500 with interval 10 (one-sided, no shift)

 fftfreq(0.01, 100, 2, 1) returns the two-sided

and shifted frequency for sampling interval 0.01.

Takes a complex vector cx (usually FFT complex result),

returns the magnitude. Option side defines the output spectrum
(1 = one-sided, 2 = two sided and shift).examples:

 fftmag(fftc(col(B)), 2) returns the magnitude of

the FFT complex result(two-sided) of input signal in

fftmag(cx [,side])
(2015 SR1) column B.

 col(C) = col(B)-mean(col(B));

fftmag(fftc(col(C))) returns the magnitude result

with DC offset removed (one-sided).

Takes a complex vector cx (usually FFT complex result),

returns the phase. Option side defines the output spectrum (1 =
fftphase(cx[, side, unwrap, one-sided, 2 = two sided and shift), unwrap defines whether to
unit]) unwrap phase angle (0 = wrap, 1 = unwrap), unit defines the
(2015 SR1)
unit (0 = radians, 1 = degrees).examples:

 fftphase(fftc(col(B))) returns the phase of the

293
 LabTalk Scripting Guide

FFT complex result (one-sided, unwrapped, in degrees) of

input signal in column B

 fftphase(fftc(col(B)), 2, 0, 0) returns the

phase of the FFT complex result (two-sided, wrapped, in

radians) of input signal in column B

Takes a complex vector cx (usually FFT complex result or

frequency), returns a shifted vector. Note that the data type of
output column needs to be set as complex (16) in
advance.examples:
fftshift(cx)
(2015 SR1)  fftshift(fftc(col(B))) returns a shifted complex

vector

Takes a complex vector cx (usually shifted FFT result), returns

an unshifted vector. Note that the data type of output column
needs to be set as complex (16) in advance.examples:
ifftshift(cx)
(2015 SR1)  ifftshift(col(B)) returns an unshifted vector, in

which column B contains a complex vector with shift.

Takes a complex vector cx (usually FFT complex result),

returns the inverse FFT result. Note that the data type of output
column needs to be set as complex (16) in advance.examples:
invfft(cx)
(2015 SR1)  invfft(ifftshift(col(B))) returns the inverse FFT

result for shifted FFT complex result in column B.

Takes integers of type(window type) and n(window size),

returns the window signal as a vector of size n.example:
windata(type, n)  windata(2, 50) returns the triangular window signal
(2015 SR1)
with vector size 50

19.2.7 Statistical Functions

294
 Function Reference

Name Brief Description

Takes a vector vd and a conditional con$ and returns the mean of
values satisfying con$. example:

 col(A) = data(1,32); con$ = col(A) > 5 &&

averageif(vd, con$)
(2015 SR0) col(A) < 10; averageif(col(A), con$)=; returns

7.5.

Takes datasets vx and vy, returns the correlation coefficient.

example:

 for(ii=1;ii<=30;ii++) col(1)[ii] = ii;

Correl(vx, vy)
(2015 SR0) col(2)=ln(col(1)); correl(col(A),col(B))=;

returns 0.92064574677971.

Takes a vector vd, returns the number of elements. Option n

specifies element: 0 (default) = all; 1 = numeric; 2 = missing.
example:
Count(vd[,n])  count(col(a),2) might return 22 for number of missing

values.

countif(vd, vcon) Takes a vector vd, returns the count of values satisfying
(2015 SR0) condition vcon.
Takes datasets vx and vy and respective means avex and avey,
returns the covariance. example:

 for(ii=1;ii<=30;ii++) col(1)[ii] = ii;

cov(vx, vy[, avex, avey])
col(2)=ln(col(1)); cov(col(A),col(B))=;

returns 6.8926313172818.

Takes a vector vd, returns the maximum value. example:

Max(vd)
 max(col(A)) returns max value in col(A).

295
 LabTalk Scripting Guide

 max(1,2,3,4,9) returns 9.

Takes a vector vd, returns the average. example:

Mean(vd)  mean(col(A)) returns the average value of col(A).

Takes a vector vd, returns the median. Option n specifies the

interpolation method: 0 (default) = empirical distribution with
averaging; 1 = nearest neighbor; 2 = empirical distribution; 3 =
weighted average right; 4 = weighted average left; 5 = Tukey
hinge). example:
Median(vd[,n])  median(col(A),2) returns the median (as determined

using n = 2). For more on interpolation methods, see

Interpolation of Quantiles.

Min(vd) Takes a vector vd, returns the minimum value.

rms(vd) Takes a vector vd, returns the root mean square.
Takes a vector vd, returns the sum of squares. Sum of squares is
calculated after subtracting some reference value ref from each
value in vd. Option ref defaults to the mean of vd but ref can be
a constant, a dataset or a function. example:

 ss(vd) returns the mean-subtracted sum of squares.

 ss(vd,4) returns the sum of squares, calculated after

subtracting 4 from each member of vd.

Ss(vd [,ref])  ss(vd1,vd2) returns the sum of squares, calculated after

subtracting each member of vd2 from the corresponding

member of vd1.

 AA = 1; BB = 2; ss(vd, AA+BB*x) returns the sum of

squares, calculated after subtracting the line described by

1+2x from vd.

Takes a vector vd, returns the sample standard deviation.

StdDev(vd)
example:

296
 Function Reference

 StdDev(col(A)) returns sample standard deviation.

Takes a vector vd, returns the population standard deviation.

example:
StdDevP(vd)
 StdDevP(col(A)) returns population standard deviation.

sumif(vd, vcon) Takes a vector vd, returns sum of values satisfying condition
(2015 SR0) vcon.
Takes a vector vd, returns the sum of elements. example:

 total(col(a)) returns the sum of all data points in

Total(vd)
column A.

Takes a vector vd, returns a range of averages of each group of

size. If elements of vd is not an even multiple of size, then the
returned average will represent only mod(vdSize,size) elements.
example:
ave(vd, size)
 ave(col(a),5) breaks col(a) into groups of size 5 and

calculates an average for each group.

Takes a vector vd, returns a range of differences between

adjacent elements. The first element in the returned range is
diff(vd)
vd(i+1)-vdi, and so forth. If there are N elements in vd, the
returned range will contain N-1 elements.
Takes a vector vd, returns a dataset which holds the values of the
cumulative sum (from 1 to i, i=1,2,...,N). Its i+1th element is the
sum(vd) sum of the first i elements. The last element of the returned range
or is the sum of all elements in the dataset.
sum(WorksheetName, col1, or
col2) Takes a worksheet name WorksheetName and two column
indices col1 and col2, returns a dataset, which holds the values of
the sum across rows in col1 and col2.
Takes significance level alpha, population standard deviation std
Confidence(alpha, std, size) and sample size, returns the confidence interval for the
population mean. example:

297
 LabTalk Scripting Guide

 confidence(0.05, 1.5, 100) returns

0.29399459768101.

Takes a vector vd, bin width = inc, vd min and vd max, and
histogram(vd, inc, min, max) generates data bins. Data points that fall on the upper edge of a
bin are placed into the next higher bin.
Takes a vector vd, returns the kurtosis. example:

 dataset ds = {1, 2, 3, 2, 3, 4, 5, 6, 4, 8};

Kurt(vd)
kurt(ds) returns 0.39502164502164.

Takes a vector vx, returns the percentile values at each percent

value specified in vy. example:

 DATA1_A = normal(1000); DATA1_B = {1, 5, 25,

50, 75, 95, 99}; DATA1_C =

Percentile(vx, vy)
percentile(DATA1_A, DATA1_B); returns a dataset

DATA1_C that contains the percentiles of a normal

distribution at 1%, 5%...99%.

Takes a sample size n, returns the Quality Control D2 Factor.

example:
QCD2(n)
 QCD2(4) returns 2.05875.

Takes a sample size n, returns the Quality Control D3 Factor.

Factor D3 is the 3-sigma lower control limit in the X bar R chart.
example:
QCD3(n)
 QCD3(10) returns 0.223.

Takes a sample size n, returns the Quality Control D4 Factor.

QCD4(n) Factor D4 is the 3-sigma upper control limit in the X bar R chart.
example:

298
 Function Reference

 QCD4(10) returns 1.777.

Takes a vector vd, returns the skewness (distribution

asymmetry). example:

Skew(vd)  skew(col(a)) returns the skewness of the dataset in

column A.

Takes a vector vd and an integer n = time period, returns a vector

of exponential moving averages. Option method specifies where
calculation begins: 0 (default) = from point n; 1 = from 1st point.
example:

Emovavg(vd,n[,method])  for(ii=1;ii<=30;ii++) col(1)[ii] = ii;

col(3)=emovavg(col(1),10, 1); //method II fills

column 3 with values, calculated using starting point = 1.

Takes a vector vd, an integer n = time period, and returns a

vector of modified moving averages. example:

 for(ii=1;ii<=30;ii++) col(1)[ii] = ii;

Mmovavg(vd,n) col(2)=mmovavg(col(1),10); fills column 2 with a

modified moving average value at each point, starting with

row 10.

Takes a vector vd and returns the moving average of adjacent

ranges [i-back, i+forward], for a point i (i = the current row
number). example:

 for(ii=1;ii<=10;ii++) col(1)[ii] = ii;

Movavg(vd,back,forward)
col(2)=movavg(col(1),0, 2); fills col(2) with adjacent

average values at each point (Note that col(2)[9] =

(col(1)[9]+col(1)[10])/2 and col(1)[10] =

299
 LabTalk Scripting Guide

col(2)[10]).

Takes two vectors v1 and v2 and returns a vector of moving

correlation coefficients of adjacent ranges [i-back, i+forward],
for a point i (i = the current row number). example:

 wcol(4) = MovCoef(wcol(2), wcol(3), 20, 0);

Movcoef(v1,v2,back,forward)
fills the 4th column with moving correlation coefficients of

col(2) and col(3), within the window [i-20. i]

Takes a vector vd and returns the root mean square(RMS) of

adjacent ranges [i-back, i+forward], for a point i (i = the current
row number). example:
Movrms(vd,back[,forward])
(2015 SR2)  col(B)=movrms(col(A),0, 2); fills col(B) with RMS at

each point for data within the window [i, i+2]).

Takes two vectors, vx (independent) and vy (dependent), returns

a vector of moving slope at each point. Optional n specifies
window width (should be > 1). If n is even, 1 will be added.
When n is not specified, the function returns a vector of one
value which is the linear fit slope of the input. example:
Movslope(vx,vy[,n])  col(C)=movslope(col(A),col(B),5); fills col(C) with

slope at each point (first and last two cells are missing

values).

Takes a vector vd and an integer n = time period, returns a vector

of triangular moving averages. example:

 for(ii=1;ii<=30;ii++) col(1)[ii] = ii;

Tmovavg(vd,n)
col(2)=tmovavg(col(1),9); fills col(2) with triangular

moving average values at each point, starting at point = 9.

Takes a vector vd (data to smooth) and vector vw (indexed

Wmovavg(vd,vw)
weight factor), returns a vector of weighted moving averages.

300
 Function Reference

example:

 for(ii=1;ii<=30;ii++) col(1)[ii] = ii;

//data vector

for(ii=1;ii<=10;ii++) col(2)[ii] = ii/10;

//weight vector

col(3)=wmovavg(col(1),col(2));

fills col(3) with the weighted moving average at each point,

starting at point = 10.

19.2.8 Distribution Functions

19.2.8.1 Cumulative Distribution Functions (CDF)
Name Brief Description
Computes beta cumulative distribution function at x, with parameters
a and b.

betacdf(x,a,b)

where is the Beta function.

Computes the lower tail, upper tail and point probabilities in given
value k, associated with a Binomial distribution using the
corresponding parameters in n, p.

binocdf(k,n,p)

Computes the lower tail probability for the bivariate Normal

distribution.
bivarnormcdf(x,y,corre)

Computes the lower tail probability for the chi-square distribution

chi2cdf(x,df)
with real degrees of freedom.

301
 LabTalk Scripting Guide

Computes the F cumulative distribution function at f, with degrees of

freedom of the numerator variance ndf and denominator variance fdf.

fcdf(f,ndf,fdf)

Computes the lower tail probability for gamma variate g with real
degrees of freedom, using shape parameter a and scale parameter b.
gamcdf(g,a,b)

where
Computes the lower tail probabilities in a given value, associated with
a hypergeometric distribution using the corresponding parameters.

hygecdf(k,m,n,l)

where n is the population size, m the number of success states in the

population, and l the number of samples drawn.
Computes the lower tail probabilities in a given value, associated with
a Lognormal distribution using the corresponding parameters mu and
logncdf(x,mu,sigma) sigma.
(2015 SR0)

Computes the cdf with the lower tail of the non-central beta
distribution.

ncbetacdf(x,a,b,lambda) where

which is the central beta probability function or incomplete beta

function.

302
 Function Reference

Computes the probability associated with the lower tail of the non-
central chi-square distribution.

ncchi2cdf(x,f,lambda)

where is a central with degrees of

freedom.
Computes the probability associated with the lower tail of the non-
central digamma or variance-ratio distribution.

= ,
Where
ncfcdf(f,df1,df2,lambda)

and is the beta function.

Computes the lower tail probability for the non-central Student's t-
distribution.

nctcdf(t,df,delta,maxiter)
with

Computes the lower tail probability for the normal cumulative

distribution.
normcdf(x)

Computes the lower tail probabilities in given value k, associated with

a Poisson distribution using the corresponding parameters in lambda.
poisscdf(k,lambda)

Computes the probability associated with the lower tail of the

srangecdf(q,v,group)
distribution of the Studentized range statistic.

303
 LabTalk Scripting Guide

where ,
Computes the cumulative distribution function of Student's t-
distribution.
tcdf(t,df)

Computes the lower tail Weibull cumulative distribution function for

value x using the parameters a and b.

wblcdf(x,a,b)

where is the interval on which the Weibull CDF is not zero.

19.2.8.2 Probability Density Functions (PDF)

Name Brief Description
Returns the probability density function of the beta distribution
with parameters a and b.
betapdf(x,a,b)

with
Returns the probability density function of the binomial
distribution with parameters nt and p.
binopdf(x,nt,p)
(2015 SR0)

where and .
Cauchy probability density function (aka Lorentz distribution).
cauchypdf(x,a,b)
(8.6 SR0)

Returns the probability density function of the exponential

exppdf(x,mu) distribution with mean parameter mu, evaluated at the value x.
(8.6 SR0)

gampdf(x,a,b) Returns the Gamma probability density with parameters a and b.

304
 Function Reference

(8.6 SR0)

To obtain the scale and shape parameters a and b from a Gamma

distributed dataset, you can use estimation function gamfit.
Returns the 2D kernel density at point (x, y) with respect to a
function established by dataset (vx, vy) with scale (wx, wy).
ks2density(x,y,vx,vy,wx,wy)
(2015 SR0)
where n is the number of elements in vector vx or vy, index i
indicates the ith element in vx or vy and optimal scales (wx, wy) are
determined by estimation function kernel2width.
Returns the kernel density at x for a given vector vx with a
bandwidth w.
ksdensity(x,vx,w)
(2015 SR0)
where n is the size of vector vx, index i indicates the ith element in
vector vx and the optimal bandwidth w can be determined by the
estimation function kernelwidth.
Laplace probability density function.

lappdf(x,mu,b)
(8.6 SR0)

Returns values at X of the lognormal probability density function

lognpdf(x,mu,sigma) with distribution parameters mu and sigma.
(8.6 SR0)

Computes the probability density function at each of the values in

X using the normal distribution with mean mu and standard
normpdf(x,mu,sigma) deviation sigma.
(8.6 SR0)

Computes the Poisson probability density function at each of the

poisspdf(x,lambda) values in X using mean parameters in lambda.
(8.6 SR0)

wblpdf(x,a,b) Returns the probability density function of the Weibull

(8.6 SR0) distribution with parameters a and b.

305
 LabTalk Scripting Guide

To obtain the scale and shape parameters a and b from a Weibull

distributed dataset, you can use estimation function wblfit.

19.2.8.3 Inverse Cumulative Distribution Functions (INV)

Name Brief Description
Returns the inverse of the cumulative distribution function for a specified
betainv(p,a,b)
beta distribution.
Computes the inverse of the chi-square cumulative density function for the
corresponding probabilities in X with parameters specified by nu.
chi2inv(p,df)

Computes the inverse of F cumulative density function at p, with parameters

df1 and df2.

finv(p,df1,df2)

where ;
Computes the inverse of Gamma cumulative density function at p , with
parameters a and b.
gaminv(p,a,b)

where ;
Computes the deviate,x, associated with the given lower tail probability,p, of
logninv(p,mu,sig the Lognormal distribution with parameters mu and sigma.
ma)
(2015 SR0)
where
Computes the deviate, x, associated with the given lower tail probability, p,
of the standardized normal distribution.
norminv(p)

where
Computes the deviate, x, associated with the lower tail probability of the
srangeinv(p,v,ir)
distribution of the Studentized range statistic.

306
 Function Reference

Computes the deviate associated with the lower tail probability of Student's t-
distribution with real degrees of freedom.
tinv(p,df)

,
Computes the inverse Weibull cumulative distribution function for the given
probability using the parameters a and b.
wblinv(p,a,b)

19.2.9 Data Generation Functions

Two functions in this category, rnd()/ran() and grnd(), return a value. All the other functions in this
category return a range.
Note: The seeding algorithm for Origin's methods of random number generation was changed for
version 2016. For more information, see documentation for the system variable @ran.

Name Brief Description

Takes two values x1 and x2 and creates a dataset,
ranging from x1 to x2, with an increment inc. If x1 =
x2, function returns inc number of points with values =
x1. Default for inc = 1. examples: col(A) =
data(0,100,5) fills column A with numbers from 0 to
100, by increment = 5.

Data(x1,x2,inc)  col(A) = data(10, 10, 5) fills the first five

rows of column A with the number 10.

 col(A) = data(1,100) fills column A with

numbers from 1 to 100, by increment = 1.

Returns a value from a normally (Gaussian) distributed

sample, with zero mean and unit standard deviation.
The initial value and sequence of values are the same
for each Origin session. No argument is needed.
grnd()
Commonly, the function is used to return a random
value from a normal distribution of known mean and
standard deviation, using the following expression:
grnd()*sd+m. example:

307
 LabTalk Scripting Guide

 aa=grnd()*0.30855+0.45701 might return

0.33882089669989.

Returns a range of npts. Values are random numbers

with normal distribution (zero mean, unit standard
deviation). If seed is omitted, a different seed is used
each time the function is called. Can be used to fill a
column with normally distributed random values, given
a mean and standard deviation: normal(npts)*sd+m.
normal(npts[,seed]) example:

 col(1) = normal(100)*2+5 fills column 1

with 100 random values with mean = 5 and sd = 2.

Returns the generated patterned numeric or text data.

pattern(vd, onerepeat, seqrepeat) will take input string
series vd and repeat each element in vd onerepeat
times and then repeat the whole string series seqrepeat
times. pattern(x1,x2,inc,onerepeat,seqrepeat) will
create a dataset range from x1 to x2 with increment inc,
each element in the dataset will be repeated onerepeat
times and then the whole dataset will be repeated
seqrepeat times. Note that the elements in string series
can be separated by pipe (|), comma(,), or space, or a
pattern(vd, onerepeat, seqrepeat) and range variable. example:
pattern(x1,x2,inc,onerepeat,seqrepeat)
 col(a)=pattern("Origin Lab", 2, 2);

fills column A with "Origin Origin Lab Lab Origin

Origin Lab Lab".

 col(b)=pattern(1,3,1,2,2); fill column B

with "1 1 2 2 3 3 1 1 2 2 3 3".

Returns n random integers having a Poisson

distribution with mean. Optional seed provides a seed
Poisson(n, mean [,seed]) for the number generator. example:

 col(1)=Poisson(100,5,1) fills column 1 with

308
 Function Reference

100 random values having a Poisson distribution

with mean of 5.

Returns a value between 0 and 1 from a uniformly

distributed sample. If option seed is positive, sets the
ran([seed]) and rnd([seed]) seed and returns 0. If seed is ≤ 0 or if no argument is
provided, returns the next number in the random
number sequence.
Returns a range of npts. Option seed can be a value,
data range, delimited string ("|", "," or space) or string
array. If seed is a value, returns uniformly distributed
uniform(npts [,seed]) and random numbers. If seed is a data range or string array,
uniform(npts, vd) returned values are randomly chosen from the data
range or string(s). If seed is omitted, a different seed is
used each time the function is called. This function also
accepts a vector vd as an argument.

19.2.10 Lookup & Dataset Info Functions

Name Brief Description
Takes a vector vd containing masked
data, returns a vector of the indexes of
masked points. example:

 dataset

aa=findmasks(col(b));
Findmasks(vd)
col(d)=aa fills column D with

the row indices of masked data

in column B.

Takes a vector vd of strictly monotonic

data, returns the index of data point d.
If option n = 0 (default) finds the value
that is equal or closest to the value of
Index(d,vd[,n]) d; n = 1 looks for ≤ d; n = 2 looks for ≥
d. If vd is not strictly monotonic or
contains text, returns -2. example:

 index(170,col(1)); returns

309
 LabTalk Scripting Guide

the index of the value in column

1 that is equal or closest to 170.

Takes a vector vd, returns the dataset

index number for first occurrence of
val. If val is not found, the function
returns 0. example:

 list(3, col(A)) searches

List(val,vd)
column A and returns the (row)

index number where the value 3

first occurs.

Searches for string str$ in vector vs

and returns the value in vector vref
(numeric or string) with the same
index. Precision of match is
determined by option. When Case =
0(default), the function is not case
sensitive. example:

lookup(str$, vs, vref[, option, Case]) and lookup(str$,  string str1$ =

vs, vref[, option, Case])$
Lookup("FSA", col(A),
(2015 SR0)
col(B))$; searches for string

FSA in column A and returns

the value in column B that has

the same index number.

Searches for value d in vector vd,

returns value in vref with the same
index number. The return value can be
table(vd, vref, d[, option]) and table(vd, vref$, d[, numeric or string, depending on vref.
option])$ Parameter option modifies search for
(2015 SR0) parameter d: -1 (default) = function
performs linear interpolation on vd vs
vref and returns the interpolated value;
0 = finds nearest value that is ≤ d; 1 =

310
 Function Reference

finds nearest value that is ≥ d; 2 =

finds nearest or equal value.
Takes a vector vd (Y dataset), returns
the row index number of the value in
the X dataset associated with vd, that
is closest to value x. option determines
which index is returned: 0 (default) =
equal or closest from the left; 1 = equal
or closest from the right; 2 = equal or
closest, left or right. Requirements: (1)
vd must be a designated Y column; (2)
name of vd must correspond to an
Xindex(x,vd[,option]) actual Y dataset; (3) the X dataset must
be sorted in ascending order. example:

 xindex(5,book1_g,1)

returns the row index number

for the x value that is equal or to

the right of, (≥) 5.

Takes a vector vd (Y or Z dataset),

returns the corresponding X value at
row number n. example:

 xvalue(20,book4_c) returns
Xvalue(n,vd) the x value associated with

column C at 20th row in column

C of Book4.

Takes a vector vd (dataset), returns the

dataset (xEr/yEr) containing the error
values of vd. example:

Errof(vd)  %a=errof(book1_b)might

return book1_c.

Takes a dataset vd and if vd is plotted

hasx(vd)
against an x dataset in the active

311
 LabTalk Scripting Guide

(graph) layer, returns 1; if not, returns

0. example:

 aa=hasx(book1_b) returns 1

if the active graph layer contains

a plot of column B.

Takes a vector vd and if n = 0, returns

the number of masked points. If n =
data point index number, returns 1 if
masked, 0 if not masked. example:

 ismasked(0,book1_b)

returns 77 if there are 77

IsMasked(n,vd) masked points in dataset

book1_b.

 ismasked(8,book1_b)

returns 0 if point n8 is not

masked, or 1 if it is masked.

Takes a vector name vd which is a Y

dataset with an associated X dataset
and returns a string containing the
name of the X dataset. example:

 %a = xof(book1_b);

book1_c = %a; // e.g.

Xof(vd) after substitution :

book1_c = book1_a puts the

name of the X dataset

associated with the Y dataset in

column B and fills column C with

312
 Function Reference

the X values.

19.2.11 Data Manipulation Functions

Name Brief Description
Takes an input string and returns the ASCII code (decimal) for the
first character in the string. This function does the same thing as
the code function. example:
asc(str$)
 aa = asc($100); aa = returns 36.

Takes two datasets vx and vy, a lag size k and returns the
correlation between the two datasets. Option n is the number of
points. Lag parameter k can be scalar or vector. When k is a vector,
function returns a vector; when a scalar, returns a scalar. example:

corr(vx,vy,k[, n])  corr(col(1),col(2),data(1,10),50) returns the cross-

correlation of the first 50 points of col(1) with col(2), using a lag

size from 1 to 10.

Takes a vector vd, returns dataset of indices of peaks found using

width and minht. width is number of points to each side of the test
point. minht is in Y axis units. A peak at index i is minht greater
peaks(vd, width, minht) than the data value at (i-width) or (i+width). example:

 peaks(col(B), 3, 0.1) returns dataset of peak indices.

Takes a dataset, sorts it in ascending order and returns it. example:

 %a=sort(book4_c); book4_d=%a takes the data in col(C),

sort(vd)
sorts it and fills col(D) with the result.

Replaces a dataset value with another when conditions cnd are

met. Takes a dataset vd, compares each value to val1 with respect
treplace(vd,val1,val2[,
to option cnd and either replaces with val2 (or -val2) when
cnd])
comparison is true; or when false retains value or replaces with
missing value ("--").

313
 LabTalk Scripting Guide

19.2.12 NAG Special Functions

19.2.12.1 Airy
Name Brief Description
airy_ai(x) Evaluates an approximation to the Airy function, Ai(x).
Evaluates an approximation to the derivative of the Airy function
airy_ai_deriv(x)
Ai(x).
airy_bi(x) Evaluates an approximation to the Airy function Bi(x).
Evaluates an approximation to the derivative of the Airy function
airy_bi_deriv(x)
Bi(x).

19.2.12.2 Bessel
Name Brief Description
Bessel i0. Evaluates an approximation to the modified Bessel
bessel_i0(x)
function of the first kind, I0(x).
bessel_i0_scaled(x) Bessel i0 scaled. Evaluates an approximation to
Bessel i1. Evaluates an approximation to the modified Bessel
bessel_i1(x)
function of the first kind, .
bessel_i1_scaled(x) Bessel i1 scaled. Evaluates an approximation to
Bessel i nu. Evaluates an approximation to the modified Bessel
bessel_i_nu(x,n)
function of the first kind I /4 (x)
Bessel i nu scaled. Evaluates an approximation to the modified
bessel_i_nu_scaled(x,n)
Bessel function of the first kind
bessel_j0(x) Bessel j0. Evaluates the Bessel function of the first kind,
Bessel j1. Evaluates an approximation to the Bessel function of the
bessel_j1(x)
first kind
Bessel k0. Evaluates an approximation to the modified Bessel
bessel_k0(x)
function of the second kind,
bessel_k0_scaled(x) Bessel k0 scaled. Evaluates an approximation to
Bessel k1. Evaluates an approximation to the modified Bessel
Bessel_k1(x)
function of the second kind,
bessel_k1_scaled(x) Bessel k1 scaled. Evaluates an approximation to
Bessel k nu. Evaluates an approximation to the modified Bessel
bessel_k_nu(x,n)
function of the second kind
Bessel k nu scaled. Evaluates an approximation to the modified
bessel_k_nu_scaled(x,n)
Bessel function of the second kind
Bessel y0. Evaluates the Bessel function of the second kind, , x >
bessel_y0(x)
0. The approximation is based on Chebyshev expansions.

314
 Function Reference

Bessel y1. Evaluates the Bessel function of the second kind, ,x>
bessel_y1(x)
0. The approximation is based on Chebyshev expansions.

19.2.12.3 Error
Name Brief Description
erf(x) The error function (or normal error integral).
Calculates an approximate value for the complement of the error
erfc(x)
function.
Computes the value of the inverse complementary error function for
erfcinv(dy)
specified y.
erfcx(x) The scaled complementary error function.
erfinv(dy) The inverse error function.

19.2.12.4 Gamma
Name Brief Description

gamma(x)
Gamma function. Evaluates
incomplete_gamma(a,x) Incomplete gamma function.
log_gamma(x) Log gamma function. Evaluates .x > 0.
Polygamma function. Evaluates an approximation to the kth derivative
real_polygamma(x,k)
of the psi function

19.2.12.5 Integral
Name Brief Description
NAG cosine integral function. Evaluates
cos_integral(x)

cumul_normal(x) Evaluates the cumulative Normal distribution function.

Evaluates an approximate value for the complement of the
cumul_normal_complem(x)
cumulative normal distribution function.
NAG elliptical integral of the first kind. Calculates an approximate
elliptic_integral_rc(x,y)
value for the integral
NAG symmetrised elliptic integral of the second kind. Calculates
an approximate value for the integral
elliptic_integral_rd(x,y,z)

NAG symmetrised elliptic integral of the first kind. Calculates an

elliptic_integral_rf(x,y,z)
approximation to the integral

315
 LabTalk Scripting Guide

NAG symmetrised elliptic integral of the third kind. Calculates an

approximation to the integral
elliptic_integral_rj(x,y,z,r)

NAG exponential integral function. Evaluates

exp_integral(x)

NAG Fresnel integral function C. Evaluates an approximation to

fresnel_c(x)
the Fresnel Integral .
NAG Fresnel integral function S. Evaluates an approximation to
fresnel_s(x)
the Fresnel Integral .

sin_integral(x)
NAG sine integral function. Evaluates

19.2.12.6 Kelvin
Name Brief Description
kelvin_bei(x) Evaluates an approximation to the Kelvin function bei x.
kelvin_ber(x) Evaluates an approximation to the Kelvin function ber x.
kelvin_kei(x) Evaluates an approximation to the Kelvin function kei x.
kelvin_ker(x) Evaluates an approximation to the Kelvin function ker x.

19.2.12.7 Miscellaneous
Name Brief Description
NAG Jacobian theta function. Computes the value of one of the
Jacobian theta functions , , , or
jacobian_theta(k,x,q)
for a real argument x and non-negative q ≤ 1..
Calculates an approximate value for the real branches of Lambert's
lambertW(x,branch,offset)
W function.

19.2.13 Fitting Functions

Multi-parameter functions in this category are used as built-in functions for Origin's nonlinear fitter.
You can view the equation, a sample curve, and the function details for each multi-parameter function
by opening the NLFit (Analysis: Fitting: Nonlinear Curve Fit). Then select the function of interest
from the Function selection page.
For additional documentation on all the multi-parameter functions available from Origin's nonlinear
curve fit, see this PDF on the OriginLab website. This document includes the mathematical

316
 Function Reference

description, a sample curve, a discussion of the parameters, and the LabTalk function syntax for each
multi-parameter function.

19.2.13.1 Origin Basic Functions

Name Brief Description
Classical Freundlich Model, has been used in the study of
Allometric1(x,a,b) allometry.

Beta peak function for use in chromatography and

spectroscopy.

Beta(x,y0,xc,A,w1,w2,w3)

Boltzmann Function - produce a sigmoidal curve.

Boltzmann(x, A1, A2, x0, dx)

Double Rectangular Hyperbola Function.

dhyperbl(x,P1,P2,P3,P4,P5)

Two-phase exponential association equation.

ExpAssoc(x,y0,A1,t1,A2,t2)

One-phase exponential decay function with time constant

ExpDec1(x,y0,A1,t1) parameter.

Two-phase exponential decay function with time constant

ExpDec2(x,y0,A1,t1,A2,t2) parameters.

Three-phase exponential decay function with time constant

ExpDec3(x,y0,A1,t1,A2,t2,A3,t3) parameters.

One-phase exponential growth with time offset, x0 should be

ExpGrow1(x,y0,x0,A1,t1) fixed.

Two-phase exponential growth with time offset, x0 should be

ExpGrow2(x, y0, x0, A1, t1, A2, fixed.
t2)

Gauss(x, y0, xc, w, A) Area version of Gaussian Function.

317
 LabTalk Scripting Guide

(y0 = offset, xc = center, w = width, A = area)

Amplitude version of Gaussian peak function.

GaussAmp(x,y0,xc,w,A) (y0 = offset, xc = center, w = width, A = amplitude)

Hyperbola funciton, also the Michaelis-Menten model in

Enzyme Kinetics.
Hyperbl(x, P1, P2)

Logistic dose response in Pharmacology/Chemistry.

Logistic(x, A1, A2, x0, p)

Probability density function of random variable whose

logarithm is normally distributed.
LogNormal(x,y0,xc,w,A)

Lorentzian peak function with bell shape and much wider

tails than Gaussian function.
Lorentz(x, y0, xc, w, A) (y0 = offset, xc = center, w = FWHM, A = area)

Poisson probability density function, a discrete probability

distribution.
Poisson(x,y0,r)

Exponential pulse function(x >= x0 ? y : 0).

Pulse(x, y0, x0, A, t1, P, t2)

Rational function with 1st order of numerator and 1st order

of denominator.
Rational0(x,a,b,c)

Sine wave function oscillates around a specified value.

Sine(x,y0,xc,w,A)

Voigt(x,y0,xc,A,wG,wL) Convolution of a Gaussian function and a Lorentzian

318
 Function Reference

function.
(y0 = offset, xc = center, A =area, wG = Gaussian FWHM, wL
= Lorentzian FWHM)

19.2.13.2 Implicit
Name Brief Description
Implicit circle equation with parameters circle center and radius.
Circle(x,y,xc,yc,r)

Implicit ellipse equation whose major and minor axes coincide with
XY axes.
Ellipse(x,y,xc,yc,a,b)

Modified implicit plane function defined by its normal direction.

PlaneMod(x,y,z,theta,phi,d)

19.2.13.3 Exponential
Name Brief Description
Asymptotic Regression Model - 1st
Asymptotic1(x,a,b,c) parameterization.

Box Lucas model, same as one-phase association

BoxLucas1(x,a,b) equation with zero offset.

a parameterization of Box Lucas Model.

BoxLucas1Mod(x,a,b)

Box Lucas model for two phase.

BoxLucas2(x,a1,a2)

Chapman-Richards function to describe the

Chapman(x,a,b,c) cumulative growth curve.

One-Parameter Exponential Function.

Exp1p1(x,A)

319
 LabTalk Scripting Guide

One-Parameter Exponential Function.

Exp1p2(x,A)

One-Parameter Exponential Function.

Exp1p2Md(x,B)

One-Parameter Exponential Function.

Exp1P3(x,A)

One-Parameter Exponential Function.

Exp1P3Md(x,B)

One-parameter asymptotic exponential function.

Exp1P4(x,A),

Another form of one-parameter asymptotic

Exp1P4Md(x,B) exponential function.

Two-Parameter Exponential Function.

Exp2P(x,a,b)

Two-Parameter Exponential Function.

Exp2PMod1(x,a,b),

Two-Parameter Exponential Function.

Exp2PMod2(x,a,b),

Inverted offset exponential function.

Exp3P1(x,a,b,c),

Another form of inverted offset exponential

Exp3P1Md(x,a,b,c), function.

Exponential function whose exponent is a 2nd

Exp3P2(x,a,b,c), order polynomial.

Two-phase exponential association equation.

ExpAssoc(x,y0,A1,t1,A2,t2)

ExpAssoc1(x,TD,Yb,A,Tau) One-phase exponential association equation.

(2017 SR0)

Biphasic exponential association equation.

ExpAssoc2(x,TD1,TD2,Yb,A1,A2,Tau1,Tau
2)
(2017 SR0)

320
 Function Reference

One-phase exponential association equation with

plateau before exponential begins.
ExpAssocDelay1(x,TD,Yb,A,Tau)
(2017 SR0)

Biphasic exponential association equation with

plateau before exponential begins.
ExpAssocDelay2(x,TD1,TD2,Yb,A1,A2,Tau
1,Tau2)
(2017 SR0)

Exponential growth function with rate constant

Exponential(x,y0,A,R0) parameter.

One-phase exponential decay function with time

ExpDec1(x,y0,A1,t1) constant parameter.

Two-phase exponential decay function with time

ExpDec2(x,y0,A1,t1,A2,t2) constant parameters.

Three-phase exponential decay function with time

ExpDec3(x,y0,A1,t1,A2,t2,A3,t3) constant parameters.

One-phase exponential decay function with time

ExpDecay1(x,y0,x0,A1,t1) offset, x0 should be fixed.

Two-phase exponential decay function with time

ExpDecay2(x, y0, x0, A1, t1, A2, t2) offset, x0 should be fixed.

Three-phase exponential decay function with time

offset, x0 should be fixed.
ExpDecay3(x,y0,x0,A1,t1,A2,t2,A3,t3)

One-phase exponential growth function with time

ExpGro1(x,y0,A1,t1) constant parameter.

Two-phase exponential growth function with time

ExpGro2(x,y0,A1,t1,A2,t2)
constant parameters.

321
 LabTalk Scripting Guide

Three-phase exponential growth function with

ExpGro3(x,y0,A1,t1,A2,t2,A3,t3) time constant parameters.

One-phase exponential growth with time offset, x0

ExpGrow1(x,y0,x0,A1,t1) should be fixed.

Two-phase exponential growth with time offset,

ExpGrow2(x, y0, x0, A1, t1, A2, t2) x0 should be fixed.

Exponential function with three growth and two

decay phases.

ExpGrow3Dec2(x,y0,xc,Ag1,tg1,Ag2,tg2,A
g3,tg3,Ad1,td1,Ad2,td2)
(2015 SR0)

Exponential function with one growth and one

decay phases.
ExpGrowDec(x,y0,xc,Ag,tg,Ad,td)
(2015 SR0)

Exponential Linear Combiantion.

ExpLinear(x,p1,p2,p3,p4)

Langevin function used in paramagnetism with

three parameters.

Langevin(x,y0,xc,C)

Scale modified Langevin function.

LangevinMod(x,y0,xc,C,s)
(2015 SR0)

PIPlatt(x,Pm,alpha) Model of photosynthesis vs. irradiance curve by

(2017 SR0) Platt

322
 Function Reference

Model of photosynthesis vs. irradiance curve with

PIPlatt2(x,Ps,alpha,beta) photoinhibition by Platt
(2017 SR0)

Model of photosynthesis vs. irradiance curve by

PIWebb(x,Pm,alpha) Webb
(2017 SR0)

Monomolecular growth model.

MnMolecular(x,A,xc,k),

Another form of Monomolecular growth model.

MnMolecular1(x,A1,A2,k)

Exponential decay function combined with a linear

Shah(x,a,b,c,r) function.

Exponential growth function with slope at zero for

parameter.
Stirling(x,a,b,k)

Yield-fertilizer model in Agriculture and Learning

YldFert(x,a,b,r) curve in psychology.

Yield-fertilizer model in Agriculture and Learning

YldFert1(x,a,b,k) curve in psychology.

19.2.13.4 Growth/Sigmoidal
Name Brief Description
Biphasic Dose Response Function.

BiDoseResp(x,A1,A2,LOGx01,LOGx02,h1,h2
,p)

Biphasic Hill Equation.

BiHill(x,Pm,Ka,Ki,Ha,Hi)
(2015 SR0)

323
 LabTalk Scripting Guide

Transformed Boltzmann function for IV data.

BoltzIV(x,vhalf,dx,gmax,vrev)

Boltzmann Function - produce a sigmoidal

Boltzmann(x, A1, A2, x0, dx) curve.

Dose-response curve with variable Hill slope

given by parameter 'p'.
DoseResp(x,A1,A2,LOGx0,p)

Double Boltzmann Function, sum of two

Boltzmann functions.
DoubleBoltzmann(x,y0,A,frac,x01,x02,k1,k2)

Hill function to determine ligand concentration

and maximum number of binding sites.
Hill(x,Vmax,k,n)

Modified Hill function with offset.

Hill1(x,START,END,k,n)

Logistic dose response in

Pharmacology/Chemistry.
Logistic(x, A1, A2, x0, p)

Five parameters logistic function.

Logistic5(x,Amin,Amax,x0,h,s)

Michaelis Menten function to describe relation

of concentration of substrate and enzyme
MichaelisMenten(x,Vmax,Km) velocity.

Gompertz Growth Model for Popuplation

SGompertz(x,a,xc,k) Studies, Animal Growth.

Slogistic1(x,a,xc,k) Sigmoidal Logistic function, type 1.

324
 Function Reference

Sigmoidal Logistic function, type 2.

SLogistic2(x,y0,a,Wmax)

Sigmoidal Logistic function, type 3.

SLogistic3(x,a,b,k)

Sigmoidal Richards function, type 1.

SRichards1(x,a,xc,d,k)

Sigmoidal Richards function, type 2.

SRichards2(x,a,xc,d,k)

Sigmoidal Weibull funciton, type 1.

SWeibull1(x,A,xc,d,k)

Sigmoidal Weibull function, type 2.

SWeibull2(x,a,b,d,k)

19.2.13.5 Hyperbola
Name Brief Description
Double Rectangular Hyperbola Function.
Dhyperbl(x,P1,P2,P3,P4,P5)

Hyperbola funciton, also the Michaelis-Menten model in Enzyme

Kinetics.
Hyperbl(x, P1, P2)

Generalized Hyperbola function.

HyperbolaGen(x,a,b,c,d)

Modified hyperbola function.

HyperbolaMod(x,T1,T2)

RectHyperbola(x,a,b) Rectangular Hyperbola Function.

325
 LabTalk Scripting Guide

19.2.13.6 Logarithm
Name Brief Description
Double logarithmic reciprocal function.
Bradley(x,a,b)

Two-parameter Logarithm function.

Log2P1(x,a,b),

Logarithmic transform function.

Log2P2(x,a,b)

Linear logarithmic transform function.

Log3P1(x,a,b,c)

One-parameter logarithm.
Logarithm(x,A)

19.2.13.7 Peak Functions

Name Brief Description
Asymmetric double Sigmoidal function.
Asym2Sig(x,y0,xc,A,w1,w2,w3)

Beta peak function for use in chromatography and

spectroscopy.

Beta(x,y0,xc,A,w1,w2,w3)

Bi-Gaussian peak function used to fit asymmetric peak.

Bigaussian(x,y0,xc,H,w1,w2)

Chesler-Cram Peak Function for use in chromatography.

CCE(x,y0,xc1,A,w,k2,xc2,B,k3,xc
3)

326
 Function Reference

Edgeworth-Cramer Peak Function for use in

chromatography.

ECS(x,y0,xc,A,w,a3,a4)

Particular case of extreme function, Gumbel probability

density function.
Extreme(x,y0,xc,w,A)

Area version of Gaussian Function.

(y0 = offset, xc = center, w = width, A = area)
Gauss(x, y0, xc, w, A)

Amplitude version of Gaussian peak function.

GaussAmp(x,y0,xc,w,A) (y0 = offset, xc = center, w = width, A = amplitude)

FWHM version of Gaussian Function.

(y0 = base, xc = center, A = area, w = FWHM)
Gaussian(x,y0,xc,A,w)

Exponentially modified Gaussian (EMG) peak function for

use in Chromatography.

GaussMod(x,y0,A,xc,w,t0)

Gram-Charlier peak function for use in chromatography.

GCAS(x,y0,xc,A,w,a3,a4)

Giddings(x,y0,xc,w,A) Giddings peak function for use in Chromatography.

327
 LabTalk Scripting Guide

Inverse polynomial peak function with center.

InvsPoly(x,y0,xc,w,A,A1,A2,A3)

Laplace probability density function.

Laplace(x,y0,a,b)

Logistic peak function, also called Hubbert function.

Logistpk(x,y0,xc,w,A)

Probability density function of random variable whose

logarithm is normally distributed.
LogNormal(x,y0,xc,w,A)

Lorentzian peak function with bell shape and much wider

tails than Gaussian function.
Lorentz(x, y0, xc, w, A) (y0 = offset, xc = center, w = FWHM, A = area)

Pearson Type IV distribution for negative discriminant,

suited to model pull distributions.

PearsonIV(x,y0,A,m,v,alpha,lam)

Pearson Type VII peak function is a Lorentz function raised

to a power.

PearsonVII(x,y0,xc,A,w,m)

Pseudo-Voigt function, linear combination of Gaussian

function and Lorentzian function.
PsdVoigt1(x,y0,xc,A,w,mu)
(y0 = offset, xc = center, A = area, w = FWHM, mu = profile
shape factor)

328
 Function Reference

Pseudo-Voigt function, linear combination of Gaussian and

Lorentzian with different FWHM.
(y0 = offset, xc = center, A =area, wG=Gaussian FWHM,
wL=Lorentzian FWHM, mu = profile shape factor)
PsdVoigt2(x,y0,xc,A,wG,wL,mu)

Convolution of a Gaussian function (wG for FWHM) and a

Lorentzian function.

Voigt(x,y0,xc,A,wG,wL)

Amplitude version of Weibull peak function.

Weibull3(x,y0,xc,A,w1,w2)

19.2.13.8 Piecewise
Name Brief Description
Piecewise linear function with two segments.

PWL2(x,a1,k1,xi1,k2)

Piecewise linear function with three segments.

PWL3(x,a1,k1,xi1,k2,xi2,k3)

329
 LabTalk Scripting Guide

19.2.13.9 Polynomial
Name Brief Description
Constant base line function.
Constant(x,y0)

Third order polynomial.

Cubic(x,A,B,C,D)

Line function with slope and intercept.

Line(x,A,B)

Line function with x-intercept and slope for

LineMod(x,a,b) parameters.

Second order polynomial.

Parabola(x,A,B,C)

Poly(x, a0, a1, a2, a3, a4, a5, a6, a7, a8, 9th order polynomial.
a9)
4th order Polynomial function.
Poly4(x,A0,A1,A2,A3,A4)

5th order polynomial function.

Poly5(x,A0,A1,A2,A3,A4,A5)

19.2.13.10 Power
Name Brief Description
Classical Freundlich Model, has been used in the study of allometry.
Allometric1(x,a,b)

An extension of Classical Freundlich Model.

Allometric2(x,a,b,c)

X shifted power function.

Belehradek(x,a,b,c)

Bleasdale-Nelder function for yield-density model.

BlNeld(x,a,b,c,f)

Simplified Bleasdale-Nelder Model.

BlNeldSmp(x,a,b,c)

Farazdaghi-Harris Model for use in yield-density study.

FarazdaghiHarris(x,a,b,c)

FreundlichEXT(x,a,b,c) Extended Freundlich adsorption isotherm equation.

330
 Function Reference

Gunary adsorption isotherm equation.

Gunary(x,a,b,c)

Extended Langmuir adsorption isotherm equation.

LangmuirEXT1(x,a,b,c),

Another form of extended Langmuir adsorption isotherm equation.

LangmuirEXT2(x,a,b,c)

Pareto cumulative distribution function with one parameter, a power

law probability distribution.
Pareto(x,A)

Scaled Pareto function.

Pow2P1(x,a,b),

two-parameter power function.

Pow2P2(x,a,b),

Pareto transform function.

Pow2P3(x,a,b)

One-parameter Power function.

Power(x,A)

Symmetric Power function with offset.

Power0(x,y0,xc,A,P)

Symmetric Power function.

Power1(x,xc,A,P)

Asymmetric Power function.

Power2(x,xc,A,pl,pu)

19.2.13.11 Rational
Name Brief Description
Brunauer-Emmett-Teller (BET) adsorption equation.
BET(x,a,b)

331
 LabTalk Scripting Guide

Modified BET Model.

BETMod(x,a,b)

Holliday Model - a Yield-density model for use in agriculture.

Holliday(x,a,b,c)

extended Holliday Model.

Holliday1(x,a,b,c)

Nelder Model - a Yeild-fertilizer model in agriculture.

Nelder(x,a,b0,b1,b2)

Rational function with 1st order of numerator and 1st order of

denominator.
Rational0(x,a,b,c)

Another form of Rational0 function with constant coefficient in

numerator normalized.
Rational1(x,a,b,c)

Another form of Rational0 function with coefficient of x in denominator

normalized.
Rational2(x,a,b,c)

Another form of Rational0 function with coefficient of x in numerator

normalized.
Rational3(x,a,b,c)

Another form of Rational0 function with sum of constant and a rational

function.
Rational4(x,a,b,c)

Rational function with 1st order of numerator and 2nd order of

denominator.
Rational5(x,a,b,c,d)

two parameter linear reciprocal function.

Reciprocal(x,a,b)

Reciprocal0(x,A) One-parameter (slope) linear reciprocal function.

332
 Function Reference

One-parameter (intercept) linear reciprocal function.

Reciprocal1(x,A)

Another form of Reciprocal function with constant coefficient in

denominator normalized.
ReciprocalMod(x,a,b)

19.2.13.12 Waveform
Name Brief Description
Sawtooth wave, a periodic function consisting of extreme case
asymmetric triangle waves.
SawtoothWave(x,x0,y0,
A,T)

Sine wave function oscillates around a specified value.

Sine(x,y0,xc,w,A)

Damped sine wave, a sinusoidal function whose amplitude decays as

time increases.
SineDamp(x,y0,xc,w,t0,
A)

sine square function.

SineSqr(x,y0,xc,w,A)

Square wave function which is a periodic wave changing between two

levels transitionally.

SquareWave(x,a,b,x0,T)

Modified square wave function with duty cycle which is a periodic

SquareWaveMod( a, b, wave changing between two levels transitionally.
x0, duty, T)
(2016 SR0)

333
 LabTalk Scripting Guide

Piecewise constant function with two segments.

Step(x,A,B,x1)

19.2.13.13 Surface Fitting

Name Brief Description
Chebyshev Series Polynomials.

Chebyshev2D(x,y,z0,A1,A2,B1,B2,C1)

Cosine Series Polynomials.

Cosine(x,y,z0,A1,A2,B1,B2,C1)

Non-Linear Logistic Dose Response Function.

DoseResp2D(x,y,z0,B,C,D,E,F)

2D exponential decay function.

Exponential2D(x,y,z0,B,C,D)

Non-Linear Extreme Value Functions.

Extreme2D(x,y,z0,B,C,D,E,F)

Non-Linear Extreme Value Cumulative Function.

ExtremeCum(x,y,z0,B,C,D,E,F,G,H)

Fourier2D(x,y,z0,a,b,c,d,w1,w2) Sum of sine and cosine functions of two variables.

334
 Function Reference

The Gaussian surface.

Gauss2D(x,y,z0,A,xc,w1,yc,w2)

2D Gaussian cumulative function.

GaussCum(x,y,z0,B,C,D,E,F)

The gaussian surface rotated.

Gaussian2D(x,y,z0,A,xc,w1,yc,w2,theta)

Non-linear Sigmoid (Logistic Cumulative)

Function.
LogisticCum(x,y,z0,B,C,D,E,F)

2D Log Normal function.

LogNormal2D(x,y,z0,B,C,D,E,F,G,H)

Non-linear Sigmoid (Logistic Cumulative)

Function.
Lorentz2D(x,y,z0,A,xc,w1,yc,w2)

2D Parabola function without xy term.

Parabola2D(x,y,z0,a,b,c,d)

335
 LabTalk Scripting Guide

The Plane Surface.

Plane(x,y,z0,a,b)

2D quadratic polynomial.
Poly2D(x,y,z0,a,b,c,d,f)

2D 5th order polynomial without cross terms.

Polynomial2D(x,y,z0,A1,A2,A3,A4,A5,B1,
B2,B3,B4,B5)

2D power function.
Power2D(x,y,z0,B,C,D,E,F)

2D rational function with 3rd order for numerator

Rational2D(x,y,z0,A01,B01,B02,B03,A1,A2 and 3rd order for denominator.
,A3,B1,B2)

2D Taylor series rational function.

RationalTaylor(x,y,z0,A01,B01,B02,C02,A1
,A2,B1,B2,C2)

The Voigt surface.

Voigt2D(x,y,z0,A,xc,w1,yc,w2,mu)

The voigt surface with volume as parameter.

Voigt2DMod(x,y,z0,A,xc,w1,yc,w2,mu)
(2016 SR0)

19.2.13.14 PFW
Name Brief Description
Asymmetric double Sigmoidal function.
Asym2Sig(x,y0,xc,A,w1,w2,w
3)

Bigaussian(x,y0,xc,H,w1,w2) Bi-Gaussian peak function used to fit asymmetric peak.

336
 Function Reference

Breit-Wigner-Fano (BWF) line shape.

BWF(x,y0,xc,H,w,q)

Chesler-Cram Peak Function for use in chromatography.

CCE(x,y0,xc1,A,w,k2,xc2,B,k
3,xc3)

Constrained Gaussian function.

ConsGaussian(x,y0, xc, A, w1,
w2)

Doniach Sunjic function.

DoniachSunjic(x,y0, xc, H, w,
a)

Edgeworth-Cramer Peak Function for use in chromatography.

ECS(x,y0,xc,A,w,a3,a4)

Fraser-Suzuki asymmetric function.

FraserSuzuki(x,y0,xc,A,sig)

Where
,
Area version of Gaussian Function.
(y0 = offset, xc = center, w = width, A = area)
Gauss(x, y0, xc, w, A)

337
 LabTalk Scripting Guide

Amplitude version of Gaussian peak function.

GaussAmp(x,y0,xc,w,A) (y0 = offset, xc = center, w = width, A = amplitude)

FWHM version of Gaussian Function.

(y0 = base, xc = center, A = area, w = FWHM)
Gaussian(x,y0,xc,A,w)

Gaussian-Lorentzian Cross Product function.

Gaussian_LorenCross(x,y0, xc,
A, w, s)

Exponentially modified Gaussian (EMG) peak function for use

in Chromatography.

GaussMod(x,y0,A,xc,w,t0)

Gram-Charlier peak function for use in chromatography.

GCAS(x,y0,xc,A,w,a3,a4)

Haaroff-Van der Linde function.

HVL(x, y0, xc, A, w, d)

Inverse polynomial peak function with center.

InvsPoly(x,y0,xc,w,A,A1,A2,A
3)

Probability density function of random variable whose logarithm

is normally distributed.
LogNormal(x,y0,xc,w,A)

Lorentzian peak function with bell shape and much wider tails
Lorentz(x, y0, xc, w, A) than Gaussian function.
(y0 = offset, xc = center, w = FWHM, A = area)

338
 Function Reference

Pearson Type VII peak function is a Lorentz function raised to a

power.

PearsonVII(x,y0,xc,A,w,m)

Pseudo-Voigt function, linear combination of Gaussian function

and Lorentzian function.
(y0 = offset, xc = center, A = area, w = FWHM, mu = profile shape
factor)
PsdVoigt1(x,y0,xc,A,w,mu)

Pseudo-Voigt function, linear combination of Gaussian and

Lorentzian with different FWHM.
(y0 = offset, xc = center, A =area, wG=Gaussian FWHM,
wL=Lorentzian FWHM, mu = profile shape factor)
PsdVoigt2(x,y0,xc,A,wG,wL,
mu)

Exponential pulse function(x >= x0 ? y : 0).

Pulse(x,y0,x0,A,t1,P,t2)

Schulz Flory distribution function to describe relative ratios of

polymers after a polymerization process.
SchulzFlory(x,y0,xc,w,A)

Sine wave function oscillates around a specified value.

Sine(x,xc,w,A,y0)

Damped sine wave, a sinusoidal function whose amplitude

SineDamp(x,y0,xc,w,t0,A)
decays as time increases.

339
 LabTalk Scripting Guide

， ，
sine square function.
Sinesqr(x,xc,w,A,y0)

Convolution of a Gaussian function (wG for FWHM) and a

Lorentzian function.
(y0 = offset, xc = center, A =area, wG = Gaussian FWHM, wL =
Voigt(x,y0,xc,A,wG,wL) Lorentzian FWHM)

Amplitude version of Weibull peak function.

Weibull3(x,y0,xc,A,w1,w2)

19.2.13.15 Baseline
Name Brief Description
Constant base line function.
Constant(x,y0)

Third order polynomial.

Cubic(x,A,B,C,D)

One-phase exponential decay function with time constant

ExpDec1(x,y0,A1,t1) parameter.

Two-phase exponential decay function with time constant

ExpDec2(x,y0,A1,t1,A2,t2) parameters.

One-phase exponential growth function with time constant

ExpGro1(x,y0,A1,t1) parameter.

One-phase exponential growth with time offset, x0 should be

ExpGrow1(x,y0,x0,A1,t1) fixed.

340
 Function Reference

Two-phase exponential growth with time offset, x0 should be

ExpGrow2(x, y0, x0, A1, t1, A2, fixed.
t2)

Exponential growth function with rate constant parameter.

Exponential(x,y0,A,R0)

Hyperbola funciton, also the Michaelis-Menten model in

Enzyme Kinetics.
Hyperbl(x, P1, P2)

Line function with slope and intercept.

Line(x,A,B)

Monomolecular growth model.

MnMolecular(x,A,xc,k),

Second order polynomial.

Parabola(x,A,B,C)

4th order Polynomial function.

Poly4(x,A0,A1,A2,A3,A4)

5th order polynomial function.

Poly5(x,A0,A1,A2,A3,A4,A5)

Piecewise constant function with two segments.

Step(x,A,B,x1)

19.2.13.16 Chromatograph
Name Brief Description
Chesler-Cram Peak Function for use in chromatography.
CCE(x,y0,xc1,A,w,k2,xc2,B,k3,x
c3)

Edgeworth-Cramer Peak Function for use in chromatography.

ECS(x,y0,xc,A,w,a3,a4)

Gauss(x, y0, xc, w, A) Area version of Gaussian Function.

341
 LabTalk Scripting Guide

(y0 = offset, xc = center, w = width, A = area)

Exponentially modified Gaussian (EMG) peak function for

use in Chromatography.

GaussMod(x,y0,A,xc,w,t0)

Gram-Charlier peak function for use in chromatography.

GCAS(x,y0,xc,A,w,a3,a4)

Giddings peak function for use in Chromatography.

Giddings(x,y0,xc,w,A)

19.2.13.17 Electrophysiology
Name Brief Description
Transformed Boltzmann function for IV data.
BoltzIV(x,vhalf,dx,gmax,vrev)

Boltzmann Function - produce a sigmoidal curve.

Boltzmann(x, A1, A2, x0, dx)

Double Boltzmann Function, sum of two

Boltzmann functions.
DoubleBoltzmann(x,y0,A,frac,x01,x02,k1,k2
)

One-phase exponential decay function with time

ExpDec1(x,y0,A1,t1) constant parameter.

Two-phase exponential decay function with time

ExpDec2(x,y0,A1,t1,A2,t2) constant parameters.

Three-phase exponential decay function with time

ExpDec3(x,y0,A1,t1,A2,t2,A3,t3)
constant parameters.

342
 Function Reference

Area version of Gaussian Function.

(y0 = offset, xc = center, w = width, A = area)
Gauss(x, y0, xc, w, A)

Goldman-Hodgkin-Katz equation for use in cell

membrane physiology.

Goldman(x,b,Nao,Nai,Ki,T)

Hill function to determine ligand concentration

and maximum number of binding sites.
Hill(x,Vmax,k,n)

19.2.13.18 Pharmacology
Name Brief Description
Biphasic Dose Response Function.

BiDoseResp(x,A1,A2,LOGx01,LOGx02,h1,
h2,p)

Biphasic sigmoidal dose response (7 parameters

Biphasic(x,Amin,Amax1,Amax2,x0_1,x0_2, logistic equation).
h1,h2)

Dose-response curve with variable Hill slope

given by parameter 'p'.
DoseResp(x,A1,A2,LOGx0,p)

Michaelis Menten function to describe relation of

concentration of substrate and enzyme velocity.
MichaelisMenten(x,Vmax,Km)

One site direct binding. Rectangular hyperbola,

OneSiteBind(x,Bmax,k1)
connects to isotherm or saturation curve.

343
 LabTalk Scripting Guide

One Site Competition curve. Dose-response curve

with Hill slope equal to -1.
OneSiteComp(x,A1,A2,logx0)

Two sites binding function.

TwoSiteBind(x,Bmax1,Bmax2,k1,k2)

Two sites competition function to describe the

TwoSiteComp(x,A1,A2,logx0_1,logx0_2,fra competition of a ligand for two types of receptors.
ction)

19.2.13.19 Rheology
Name Brief Description
Bingham model to describe viscoplastic fluids exhibiting a yield
Bingham(x,y0,A)
response.
(2015 SR0)

Cross model to describe pseudoplastic flow with asymptotic viscosities

Cross(x,A1,A2,t,m) at zero and infinite shear rates.
(2015 SR0)

Carreau-Yasuda model to describe pseudoplastic flow with asymptotic

Carreau(x,A1,A2,t,a,n) viscosities at zero and infinite shear rates.
(2015 SR0)

Herschel-Bulkley model to describe viscoplastic materials exhibiting a

Herschel(x,y0,K,n)
power-law relationship.
(2015 SR0)

Vogel-Fulcher-Tammann Equation.
VFT(x,A,B,x0)
(2015 SR0)

Mauro-Yue-Ellison-Gupta-Allan Equation.
MYEGA(x,y0,K,C)
(2015 SR0)

19.2.13.20 Enzyme Kinetics

Name Brief Description
CompInhib(x,Vmax,Km,Ki,Ic) Competitive inhibition model for single substrate

344
 Function Reference

(2015 SR0) and single inhibitor.

Note that this function is usually used in global fit,

Vmax, Km and Ki should be shared, and Ic should
be fixed for each dataset. The initial value of Ki can
be the mean of Ic.
Noncompetitive inhibition model for single
substrate and single inhibitor.

NoncompInhib(x,Vmax,Km,Ki,Ic)
(2015 SR0)
Note that this function is usually used in global fit,
Vmax, Km and Ki should be shared, and Ic should
be fixed for each dataset. The initial value of Ki can
be the mean of Ic.
Uncompetitive inhibition model for single
substrate and single inhibitor.

UncompInhib(x,Vmax,Km,Kia,Ic)
(2015 SR0)
Note that this function is usually used in global fit,
Vmax, Km and Kia should be shared, and Ic
should be fixed for each dataset. The initial value
of Kia can be the mean of Ic.
A general equation including competitive,
uncompetitive and noncompetitive inhibition as
special cases.
MixedModelInhib(x,Vmax,Km,Ki,Alpha,Ic)
(2015 SR0)
This fitting function is for global fitting. When using
it, Vmax, Km, Ki, and Alpha are shared, while Ic is
a fixed constant. The initial value of Ki can be the
mean of Ic.
Substrate inhibition model at high concentrations.
SubstrateInhib(x,Vmax,Km,Ki)
(2015 SR0)

Michaelis Menten function to describe relation of

concentration of substrate and enzyme velocity.
MichaelisMenten(x,Vmax,Km)

Hill function to determine ligand concentration

Hill(x,Vmax,k,n)
and maximum number of binding sites.

345
 LabTalk Scripting Guide

19.2.13.21 Spectroscopy
Name Brief Description
Amplitude version of Gaussian peak function.
GaussAmp(x,y0,xc,w,A) (y0 = offset, xc = center, w = width, A = amplitude)

Inverse polynomial peak function with center.

InvsPoly(x,y0,xc,w,A,A1,A2,A3
)

Lorentzian peak function with bell shape and much wider tails
than Gaussian function.
Lorentz(x, y0, xc, w, A) (y0 = offset, xc = center, w = FWHM, A = area)

Pearson Type VII peak function is a Lorentz function raised to

a power.

PearsonVII(x,y0,xc,A,w,m)

Pseudo-Voigt function, linear combination of Gaussian

function and Lorentzian function.
(y0 = offset, xc = center, A = area, w = FWHM, mu = profile
shape factor)
PsdVoigt1(x,y0,xc,A,w,mu)

Pseudo-Voigt function, linear combination of Gaussian and

Lorentzian with different FWHM.
(y0 = offset, xc = center, A =area, wG=Gaussian FWHM,
wL=Lorentzian FWHM, mu = profile shape factor)
PsdVoigt2(x,y0,xc,A,wG,wL,mu
)

346
 Function Reference

Convolution of a Gaussian function (wG for FWHM) and a

Lorentzian function

Voigt(x,y0,xc,A,wG,wL)

19.2.13.22 Statistics
Name Brief Description
Exponential growth function with rate constant parameter.
Exponential(x,y0,A,R0)

Exponential cumulative distribution function.

ExponentialCDF(x,y0,A,mu)
(2016 SR0)

Particular case of extreme function, Gumbel probability

density function.
Extreme(x,y0,xc,w,A)

Gamma cumulative distribution function.

GammaCDF(x,y0,A1,a,b)
(2016 SR0)

Area version of Gaussian Function.

(y0 = offset, xc = center, w = width, A = area)
Gauss(x, y0, xc, w, A)

Amplitude version of Gaussian peak function.

GaussAmp(x,y0,xc,w,A) (y0 = offset, xc = center, w = width, A = amplitude)

Transformed Gumbel cumulative distribution function.

Gumbel(x,a,b)

Laplace probability density function.

Laplace(x,y0,a,b)

347
 LabTalk Scripting Guide

Logistic dose response in Pharmacology/Chemistry.

Logistic(x, A1, A2, x0, p)

Probability density function of random variable whose

logarithm is normally distributed.
LogNormal(x,y0,xc,w,A)

LognormalCDF cumulative distribution function.

LognormalCDF(x,y0,A,xc,w)
(2016 SR0)

Lorentzian peak function with bell shape and much wider

tails than Gaussian function.
Lorentz(x, y0, xc, w, A) (y0 = offset, xc = center, w = FWHM, A = area)

Pareto cumulative distribution function with one parameter, a

power law probability distribution.
Pareto(x,A)

Pareto function with two parameters.

Pareto2(x,a,b)

Pearson Type IV distribution for negative discriminant,

suited to model pull distributions.

PearsonIV(x,y0,A,m,v,alpha,lam)

Poisson probability density function, a discrete probability

distribution.
Poisson(x,y0,r)

Rayleigh cumulative distribution function.

Rayleigh(x,b)

Weibull probability density function.

Weibull(x,y0,a,r,u)

348
 Function Reference

Weibull cumulative distribution function.

WeibullCDF(x,y0,A1,a,b)
(2016 SR0)

19.2.13.23 Quick Fit

Name Brief Description
Boltzmann Function - produce a sigmoidal curve.
Boltzmann(x, A1, A2, x0, dx)

Dose-response curve with variable Hill slope given by parameter

'p'.
DoseResp(x,A1,A2,LOGx0,p)

One-phase exponential decay function with time offset, x0

ExpDecay1(x,y0,x0,A1,t1) should be fixed.

One-phase exponential growth with time offset, x0 should be

ExpGrow1(x,y0,x0,A1,t1) fixed.

Area version of Gaussian Function.

(y0 = offset, xc = center, w = width, A = area)
Gauss(x, y0, xc, w, A)

Hill function to determine ligand concentration and maximum

number of binding sites.
Hill(x,Vmax,k,n)

Hyperbola funciton, also the Michaelis-Menten model in

Enzyme Kinetics.
Hyperbl(x, P1, P2)

Logistic dose response in Pharmacology/Chemistry.

Logistic(x, A1, A2, x0, p)

Lorentzian peak function with bell shape and much wider tails
Lorentz(x, y0, xc, w, A) than Gaussian function.
(y0 = offset, xc = center, w = FWHM, A = area)

349
 LabTalk Scripting Guide

Sine wave function oscillates around a specified value.

Sine(x,y0,xc,w,A)

Convolution of a Gaussian function (wG for FWHM) and a

Lorentzian function.

Voigt(x,y0,xc,A,wG,wL)

19.2.14 Miscellaneous
Name Brief Description
BitAND(n1, n2) Returns bitwise AND operation of two integers.
BitOR(n1, n2) Returns bitwise OR operation of two integers.
BitXOR(n1, n2) Returns bitwise XOR operation of two integers.
ISNA(d) Determines whether the number is a NANUM.
isText(str$) Determine whether a value is a text. Return 1 for text; return 0 for
(2015 SR0) numeric value or NANUM.
NA() Returns NANUM.
xf_get_last_error_code() Get the last error code value of XFunction engine.
xf_get_last_error_message()$ Get the last error string message of XFunction engine.

19.2.15 Engineering
Name Brief Description
Bin2Dec(str$) Convert a binary number to decimal.
Convert(d,str1$,str2$) Convert a number from one measurement system to another.
Convert a decimal number to binary. The input range is limited to -512 to
Dec2Bin(n)$
511.
Dec2Hex(n)$ Convert a decimal number to hexadecimal.
Hex2Dec(str$) Convert a string representation of a hexadecimal number to decimal.

19.2.16 Complex
Name Brief Description
Imabs(c) Get the modulus of a complex number.

350
 Function Reference

Imaginary(c) This function is used to get the imaginary part of a complex number.
Imargument(c) Get the argument (theta) of a complex number.
Imatan(c)
Calculate the inverse tangent of a complex number.
(2016 SR0)
Imatanh(c)
Calculate the inverse hyperbolic tangent of a complex number.
(2016 SR0)
Imconjugate(c) Get the conjugate of a complex number.
Calculate the cosine value for a complex number.

Imcos(c)
where C is a complex, and .
Imdiv(c1,c2) Calculate the complex division.
Calculate the exponential value for a complex number.
Imexp(c)
where .
Calculate the natural logarithm of the complex number.
Imln(c)
where ImAbs computes the modulus of the complex,
Calculate the base 10 logarithm of a complex number.

Imlog10(c)
where ImLn computes the natural logarithm of the complex, and
.
Calculate the base 2 logarithm of a complex number.

Imlog2(c)
where ImLn computes the natural logarithm of the complex, and
.
ImPower(c,d) Calculate the given complex to the power of the specified value.
Perform the product (multiplication) operation of two complex
numbers.
Improduct(c1,c2)

ImReal(c) Get the real part of the specified complex number.

Calculate the sine value for a complex number.

Imsin(c)
where C is complex, and .

351
 LabTalk Scripting Guide

Imsqrt(c) Calculate the square root of a complex number.

ImSub(c1,c2) Perform subtraction between two complex numbers.
ImSum(c1,c2) Get sum of two specified complex numbers.
Convert the specified two reals into a complex number. Note that the
data type of output column needs to be set as complex (16) in
advance. examples:

 real2complex(1, 2) returns complex number 1 + 2i

Real2Complex(real,imag)  real2complex(col(A), col(B)) returns a complex vector,

the real part uses values from column A, imaginary part from

column B

19.2.17 Notes on Use

Each function returns either a single value or a range of values (a dataset), depending on the type of
function and the arguments supplied. Unless otherwise specified, all functions will return a range if
the first argument passed to the function is a range, and all functions will return a value if a value is
passed.

19.3 LabTalk-Supported X-Functions

Below are several X-Functions, arranged by category, that are used frequently in LabTalk script.

This is not a complete list of X-Functions in Origin, but only those supported by
LabTalk! For a complete listing of all X-Functions, arranged by category and
alphabetical, see the X-Function Reference.

19.3.1 Data Exploration

Name Brief Description

addtool_curve_deriv Place a rectangle on the plot to perform differentiation

addtool_curve_fft Add a rectangle onto the plot to perform FFT

addtool_curve_integ Attach a rectangle on the plot to perform integration

addtool_curve_interp Place a rectangle on the plot to perform interpolation

addtool_curve_stats Place a rectangle onto the plot to calculate basic statistics

addtool_quickfit Place a rectangle onto the plot to do fitting

352
 Function Reference

Region Statistics:Place a rectangle or circle onto the plot to calculate

addtool_region_stats
basic statistics

dlgRowColGoto Go to specified row and column

imageprofile Open the Image Profile dialog.

vinc Calculate the average increment in a vector

vinc_check Calculate the average increment in a vector

19.3.2 Data Manipulation

Name Brief Description

addsheet Set up data format and fitting function for Assays Template

Assays Template Configuration:Set up data format and fitting function for

assays
Assays Template

copydata Copy numeric data

cxt Shift the x values of the active curve with different mode

levelcrossing Get x coordinate crossing the given level

m2v Convert a matrix to a vector

map2c Combine an amplitude matrix and a phase matrix to a complex matrix.

mc2ap Convert complex numbers in a matrix to amplitudes and phases.

mc2ri Convert complex numbers in a matrix into their real parts and imaginary parts.

mcopy Copy a matrix

mks Get data markers in data plot

Convert a matrix layer with multiple matrix objects to a matrix page with
mo2s
multiple matrix layers.

mri2c Combine real numbers in two matrices into a complex matrix.

Merge (move) multiple matrix sheets into one single matrix sheet with multiple
ms2o
matrixobjects.

newbook Create a new workbook or matrix book

newsheet Create new worksheet.

rank Decide whether data points are within specified ranges

353
 LabTalk Scripting Guide

reducedup Reduce Duplicate X Data

reduce_ex Average data points to reduce data size and make even spaced X

reducerows Reduce every N points of data with basic statistics

reducexy Reduce XY data by sub-group statistics according to X's distribution

Subtract the active plot from a straight line formed with two points picked on the
subtract_line
graph page

subtract_ref Subtract on one dataset with another

trimright Remove missing values from the right end of Y columns

v2m Convert a vector to matrix

vap2c Combine amplitude vector and phase vector to form a complex vector.

Convert a complex vector into a vector for the amplitudes and a vector for the
vc2ap
phases.

vc2ri Convert complex numbers in a vector into their real parts and imaginary parts.

vfind Find all vector elements whose values are equal to a specified value

Construct a complex vector from the real parts and imaginary parts of the
vri2c
complex numbers

vshift Shift a vector

xy_resample Mesh within a given polygon to resample data.

xyz_resample Resample XYZ data by meshing and gridding

19.3.2.1 Gridding

Name Brief Description

m2w Convert the Matrix data into a Worksheet

r2m Convert a range of worksheet data directly into a matrix

Convert the worksheet data directly into a matrix, whose coordinates can be
w2m
specified by first column/row and row labels in the worksheet.

wexpand2m Convert Worksheet to Matrix by expand for columns or rows

XYZ2Mat Convert XYZ worksheet data into matrix

xyz_regular Regular Gridding

354
 Function Reference

xyz_renka Renka-Cline Gridding Method

xyz_renka_nag NAG Renka-Cline Gridding Method

xyz_shep Modified Shepard Gridding Method

xyz_shep_nag NAG Modified Shepard Gridding Method

xyz_sparse Sparse Gridding

xyz_tps Thin Plane Spline interpolation

19.3.2.2 Matrix

Name Brief Description

mCrop Crop matrix to a rectangle area

mdim Set the dimensions and values of XY coordinates for the active matrix

mexpand Expand for every cell in the active matrix according to the column and row factors

mflip Flip the matrix horizontally or vertically

mproperty Set properties of the active matrix

mreplace Replace cells in the active matrix with specified datamreplace

mrotate90 Rotates the matrix 90/180 degreesmrotate90

msetvalue Assign each cell in the active matrix from the user definited formula

mshrink Shrink matrix according shrinkage factors

mtranspose Transpose the active matrix

19.3.2.3 Plotting

Name Brief Description

plotbylabel Plot a multiple-layers graph by grouping on column labels

plotgroup Plot by page group, layer group, and data group

plotmatrix Plot scatter matrix of the dataset

plotmyaxes Customize Multi-Axes plot

plotstack Plot stacked graph

plotxy Plot XY data with specific properties

355
 LabTalk Scripting Guide

Plot color fill surfaces or colormap surfaces for all matrix objects in the specified
plotms
matrix sheet.

plotvm Plot from a range of cells in worksheet as a virtual matrix

19.3.2.4 Worksheet

Name Brief Description

colcopy Copy columns with format & headers

colint Set Sampling Interval (Implicit X) for selected Y columns

colmask Mask a range of columns based on some condition

colmove Move selected columns

Show X column (extract Sampling Interval) for the selected Y

colshowx
column(s)

colswap Swap the position of two selected columns

filltext Fill the cell in the specified range with random letters

getresults Get the result tree

insertArrow Insert arrow

insertGraph Insert a graph into a worksheet cell

insertImg Insert images from files

insertNotes Embed a Notes page into a worksheet cell

insertSparklines Insert sparklines into worksheet cells

insertVar Insert Variables into cells

merge_book Merge the workbooks to a new workbook.

sparklines Add thumbnail size plots of each Y column above the data

updateEmbedGraphs Update the embedded Graphs in the worksheet.

updateSparklines Add thumbnail size plots of each Y column above the data

w2xyz Convert formatted data into XYZ form

wautofill Worksheet selection auto fill

wautosize Resize the worksheet by the column maximal string length.

356
 Function Reference

Set cell(s) color to fill color or set the selected character font color to
wcellcolor
Font color.

wcellformat Format the selected cells

wcellmask Set cell(s) mask in specified range

wcellsel Select cell(s) with specified condition

wclear Worksheet Clear

wcolwidth Update the width of columns in worksheet

wcopy Create a copy of the specified worksheet

Remove Duplicated Rows:Remove rows in a worksheet based on

wdeldup
duplications in one column

wdelrows Delete specified worksheet rows

Hold Duplicated Rows:Hold rows in a worksheet based on

wkeepdup
duplications in one column

wks_update_link_table Update the contents in the worksheet to the linked table on graph

Copy XY data from one worksheet to another and merge mismatching

wmergexy
X by inserting empty rows when needed

wmove_sheet Move the specified worksheet to the destination workbook

wmvsn Reset short names for all columns in worksheet

wpivot Pivot Table:Create a pivot table to visualize data summarization

wproperties Get or set the worksheet property through a tree from script

wrcopy Worksheet Range Copy with options to copy labels

wreplace Find and replace cell value in a worksheet

wrow2label Set Label Value

wrowheight Set row(s) height

wsort Sort an entire worksheet or selected columns

wsplit_book Split specific workbooks into multiple workbooks with single sheet

wtranspose Transpose the active worksheet

wunstackcol UnStack grouped data into multiple columns

357
 LabTalk Scripting Guide

wxt Worksheet Extraction

19.3.3 Database Access

Name Brief Description

dbEdit Create/Edit/Remove/Load Query

dbImport Import data from database through the query

dbInfo Show database connection information

dbPreview Import to certain top rows for previewing the data from the query

19.3.4 Fitting

Name Brief Description

findBase Find Baseline region in XY data

fitcmpdata Compare two datasets to the same fit model

fitcmpmodel Compare two fit models to the same dataset

fitLR Simple Linear Regression for LabTalk usage

fitpoly Polynomial fit for LabTalk usage

getnlr Get NLFit tree from a fitting report sheet

nlbegin Start a LabTalk nlfit session

nlbeginm Start a LabTalk nlfit session on matrix data

Start a LabTalk nlfit session and fit multiple dependent/independent variables

nlbeginr
function.

nlbeginz Start a LabTalk nlfit session on xyz data

nlend Terminate an nlfit session

nlfit Iterate the nl fit session

nlfn Set Automatic Parameter Initialization option

nlgui Control NLFIT output quantities and destination.

nlpara Open the Fitting Parameter dialog.

358
 Function Reference

19.3.5 Graph Manipulation

Name Brief Description

Paste a graph from existing graphs as an EMF object onto a layout

add_graph_to_graph
window

add_table_to_graph Add a linked table to graph

add_wks_to_graph Paste a worksheet from existing worksheets onto a layout window

add_xyscale_obj Add a new XY Scale object to the layer

axis_scrollbar Add a scrollbar object to graph to allow easy zooming and panning

Add a pair of inverted triangles to the bottom X-Axis that allows easy
axis_scroller
rescaling

g2w Move graphs into worksheet

For a given X value, find all Y values from all curves and add them as a
gxy2w
row to a worksheet

layadd Create a new layer on the active graph

layalign Align some destination layers according to the source layer.

layarrange Arrange the layers on the graph.

laycolor Fill layer background color

laycopyscale Copy scale from one layer to another layer

layextract Extract specified layers to separate graph windows

laylink Link several layers to a layer.

laymanage Manage the organization of layers in the active graph

laysetfont Fix the display scaling of text in the layer(s) to one.

laysetpos Set position of one or more graph layers.

laysetratio Set ratio of layer width to layer height.

laysetscale Set axes scales for graph layers.

laysetunit Set unit for graph layers.

layswap Swap the positions of two graph layers.

laytoggle Toggle the left axis and bottom axis on and off.

359
 LabTalk Scripting Guide

layzoom Center zooms on layer

legendupdate Update or reconstruct legend on the graph page/layer

merge_graph Merge selected graph windows into one graph

newinset Create a new graph page with insets

newpanel Create a new graph with panels

Apply Palette to &Color Map:Apply palette to the specified graph with an

palApply
existing palette file

pickpts Pick XY data points from a graph

speedmode Set speed mode properties

19.3.6 Image
19.3.6.1 Adjustments

Name Brief Description

imgAutoLevel Apply auto leveling to image

imgBalance Balance the color of image

imgBrightness Adjust the brightness of Image

imgColorlevel Apply user-defined color leveling to image

imgColorReplace Replace color within pre-defined color range

imgContrast Adjust contrast of image

imgFuncLUT Apply lookup table function to image

imgGamma Apply gamma correction to image

imgHistcontrast Adjust the contrast of image, using histogram to calculate the median.

imgHisteq Apply histogram equalization

imgHue Adjust hue of image

imgInvert Invert image color

imgLevel Adjust the levels of image

imgSaturation Adjust Saturation of image

360
 Function Reference

19.3.6.2 Analysis

Name Brief Description

imgHistogram Image histogram

19.3.6.3 Arithmetic Transform

Name Brief Description

imgBlend Blend two images into a combined image

imgMathfun Perform math function on image pixel values with a factor

imgMorph Apply morphological filter to numeric Matrix or grayscale/binary image

imgPixlog Perform logic operation on pixels

imgReplaceBg Replace background color

imgSimpleMath Simple Math operation between two Images

imgSubtractBg Subtract image background

19.3.6.4 Conversion

Name Brief Description

img2m Convert a grayscale image to a numeric data matrix

imgAutoBinary Auto convert to binary

imgBinary Convert to binary

imgC2gray Convert to a grayscale image

imgDynamicBinary Convert to binary using dynamic threshold

imgInfo Print out the given image's basic parameters in script window

imgPalette Apply palette to image

imgRGBmerge Merge RGB channels to recombine a color image

imgRGBsplit Split color image into R,G, B channels

imgThreshold Convert part of an image to black and white using threshold

m2img Convert a numeric matrix to a grayscale image

19.3.6.5 Geometric Transform

361
 LabTalk Scripting Guide

Name Brief Description

imgCrop Crop image to a rectangle area

imgFlip Flip the image horizontally or vertically

imgResize Resize image

imgRotate Rotates an image by a specified degree

imgShear Shear the image horizontally or vertically

imgTrim Trim image with auto threshold settings

19.3.6.6 Spatial Filters

Name Brief Description

imgAverage Apply average filter to image

imgClear Clear the image

imgEdge Detecting edges

imgGaussian Apply Gaussian filter

imgMedian Apply median filter

imgNoise Add random noise to image

imgSharpen Increase or decrease image sharpness

imgUnsharpmask Apply unsharp mask

imgUserfilter Apply user defined filter

19.3.7 Import and Export

Name Brief Description

batchProcess Batch processing with Analysis Template to generate summary report

expASC Export worksheet data as ASCII file

expGraph Export graph(s) to graphics file(s)

expImage Export the active Image into a graphics file

expMatASC Export matrix data as ASCII file

362
 Function Reference

expNITDM Export workbook data as National Instruments TDM and TDMS files

expPDFw Export worksheet as multipage PDF file

expWAV Export data as Microsoft PCM wave file

expWks Export the active sheet as raster or vector image file

img2GIF Export the active Image into a gif file

impASC Import ASCII file/files

impBin2d Import binary 2d array file

impCDF Import CDF file. It supports the file version lower than 3.0

impCSV Import csv file

impDT Import Data Translation Version 1.0 files

impEDF Import EDF file

Import EarthProbe (EPA) file. Now only EPA file is supported for EarthProbe
impEP
data.

impExcel Import Microsoft Excel 97-2007 files

impFamos Import Famos Version 2 files

impFile Import file with pre-defined filter.

impHDF5 Import HDF5 file. It supports the file version lower than 1.8.2

impHEKA Import HEKA (dat) files

impIgorPro Import WaveMetrics IgorPro (pxp, ibw) files

impImage Import a graphics file

impinfo Read information related to import files.

impJCAMP Import JCAMP-DX Version 6 files

impJNB Import SigmaPlot (JNB) file. It supports version lower than SigmaPlot 8.0.

impKG Import KaleidaGraph file

impMatlab Import Matlab files

Import ETAS INCA MDF (DAT, MDF) files. It supports INCA 5.4 (file version
impMDF
3.0).

363
 LabTalk Scripting Guide

Import Minitab file (MTW) or project (MPJ). It supports the version prior to
impMNTB
Minitab 13.

impNetCDF Import netCDF file. It supports the file version lower than 3.1.

impNIDIAdem Import National Instruments DIAdem 10.0 dat files

Import National Instruments TDM and TDMS files(TDMS does not support
impNITDM
data/time format)

impODQ Import *.ODQ files.

Import pCLAMP file. It supports pClamp 9 (ABF 1.8 file format) and pClamp 10
imppClamp
(ABF 2.0 file format).

impSIE Import nCode Somat SIE 0.92 file

impSPC Import Thermo File

impSPE Import Princeton Instruments (SPE) file. It supports the version prior to 2.5.

impWav Import waveform audio file

insertImg2g Insert Images From Files:Insert graphic file(s) into Graph Window

plotpClamp Plot pClamp data

reimport Re-import current file

19.3.8 Mathematics
Name Brief Description

avecurves Average or concatenate multiple curves

averagexy Average or concatenate multiple curves

bspline Perform cubic B-Spline interpolation and extrapolation

csetvalue Setting column value

differentiate Calculate derivative of the input data

filter2 Apply customized filter to a Matrix

integ1 Perform integration on input data

integ2 Calculate the volume beneath the matrix surface from zero panel.

Perform 1D interpolation or extrapolation on a group of XY data to find Y at given

interp1
X values using 3 alternative methods.

364
 Function Reference

interp1q Perform linear interpolation and extrapolation

interp1trace Perform trace/periodic interpolation on the data

Perform 1D interpolation/extrapolation on a group of XY data to generate a set of

interp1xy
interpolated data with uniformly-spaced X values using 3 alternative methods.

interp3 Perform 3D interpolation

interpxyz Perform trace interpolation on the XYZ data

marea Calculate the area of the matrix surface

mathtool Perform simple arithmetic on data

medianflt2 Apply median filter to a matrix

minterp2 2D Interpolate/Extrapolate on the matrix

minverse Generate (pseudo) inverse of a matrix

normalize Normalize the input data

polyarea Calculate the area of an enclosed plot region

reflection Reflect a range of data to certain interval

rnormalize Normalize Columns:Normalize the input range column by column

specialflt2 Apply predefined special filter to a matrix

spline Perform spline interpolation and extrapolation

vcmath1 Perform simple arithmetic on one complex number

vcmath2 Perform simple arithmetic on two complex numbers

vmathtool Perform simple arithmetic on input data

vnormalize Normalize the input vector

white_noise Add white (Gaussian) noise to data

xyzarea Calculate the area of the XYZ surface

19.3.9 Signal Processing

Name Brief Description

cohere Perform coherence

365
 LabTalk Scripting Guide

conv Compute the convolution of two signals

corr1 Compute 1D correlation of two signals

corr2 2D correlation.

deconv Compute the deconvolution

envelope Get envelope of the data

fft_filter2 Perform 2D FFT filtering

fft_filters Perform FFT Filtering

hilbert Perform Hilbert transform or calculate analytic signal

msmooth Smooth the matrix by expanding and shrinking

smooth Perform smoothing to irregular and noisy data.

19.3.9.1 FFT

Name Brief Description

fft1 Fast Fourier transform on input vector (discrete Fourier transforms)

fft2 Two-dimensional fast Fourier transform

ifft1 Perform inverse Fourier transform

ifft2 Inverse two-dimensional discrete Fourier transform

stft Perform Short Time Fourier Transform

unwrap Transfer phase angles into smoother phase

19.3.9.2 Wavelet

Name Brief Description

cw_evaluate Evaluation of continuous wavelet functions

cwt Computes the real, one-dimensional, continuous wavelet transform coefficients

dwt 1D discrete wavelet transform

dwt2 Decompose matrix data with wavelet transform

Inverted 1D Wavelet Transform from its approximation coefficients and detail

idwt
coefficients.

366
 Function Reference

idwt2 Reconstruct 2D signal from coefficients matrix

mdwt Multilevel 1-D wavelet decomposition

wtdenoise Remove noise using wavelet transform

wtsmooth Smooth signal by cutting off detailed coefficients

19.3.10 Spectroscopy
Name Brief Description

blauto Create baseline automatically

fitpeaks Pick multiple peaks from a curve to fit Guassian or Lorentzian peak functions

pa Open Peak Analyzer

paMultiY Peak Analysis batch processing using Analysis Theme to generate summary report

pkFind Pick peaks on the curve.

19.3.11 Statistics
19.3.11.1 Descriptive Statistics

Name Brief Description

colstats Perform statistics on columns

corrcoef Calculate correlation coefficients of the selected data

discfreqs Calculate Frequency for discrete/categorical data

freqcounts Calculate frequency counts

kstest One sample Kolmogorov-Smirnov test for normality

lillietest Lilliefors normality test

mmoments Calculate moments on selected data

moments Calculate moments on selected data

mquantiles Calculate quantiles on selected data

mstats Calculate descriptive statistics on selected data

quantiles Calculate quantiles on selected data

367
 LabTalk Scripting Guide

rowquantiles Calculate quantiles on row(s)

rowstats Descriptive statistics on row(s)

stats Calculate descriptive statistics on selected data

swtest Shapiro-Wilk test for normality:Shapiro-Wilk Normality test

19.3.11.2 Hypothesis Testing

Name Brief Description

rowttest2 Perform a two-sample t-test on rows

ttest1 One-Sample t-test

ttest2 Two-Sample t-test

ttestpair Pair-Sample t test

vartest1 Chi-squared variance test

vartest2 Perform a F-test.

19.3.11.3 Nonparametric Tests

Name Brief Description

friedman Perform a Friedman ANOVA

kstest2 Perform a two-sample KS-test on the input data.

kwanova Perform Kruskal-Wallis ANOVA

mediantest Perform median test

mwtest Preform Mann-Whitney test

sign2 Perform paired sample sign test

signrank1 Perform a one-sample Wilcoxon signed rank test

signrank2 Preform paired sample Wilcoxon signed rank test

19.3.11.4 Survival Analysis

Name Brief Description

kaplanmeier Perform a Kaplan-Meier (product-limit) analysis

368
 Function Reference

phm_Cox Perform a Cox Proportional Hazards Model analysis

weibullfit Perform a Weibull fit on survival data

19.3.12 Utility

Name Brief Description

customMenu Open Custom Menu Editor Dialog.

get_plot_sel Get plot selections in data plot

get_wks_sel Get selections in worksheet

themeApply2g Apply a theme to a graph or some graphs.

themeApply2w Apply a theme to a worksheet or some worksheets.

themeEdit Edit the specific theme file using Theme Editing tool.

xop X-Function to run the operation framework based classes.

19.3.12.1 File

Name Brief Description

cmpfile Compare two binary files and print out comparison results

dlgFile Prompt user to select a file with an Open file dialog.

dlgPath Prompt user to select a path with an Open Path dialog.

dlgSave Prompt user with an Save as dialog.

Create a .txt file that contains notes or records of the user's work through a
filelog
string

findFiles Searches for a file or files.

findFolders Searches for a folder or folders.

imgFile Prompt user to select an image with an Open file dialog.

template_saveas Save a graph/workbook/matrix window to a template

web2file Copy a web page to a local file

19.3.12.2 System

369
LabTalk Scripting Guide

Name Brief Description

cd Change or show working directory

Assigns a specified index to the current working directory, or lists all

cdset
assigned indices and associated paths.

Used to create a debug log file. Turn on only if you have a problem to
debug_log
report to OriginLab.

dir list script (ogs) and x-functions (oxf) in current working directory.

Open a dialog with check boxes and return each check box's selected
dlgChkList
status when the dialog is closed.

group_server Set up the Group Folder location for both group leader and members

groupmgr Group Leader's tool to manage Group Folder files

instOPX Install an Origin XML Package

language Change Origin Display Language

lc Lists x-function categories, or all x-functions in a specified category.

lic Update Module License:Add module license file into Origin

lx Lists x-functions (by name, keyword, location etc)

mkdir Create a new folder in the current working directory

op_change Get and set tree stored in operation object

pb Open the Project Browser

pe_cd Change project explorer directory

pe_dir Lists current project explorer folders and workbooks

pe_load Load an Origin project into an existing folder in the current project

pe_mkdir Create new folder

pe_move Move specified page of folder to specified folder

pe_path Find Project Explorer path

pe_rename Rename Page or subfolder

pe_rmdir Delete a subfolder under the active folder in PE

pe_save Save a folder from the current project to an Origin project file

370
 Function Reference

pef_pptslide Export all graphs in folder to PowerPoint Slides

pef_slideshow Slide Show (full screen view) of all graphs in folder

pemp_pptslide Export selected graphs to PowerPoint Slides

pemp_slideshow Slide Show (full screen view) of selected graphs

pep_addshortcuts Create shortcuts for selected windows in Favorites folder

pesp_gotofolder Go to the original folder where this page locates

updateUFF Transfer user files in Origin75 to Origin8

ux Update x-function list in specified location

371
20 Appendix
List of LabTalk related help materials:
Reference Location

Menu: Help: X-Functions

X-
 Reference of individual X-Function.
Function

Menu: Help: Programming: Origin C

 Section OriginC Reference> Global Functions> LabTalk Interface

Origin C
For running LabTalk from Origin C.

Menu: Help: Programming: Code Builder

Code
 How to use Code Builder.
Builder

Menu: Help: Tutorials

 Section Tutorials> Programming> Command Window and X-Functions.

Tutorials A simple introductory tutorial for how to run LabTalk commands and X-

Functions.

Web site:

http://www.originlab.com/index.aspx?go=Products/Origin/ImportingData&pid=1163
Video
 Learn how to run LabTalk Script after importing data.

373
Index
$ Before Formula Scripts .................................. 125
$( ) Substitution ..........................................73, 80 block................................................................. 32
$(num) ............................................................ 157 block of cells .................................................... 61
braces .............................................................. 32
%
break ................................................................ 45
% variables....................................................... 90
C
%( ) Substitution ............................................... 73
%( ) substitution notation ................................. 68 Calculation Using Interpolation ........................ 41
%(string$) ....................................................... 157 calculations involving columns ........................ 76
%A - %Z ........................................................... 73 call a fitting function ......................................... 53
%n, Argument .................................................. 84 Calling Origin C Function from LabTalk ......... 110
Calling X-Functions and Origin C Functions97, 240
@
cd ................................................................... 123
@ option ........................................................... 78 Code Builder .......................................... 117, 143
@ Substitution .................................................. 77 Code Builder, script access ........................... 144
@ variable ........................................................ 78 colon-equal ...................................................... 95
A column dataset name ...................................... 74
access worksheet cell ...................................... 74 Column Format .............................................. 183
Active Column ................................................ 168 Column Header .............................................. 241
active dataset ................................................... 90 Column Label ......................................... 181, 241
active graph layer ........................................... 210 Column Label Row ........................................ 241
Active Matrixbook .............................168, 196–95 Column Width ................................................ 183
Active Window................................................ 168 Columns, Loop over ....................................... 249
active window title ............................................ 90 COM Server ................................................... 132
active worksheet .............................................. 60 command history ........................................... 116
Add Layer ....................................................... 213 command statement ........................................ 29
Addition ............................................................ 35 Command Window .................................. 70, 115
after fit script................................................... 132 command-line ................................................ 133
Analysis Template ..................................321, 324 comment .......................................................... 33
and operator ..................................................... 44 Comments ..................................................... 240
And operator .................................................... 35 Composite Range ............................................ 72
Append project ............................................... 238 conditional operator ......................................... 39
area ................................................................ 259 console........................................................... 133
Argument Order ............................................. 98 Constant .......................................................... 13
Argument, Command Statment ....................... 29 continue ........................................................... 45
Argument, Macro.............................................. 47 control characters ............................................ 74
Argument, Subsitution ...................................... 84 convert a numeric date value ........................ 191
Argument, X-Function .................................... 101 Convert Number to String .............................. 157
Arithmetic ....................................................... 187 Convert String to Number .............................. 156
arithmetic operator ........................................... 35 Converting Image to Data .............................. 288
arithmetic statement ......................................... 30 Copy Column ................................................. 188
ASCII ......................................................223, 230 Copy Matrix .................................................... 200
assignment operator .................................... 2, 37 Copy Range ................................................... 170
assignment statement ...................................... 27 correlation coefficient ..................................... 267
Assignment, X-Function Argument .................. 95 Cox Proportional hazards model ................... 272
Average Curves ............................................. 258 Create Baseline ............................................. 283
Axis Property .................................................. 211 Create Graph ................................................. 205
Axis Title Substitution ....................................... 80 Create Script File ........................................... 117
current baseline dataset .................................. 90
B current project name ........................................ 90
baseline .......................................................... 283 current working directory ............................... 122
batch processing ............................................ 323 current working folder .................................... 122
Batch Processing ........................................... 323 Current Working Folder ................................. 122

375
 LabTalk Scripting Guide

curve fitting ..................................................... 273 Extracting String Number............................... 156

custom menu.................................................. 138 F
Custom Routine ................................................. 3
Fast Fourier Transform .................................. 281
D FFT ................................................................ 281
D notation ....................................................... 191 filter ................................................................ 225
Data Filter....................................................... 175 filtering ........................................................... 282
Data Format ................................................... 184 find peak ........................................................ 283
Data Import .................................................... 223 Finding X given Y ........................................... 261
data plot ......................................................... 211 Finding Y given X ........................................... 261
Data Reader ................................................... 296 Flow of Control ................................................. 41
Data Selector ................................................. 297 for ..................................................................... 43
Data Type ......................................................... 12 format a number ............................................ 158
Database ........................................................ 225 frequency counts ........................................... 267
Dataset ............................................................. 14 Friedman Test ................................................ 270
dataset function ................................................ 52 Function ................................................. 187, 415
Dataset in Current Fitting Session ................... 90 function statement ........................................... 31
Dataset Substitution .............................60–61, 76 Function Tutorial .............................................. 55
Date ................................................................ 189 Function, Built-in .............................................. 48
date and time data ......................................... 189 Function, User Define ...................................... 49
date-time string .............................................. 191 functions viewer ............................................. 145
Debug Script .................................................. 143 G
Decision structure ............................................ 43
Get Input ........................................................ 291
Declare Range ................................................. 57
Get Point ........................................................ 296
Define Range ................................................... 68
GetN............................................................... 293
Delayed Execution ........................................... 32
GetNumber dialog .......................................... 293
delete ............................................................... 70
GetString ........................................................ 292
Delete Column ............................................... 186
GetYesNo command ..................................... 292
Delete Range Variable ..................................... 70
graph ...................................................... 205, 209
Delete Variable................................................. 21
Graph Export ................................................. 231
Delete Worksheet........................................... 169
Graph Groups ................................................ 207
derivative ........................................................ 258
graph layer ............................................. 205, 210
Descriptive Statistics ...................................... 265
Graph Layer ................................................... 207
dialog .............................................................. 300
graph legend .................................................. 211
Differentiation ................................................. 258
Graph Legend ................................................ 216
Division ............................................................. 35
graph property ............................................... 210
doc -e .......................................................42, 246
graph template ............................................... 205
Document ....................................................... 237
graph window ................................................. 205
Double .............................................................. 12
Graph, 3D ...................................................... 208
Double-Y Graph ............................................. 207
graphic object .................................................. 19
DPI ................................................................. 231
Graphic Object ............................................... 127
Dynamic Range Assignment............................ 68
Graphic Objects, Looping over ...................... 249
E Graphic Windows, Looping over .................... 248
Echo ............................................................... 146 gridding .......................................................... 209
Edge Detection............................................... 286 H
Embed debugging statement ......................... 147
Hello World ........................................................ 1
EPS ................................................................ 230
Hide Column .................................................. 182
error code ....................................................... 107
Hypothesis Test ............................................. 267
evaluating an expression ................................. 34
Excel book ...................................................... 239 I
exit .................................................................... 45 If 43
Exponentiate .................................................... 35 image ............................................................. 231
Export Graph .................................................. 231 Image Import .................................................. 226
Export Worksheet........................................... 230 Image Processing .......................................... 284
External application ........................................ 132 Import Data .................................................... 223
Extract Worksheet Data ................................. 171 Import Data Theme ........................................ 224

376
 Index

Import Image .................................................. 226 matrix ............................................................. 232

Import Wizard ................................................. 131 Matrix Export .................................................. 232
increment and decrement operators ................ 37 Matrix Interpolation ........................................ 264
insert column .................................................. 180 matrix sheet ................................................... 197
Insert Column ................................................. 180 matrix, copy ................................................... 200
Integer .............................................................. 13 Mean .............................................................. 265
integrating peak.............................................. 284 Median ........................................................... 265
Integration ...................................................... 259 Metadata ........................................................ 240
Intellisense ..................................................... 116 Move Column ................................................. 181
interactively ........................................................ 2 Multiple Regression ....................................... 274
Interpolated Curves ........................................ 263 Multiplication .................................................... 35
J N
JPEG .............................................................. 230 Non-linear Fitting ........................................... 276
K Nonparametric Test ....................................... 270
non-printing characters .................................... 74
Kaplan-Meier Estimator ................................. 271
numeric data type ............................................ 12
Kolmogorov-Smirnov Test ............................. 270
numpy ............................................................ 318
Krusal-Wallis ANOVA .................................... 270
O
L
Object Method ................................................. 86
label ................................................................ 216
Object Property ................................................ 85
Label Row Characters ..................................... 75
OCB file.......................................................... 111
LabTalk Interpreter ........................................... 33
OGS file ......................................................... 117
LabTalk Object ................................................. 85
One-Sample T-Test ....................................... 268
LabTalk Variables Dialog ............................... 145
Open a File .................................................... 145
latest worksheet selection ................................ 90
Open the Code Builder .................................. 145
Layer Alignment ............................................. 215
option ............................................................... 29
Layer Arrangement ........................................ 214
Option switche ............................................... 100
Layer, Add layer ............................................. 213
Option Switche ................................................. 63
Layer, Adding ................................................. 212
Option Switches ............................................... 62
Layer, Linking ................................................. 215
Or operator ...................................................... 35
Layer, Looping over ....................................... 250
Origin C functions .......................................... 108
Layer, Move ................................................... 214
Origin C, Pass Variable ................................. 110
Layer, Swap ................................................... 214
Origin Object .................................................... 88
Legend Substitution ......................................... 80
Origin Project ........................................... 88, 237
length of script .................................................. 33
origin project, append .................................... 238
LHS .................................................................. 27
origin project, open/save................................ 238
Linear Fit ........................................................ 274
Output X-Function .......................................... 100
Linear Regression .......................................... 274
list ..................................................................... 70 P
List Range Variable .......................................... 69 Parameter rows ............................................. 240
List Variables.................................................... 21 Pass Arguments in Script .............................. 119
Load Origin C ................................................. 109 Pass Arguments to Function ........................... 51
Load Window ................................................. 238 Pass Arguments to Macro ............................... 47
logical and relational operators ........................ 37 Pass Variable, Origin C ................................. 110
Long Name..................................................... 240 Pass Variables by Reference ........................ 120
loop .................................................................. 42 Pass Variables by Value ................................ 121
loop over multiple files ................................... 323 path of the current project ................................ 90
Loop Over Objects ......................................... 246 PDF ................................................................ 230
Loose Dataset .................................................. 66 peak analysis ................................................. 282
M placeholder .................................................... 120
plot ......................................................... 205, 248
Macro Property................................................. 47
Plot Designation ............................................. 183
Macro Statement .............................................. 29
Plot Graph ...................................................... 205
Manage Layer ................................................ 212
plot style ......................................................... 211
Mask ............................................................... 300
Polynomial Fit ................................................ 274
mathematical operations .................................. 40

377
 LabTalk Scripting Guide

program path .................................................... 90 Run Script from Graphic Object ..................... 127
project level loose dataset ............................... 14 Run Script from Import Wizard ...................... 131
Project Management ...................................... 237 Run Script from Nonlinear Fitter .................... 132
Project variables............................................... 22 Run Script from Script Panel ......................... 127
ProjectEvents.ogs .......................................... 129 Run Script from Set Values Dialog ................ 125
PyOrigin ......................................................... 316 Run Script On a Timer ................................... 133
PyQt4 ............................................................. 318 S
Python ............................................................ 313
Sampling Interval ........................................... 240
Python Binding ............................................... 318
Save Window ................................................. 238
Python Command .......................................... 313
Scalar Calculations .......................................... 40
Python Expression ......................................... 315
Scientific Notation .......................................... 159
Python Extension ........................................... 318
scipy ............................................................... 318
Python File ..................................................... 315
scope of a function ........................................... 53
Python Module ............................................... 316
Scope of String Register .................................. 89
Q scope of variables ............................................ 21
Quick Output ...................................................... 2 scope, forcing change of.................................. 24
R scope, local ...................................................... 23
scope, project .................................................. 22
range ................................................................ 16
scope, session ................................................. 22
Range Data Manipulation ................................ 67
Screen Reader ............................................... 296
Range Notation ................................................ 57
script .............................................. 117, 127, 133
Range to UID ................................................... 71
Script .............................................................. 133
range variable .................................................. 87
Script After Fitting .......................................... 132
Range, Block of Cells ....................................... 61
Script Panel ................................................... 127
Range, Column ................................................ 59
Script Section ................................................. 117
Range, Column Subrange ............................... 61
Script Window .................... 1, 3, 5, 115, 116, 117
Range, Get plot X............................................. 63
Script, Before Formula ................................... 125
Range, Get plot Y............................................. 63
script, debugging ........................................... 141
Range, Get plot Z ............................................. 63
script, execution ............................................. 113
Range, Graph Data .......................................... 63
Script, Fitting .................................................. 276
Range, Matrix Data .......................................... 62
Script, for specified window ........................... 114
Range, Origin Object ....................................... 58
script, from a custom menu ........................... 138
Range, Page and Sheet ................................... 61
script, from a script panel............................... 127
Range, Worksheet Data ................................... 59
script, from a toolbar button ........................... 138
Range, X-Function Argument .......................... 69
script, from external console .......................... 133
recalculate ...................................................... 106
script, import wizard/filter ............................... 131
recognition order .............................................. 33
script, in set values dialog.............................. 125
Reduce Worksheet Data ................................ 170
script, in worksheet script dialog .................... 126
refresh window ............................................... 239
script, interactive execution ................... 141, 150
Regional Data Selector .................................. 298
Script, Project events ..................................... 129
Regional Mask Tool ....................................... 298
script, run ....................................................... 113
Regression ..................................................... 274
section.............................................................. 45
Rename matrix sheet ..................................... 196
Select Range on Graph ................................... 64
Rename worksheet ........................................ 168
semicolon ................................................... 26, 31
repeat ............................................................... 42
separate statements ........................................ 31
ReportData ..................................................... 103
Session variables ............................................. 22
resolution ........................................................ 231
Set.................................................................. 211
RHS .................................................................. 27
Set Column Value .......................................... 322
Rotate image .................................................. 285
Set Column Values ........................................ 188
Row-by-Row Calculations ................................ 40
Set Decimal Places ........................................ 158
Rows, Delete .................................................. 181
set matrix value .............................................. 200
Rows, Looping over ....................................... 249
Set Path ......................................................... 122
Run Script ...................................................... 113
Set Significant Digits ...................................... 158
Run Script from Command Window............... 115
Set Values Dialog .......................................... 125
Run Script from External Application ............. 132
Signal Processing .......................................... 278
Run Script from File ....................................... 117

378
 Index

Signed Rank Test........................................... 270 Trim margin .................................................... 285

smoothing....................................................... 259 T-test .............................................................. 268
Smoothing ...................................................... 278 Two-Sample T-Test ....................................... 268
Sparkline ........................................................ 186 U
spectroscopy .................................................. 282
UID ............................................................. 71, 86
speed mode ................................................... 211
UID, Range ...................................................... 71
Start a New Project ........................................ 237
Units ............................................................... 240
statement ......................................................... 26
universal identifier ...................................... 71, 86
Statement Type ................................................ 27
Update Origin C ............................................. 111
string array ..................................................... 159
User Files Folder ........................................... 117
String Comparison ........................................... 92
User Files Folder Path ..................................... 90
string concatenation ......................................... 36
User-Defined parameters .............................. 240
String Concatenation ..................................... 155
string expression ........................................28, 73 V
String Expression Substitution ......................... 73 variable ............................................................ 20
String Method ................................................. 154 Variable ............................................................ 12
String Processing ........................................... 154 Variable Name Conflict .................................... 20
String Register ...................................15, 89, 154 Variable Naming Rule ...................................... 20
String Registers.............................................. 155 variable, local ................................................... 23
string variable ................................................. 115 variable, project ............................................... 22
String variable .................................................. 15 variable, session .............................................. 22
String Variable................................................ 153 variables ............................................................ 2
String Variable, String Register........................ 91 Vector Calculation ............................................ 40
StringArray ....................................................... 16 Virtual Matrix .......................................... 179, 209
subrange .......................................................... 61 W
Substitution Notation ........................................ 73
substitution notations ......................................... 2 wcol() ............................................................... 68
substitution, keyword .................................74–73 Weibull Fit ...................................................... 273
Substring ........................................................ 154 wildcard .......................................................... 172
Substring notation ............................................ 93 window, active ......................................... 114–13
Subtraction ....................................................... 35 worksheet ...................................................... 170
summary report .............................................. 324 Worksheet Export .......................................... 230
Swap Column ................................................. 183 Worksheet Filter ............................................. 175
switch .................................................29, 44, 105 worksheet info substitution .............................. 77
Syntax .............................................................. 26 Worksheet Script dialog ................................. 126
system variable ................................................ 90 worksheet, column and cell substitution .......... 74
System Variable, String Register ..................... 90 worksheet, copy ............................................. 170
worksheet, extract data.................................. 171
T worksheet, reduce data ................................. 170
T notation ....................................................... 191 Worksheets, Looping over ............................. 248
temporary loose dataset .................................. 14 X
ternary operator................................................ 39
theme ............................................................. 106 X-Function ......................................... 94, 97, 415
Time ............................................................... 189 X-Function Argument ..................................... 101
Time format notation ...................................... 191 X-Function Argument, Range .......................... 69
timer ............................................................... 134 X-Function Exception ..................................... 107
token ................................................................ 94 X-Function, open dialog ................................. 106
toolbar ............................................................ 138 X-Function, option switch............................... 105
Tree ................................................................ 243 XY Range ........................................................ 71
tree data type ................................................... 17 XYZ Range ...................................................... 71

379