5.3 Range Notation in LabTalk

Summary

Rangeis a unique data type in Origin to refer to data in your project. Usually data are stored in 4 places in project: workbooks, graphs, matrices and loose datasets.

Once a range variable is declared, you can directly read or write to the range.

Starting with Orgin 2023, range references to page names -- be they workbooks, matrices or graphs -- should be double-quoted for page Long Name and NOT double-quoted for page Short Name (double-quoting Long Name was previously required, double-quoting Short Name was allowed, but discouraged). The prohibition on double-quoting of Short Name extends to references by substitution (e.g. [%H] NOT ["%H"]). This change means that page Long Name search will preferentially search the active folder for window Long Name. This prohibition allows for more robust page references when duplicating folders or appending projects. However, if you prefer the old behavior, you can roll back this change using system variable @RQS.

Declaration

You declare a range variable using a syntax that is similar to other data types:

range [-option] RangeName = RangeString

The left-hand side of the range assignment is uniform for all types of range assignments. Range names follow Origin variable naming rules. The [-option] component indicates an optional parameter, with available option switches differing by data type (see Types of Range Data for details).
The right-hand side of the range assignment, the RangeString, varies by object type. Refer to the following sub-topics for specifics:

Workbooks

For workbook data, RangeString takes the form:

[WorkBookName]SheetNameOrIndex!ColumnNameOrIndex[CellIndex]

[WorkbookName] can be skipped if defining range for current book. [WorkbookName]SheetNameorIndex! can be skipped if defining data in active sheet of active book.

WorkBookName and SheetName refer to the corresponding Short Name, since Short Name is the default programming name.

To use Long Name in range notation for workbook or worksheet, you must put Long Name in double quotes as in ["MyBook"]"MySheet"!.
Conversely, DO NOT surround Short Name with double quotes (this includes in references like [%H]). Prior to Origin 2023, this may have been accepted though it was not recommended. Starting with Origin 2023, double-quoting Short Name will likely fail. To roll back to previous behavior (allow double-quoted Short Name), see LT system variable @RQS.
Following the change to disallow double-quoting of Short Name, page Long Name search will preferentially search the active folder for window Long Name. This allows you to do such things as:

Duplicate folders and preserve within-folder operations such as those that rely on local variables defined in a workbook.
Save a Project Explorer folder as a project then later append that project to another project. When doing so, window Short Names are modified to avoid naming conflicts but operations that depend on window Long Names will not be affected.

ColumnName (no quotes) can be either the column Long Name or the Short Name (if Long Name has spaces, it must be double-quoted).
Since 2022b, column Long Name will be be case sensitive when @LNCS=1.

Worksheet Cell Range

Use a range to access a single cell or block of cells. The range may span rows and columns.

 // cell(2,1), row2 of col(1)
 range aa = 1[2];  
 // cell(1,1) to cell(10,3)                     
 range bb = 1[1]:3[10];

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

Practical Example 1

//create a new workbook with col(A) and col(B)
newbook;
//fill first column with values
col(A) = {1:10};
// define range aa as col(A) dataset, range bb as col(B) dataset (empty)
range aa = col(A);
range bb = col(B);
// copy value in range aa, cell 1 to range bb cell 1
bb[1] = aa[1];

Practical Example 2

//create a new workbook
newbook;
//fill first column with values
col(A) = {1:10};
// put name of active worksheet into string var "yy$"
yy$ = %H;
// define range variable "aa" as your column of values
range aa = [yy$]1!col(A);
// create a new workbook and put name into "zz$"
newbook;
zz$ = %H;
// define range in new book
range bb = [zz$]1!col(A);
// write value in "aa", cell 1 to "bb", cell 1
bb[1] = aa[1];

Column Label Row Range

Use a range variable to access the column label rows in the active worksheet:

range rr=[L:C];
range rr=1[L]:end[L];

Note that you CANNOT use a negative number, such as (-1) in the range variable for label row.

Practical Example

// create a new workbook
newbook;
// import a file
string fn$=system.path.program$ + "Samples\Import and Export\ASCII Simple.dat";
impASC fname:=fn$;
// define range variable containing raw data
range raw = [%H]1!col(signal);
// show 1st and 2nd User Defined Parameter Rows
wks.userParam1 = 1;  
wks.userParam2 = 1;
// rename 1st Parameter as "Mean", 2nd as "Std. Dev."
wks.UserParam1$ = "Mean";
wks.UserParam2$ = "Std. Dev.";
// use mean() and stddev() functions to return values to 5 decimal places;
// to respective label row cells in range variable raw
raw[Mean]$ = $(mean(raw),*5);
raw[Std. Dev.]$ = $(stddev(raw),*5);

For an expanded discussion on accessing column label row data, with examples, see

Worksheet Column SubRange

// A subrange, rows 3-10, of col(a) in book1 sheet2
range cc = [book1]sheet2!col(a)[3:10];

//range that refers to the first column in the active worksheet
range r1 = !1;
//variables can be used when specifying the subrange
int istart=3;
int iend=10;
range r2 = r1[istart:iend];

Practical Example:

//create a new workbook
newbook;
//fill first column with values
col(A) = {1:10}; 
//create range that refers to this first column
range rA = col(A);
//add a new sheet
newsheet;
//fill this column with the values from the first column in first worksheet
col(A) = rA;
range rAA = col(A);
newsheet;
range r1 = rA[1:5];
range r2 = rAA[6:10];
col(A) = r1 + r2;

Worksheet Column Range

Use a range variable to access an entire column of data.

Origin 2024b can create range with discontinuous columns with a new option switch -s:

StringArray sa = {2,4,6,8};
range -s rr=sa;
del rr;

In the examples below, all the ranges defined refer to the first column in the active worksheet (assuming the name of the first column is "A"). You may recognize the col( ) and wcol( ) functions as these are used from the Set Column Values dialog in Origin.

range rA = A;
range rAA = col(A);
range r1 = 1;
range ricol = wcol(ncol);

int ncol = 1;
range rr = $(ncol);

Practical Example:

Once a range variable is created, you can work with the range data directly, reading and writing to the range.

//create a new workbook
newbook;
//fill first column with values
col(A) = {1:10}; 
//fill second column with values
col(B) = {2:2:20};
//create range that refers to the first column
range rA = col(A);
//create a range that refers to the second column
range rB = col(B);
//add a new sheet
newsheet;
//multiply the values in the column range by 2 and assign to column A
col(A) = rA *2;
//divide the values in the column range by 2 and assign to column B
col(B) = rB/2;

For use with specific X-Functions, it's possible to define a range that covers multiple columns or a block of cells in a Worksheet:

range raMC = col(2):col(4); // Or equivalent of 2:4
stats raMC;
ty %(raMC) values range from $(stats.min) to $(stats.max);

range raBlock = 2[5]:10[300]; // column 2, row 5 to column 10, row 300
stats raBlock;
ty %(raBlock) values range from $(stats.min) to $(stats.max);

In Origin 2022b when @LNCS=1, column long name is case sensitive:

col("M")=10*col("m"); // "M" and "m" are two columns' long names

Worksheet Range

Use a range variable to access a worksheet:

range rSheet1 = [Book1]Sheet1!;
range rSheet2 = 1!;
range rSheet3 = !;

Note: If you run all the above lines when Sheet1 is active in the active Book1 workbook window, all three range variables will refer to that same worksheet.

Practical Example:

//create a new worksheet
newsheet;
//range refers to the active worksheet
range rWks = !;

Workbook Page Range

Use a range variable to access an entire workbook. In the example below, if you run the script when a Book1 workbook is the active window, all three range variables will refer to the Book1 window.

range rPage1 = [Book1];

//%H is a system string register that holds the name of the active window
range rPage2 = [%H];

string strBookName$ = %H;
range rPage3 = [%(strBookName$)];

Graphs

For graph data, the RangeString takes the form:

[GraphWindowName]LayerNameOrIndex!DataPlot

An example assignment looks like

range ll = [Graph1]Layer1!2;       // Second curve on Graph1, Layer1

Graph Data Subrange

Practical Example:

//integrate active plot from index 10 - 20
integ1 1[10:20];

Graph Data Range

range rAA = [Graph1]Layer1!1;
range rBB = 1!1;
range rCC = !1;
range rDD = 1;

Note: If you run the above three lines when layer 1 is active in the Graph1 window, all three range variables will refer to the first dataplot in that layer.

Practical Example:

range rr = 1;
set rr -c color(green);

Graph Layer Range

Use a range variable to access a layer in a graph window:

range rAA = [Graph1]Layer1!;
range rBB = 1!;
range rCC = !;

Note: If you run the above three lines when layer 1 is active in the Graph1 window, all three range variables will refer to that layer.

Practical Example:

//The layer is an Origin object.  To learn more look at the tutorial on Origin Objects.
//graph layer object that refers to the active layer
range rr= !;
//adjust the width and height of the graph layer object
rr.width=50;
rr.height=50;

Graph Page Range

Use a range variable to access an entire graph window. In the example below, if you run the script when Graph1 is the active window, all three range variables will refer to this window.

range rPage1 = [Graph1];
//%H is a system string register that holds the name of the active window
range rPage2 = [%H];

string strGraphName$ = %H;
range rPage3 = [%(strGraphName$)];

Matrices

For matrix data, the RangeString takes the form:

[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"!.

Matrix Data Subrange

You can declare a range that points to a cell or range of cells. Although a matrix is a 2D array, the index in this case is a one dimensional index from 1 to the number of cells in a matrix. The numbering is in row major order so the index calculation here is:

index = (RowNumber - 1) * NumberOfColumns + ColumnNumber

e.g. for a default 32 by 32 matrix: cell in 10th row and 20th column will have index

(10 - 1) * 32 + 20 = 308

range raMC = [MBook1]1!1[308];
raMC -= 100;

Matrix Data

Matrix Data is referred to as a Matrix Object and is equivalent to a wks.col object:

range raMD = [MBook1]"First Object Collection"!1;
stats raMD;
ty %(raMD) ranges from $(stats.min) to $(stats.max);

Given a Matrix Data range, you can access cells by row and column:

raMD[10,20] += 100; // Increment the cell in row 10, column 20 by 100

Matrixsheet

You can access Matrixsheet properties which is equivalent to the wks object:

range raMS = [MBook1]MSheet1;
raMS.Name$ = First Object Collection;

Matrixbook

You can access Matrix page properties using a Matrixbook range:

range raMB = [MBook1];
raMB.Label$ = Final Results;

Loose Datasets

Loose Datasets are variables in project scope. They are similar to columns in worksheet but lacks the usual book-sheet-column organization. They are typically created with the create command, or automatically created from an assignment statement without Dataset declaration.

For loose datasets, the RangeString takes the form:

[??]!LooseDatasetName

Assignment can be performed using the syntax:

//Use create command to create loose datasets temp1_X and temp1_Y
create temp1 -wdn 5 X Y;
//Use assignment to create loose dataset tempZ
tempZ = {10,9,8,7,6};

//define range variables for loose datasets
range rx = [??]!temp1_X;    
range ry = [??]!temp1_Y;    
range rz=[??]!tempZ;

Practical Example:

Here, we create a loose dataset, then use the plotxy X-Function to plot a graph of the 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.