5.3 Range Notation in LabTalk


Summary

Data exists in four primary places in your Origin project: workbooks, graphs, matrices and loose datasets.

You can access data in any of these objects using Range variables. Once a range variable is declared, you can directly read or write to the range.

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]

Note:
  • WorkBookName andSheetName refer to Short Name since Short Name is the default programming name. To use Long Name in range notation for workbook or worksheet, use Long Name in double quotes as in ["MyBook"]"MySheet"!.
  • ColumnName can be either the Long Name or the Short Name of the column.

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.

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

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

Matrix Sheet

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

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

Matrix Book

You can access Matrix page properties using a Matrix Book range:

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

Loose Datasets

Loose Datasets are similar to columns in a worksheet but as the name implies, they lack the usual book-sheet-column organization. Loose Datasets 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:

range xx = [??]!tmpdata_a;       // Loose dataset 'tmpdata_a'


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, for example.

For More Information on Range

For a complete discussion of LabTalk Range Syntax, see the topic "Range Notation" in the LabTalk Scripting Guide.