2.3.2.1 Range Notation

Range-Notation

Introduction to RangeRange Notation

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.

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 and SyntaxDeclare Range

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 see the Types of Range Data section below for details. Range names follow Origin variable naming rules; please note that system variable names should be avoided.

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 ObjectsAccess Origin Object by RangeRange, Origin Object

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

• column
• worksheet
• page
• graph layer
• loose dataset

Once assigned, use rangeVariable.= and rangeVariable.() to dump all accessible properties and methods

range rA = [Book1]Sheet1!Col(A); //define range variable ra as  column A in Book1 Sheet1
rA.=; //dump all properties
rA.(); //dump all methods
rA.lname$=; //output long name
rA.nRows=; //output number of rows
rA.unit$="MM/DD/YYYY"; //set unit as "MM/DD/YYYY"
ra.setformat(4);//set column as Date

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

Types of Range Data

Worksheet DataRange, Worksheet Data

For worksheet data, RangeString takes the form:

[WorkBookName]SheetNameOrIndex!ColumnNameOrIndex[CellIndex]

• WorkBookName and SheetName part can be skipped if referring to active book or active sheet
• 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.

//Using long name
range rPage = ["My Book"]; //range variable for page
range rSheet = ["My Book"]"My Sheet"; //range variable for sheet
range rA = ["My Book"]"My Sheet"!"Amplitude"; //range variable for column

//Using shor tname
range rPage = [Book1]; //range variable for page
range rSheet = [Book1]Sheet1; //range variable for sheet
range rA = [Book1]Sheet1!B; //range variable for column

//Using index in sheet and column part
range rSheet = [Book1]1; //range variable for sheet
range rA = [Book1]1!2; //range variable for column

//Mix of long name, short name or index
range rSheet = ["My Book"]1; //long name for book, index for sheet
range rA = [Book1]"My Sheet"!2; //short name for book, long name for sheet, index for column
range rB = [Book1]1!"Temparature"; //short name for book, index for sheet, long name for column

//Other examples
range rPage =[%H]; //%H is current window
range rA=%C; //%C is current selection in sheet
range rSheet = [%H]1; //1st sheet in current window
range rA=rSheet!A; //build rA based on rSheet

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

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 row. [10:0] also works
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.

ColumnRange, Column

When declaring a range variable for a column on the active worksheet, the book and sheet part can be dropped. Column short name, index, long name or col() can be used for column part as long as it be identified,

range r1 = col(3); //3rd column of active sheet
range r2 = col(C); //column C of active sheet;
range r3 = col("Sensor Y") //column with long name "Sensor Y" of active sheet
range aa=1;        // col(1) of  active worksheet
range bb=B;        // col(B) of active worksheet
range cc="Test A"; // col with Long Name "Test A" of active worksheet

An expression such as aa = 1! refers to the first sheet of the active book, while an expression such as aa = "1!" refers to a column in the current sheet with a Long Name of 1!. See the system variable @RPQ to control preserving or discarding quotes for range declaration.

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 declare multiple range variables in same specified sheet, you can put book & sheet portion in the front:

range ["MyBook"]Sheet3 aa=1, bb=B, cc="Test A"; //columns in Sheet3 of Book with long name "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 properties 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:

// 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 assigning non-existing column to a range variable, the column will not show until value is assigned to it. Same rule applies to column in non-existing sheet or book.

newbook; //start a new book, by default there are only two columns;
range aa=1, bb=2, cc=3; //assign 3 range variables 3 columns, 3rd column doesn't exist
aa=data{0, 10, 0.5}; //assign values to aa
bb=sin(aa); //assign values to bb
cc=cos(bb); //assign values to cc, 3rd column shows

If you wish to access column label rows using range, please see Accessing Metadata and the Column Label Row Reference Table.

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 SheetRange, Page and Sheet

Besides a single column of data, a range can be used to access page and sheet objects:

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; 
rPage.nlayers=; //output number of sheets
rPage.active=3; //set 3rd sheet to be active sheet

Use a range variable to access a worksheet:

// 'rSheet' points to sheet with long name MySheet" in book with ong Name MyBook
range rSheet = ["MyBook"]"MySheet"!;
rSheet.name$ = "Statistics";        // Rename sheet short name to "Statistics".
page.xlcolname = 0;               //Turn off Spreadsheet Cell Notation firstly
rSheet.AddCol(StdDev);              // Add a column named StdDev

For the Spreadsheet Cell Notation in the workbook, please see FAQ-849 for more information.

Column SubrangeRange, 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];

Create subrange of another range

range ra=[book1]Sheet1!A;
range subra=ra[10:20];

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 CellsRange, 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];  // (column 1, row 2), a cell
range bb = 1[1]:3[10];  // (column 1, row 1) to (column 3 row 10)

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

Origin's join() function can be used to join multiple non-contiguous ranges into a single dataset.

Option Switch -vOption Switches

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 examples scales all entries in a particular row of columns in the workshet:

// Scale 1st element of all columns except the last column, by a factor
range -v r=1[1]:$(wks.ncols-1)[1];
r*=10;
// Scale 1st element of all columns
range -v r=1[1]:end[1];
r*=10;

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 DataRange, Matrix Data

For matrix data, the RangeString is

[MatrixBookName]MatrixSheetNameOrIndex!MatrixObject

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 matrixsheet MatSheet1 (Long Name)
// on matrix book MatBook1 (Long Name)
range mo = ["MatBook1"]"MatSheet1"!Mat("MatObject1");

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 DataRange, 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
range mm = %C; //Get the current active plot or selected plot

Option Switches -w, -wx, -wy and -wzOption Switche

For graph windows, you can use range -wRange, Get plot Y and range -wxRange, Get plot X, range -wyRange, Get plot Y, range -wzRange, Get plot Z 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;
type %(rw); //output the rangestring

// 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 GraphSelect Range on 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;
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

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.

Methods of Range

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

Unique Uses of Range

Manipulating Range DataManipulate RangeRange Data Manipulation

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;
// 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 AssignmentDynamic 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 IndexDefine Range

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 range variable using the %( ) substitution notation and wks (object) methods. When the %( ) substitution is used on a range variable, it is resolved to a rangestring. Sometimes %() can be skipped.

range rpage=[book1] //define range variable for page
range rwks = %(rpage)sheet1!; //define rwks based on %(rpage)

type %(rwks); //output rangestring [book1]sheet1! 

range r1= rwks!A; //define r1 based on rwks, %() skipped though %(rwks)A also works
type %(r1); //output rangestring [Book1]Sheet1!A
r1=data(0,100,2); //fill r1 with 0, 2, 4, ..., 100

range subr1=r1[10:20] //define subr1 based on r1, %() skipped though %(r1)[10:20] also works
type %(subr1); //output rangestring [Book1]Sheet1!A[10:20]

This method of constructing new range based on higher level range is very useful for code centralization.

rpage.longname$="My Book"; //rename page long name
rwks.addcol();//add a column to specified sheet
range r2 = rwks!wcol(rwks.ncols); //define r2 as last (rightmost) column in rwks
r2=subr1; //fill r2 with subr1 values

Refer to the Last Row, Column and Sheet Using 0

The 0 notation refers to the last index(last row, last column or last sheet) of a range with dynamic end. For example,

range rsheet=0!; //last sheet
range right = 0!0; //last(rightmost) column in last sheet
range sub = 0!0[10:0]; ///cells from row 0 to last row of last column in last sheet
range r2 = [Book1]Sheet1!2[3]:0[0]; //from 2nd col, 3rd row to last column, last row

X-Function ArgumentX-Function Argument, RangeRange, 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 rangestring:

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 first define the range variable and then use range variable as argument

// Defines a range variable for cells from row 3 to row 5 of col(2) on 1st and 2nd sheets, 
range aa = (1,2)!col(2)[3:5]; 
//run statistics on the range;
stats aa;

The input vector argument for this X-Function is then specified by a range variable.

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;

Listing, Deleting, and Converting Range Variables

Listing Range VariablesList Range Variable

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:

Deleting Range VariablesDelete Range Variable

To delete a range variable, use the deldelete 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
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.

Converting Range to UIDRange to UIDUID, Range

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.

Special Notations for Range

Specifying Multiple Sheets

When referring to multiple sheets, use the general form of the worksheet data range string, combined with commas and colons to specify the range.

[Workbook](SheetA,SheetN:SheetM)!colBegin[rowIndex]:colEnd[rowIndex]

// Basic combination of three ranges:
(range1, range2, range3)  

// Common column ranges from multiple sheets:
(sheet1,sheet2,sheet3)!range1
(sheet1,sheet3:5)!range1
 
// Common column ranges from a range of sheets   
(sheet1:sheetn)!range1

For example:

// plot A(X)B(Y) from two 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];

// Appends every worksheet in the active workbook into a new sheet in the book.
wappend irng:=(1:end)!;

A more general discussion of Composite Range is given below.

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

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
(1，2，3)!range1

// Common column ranges from a range of sheets   
(sheet1:sheet3)!range1           
(1:3)!!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!