2.4.1.2 X-Function Input and Output

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 Type Description Sample Constructions Comment
XYRange

A combination of X, Y, and optional Y Error Bar data

  1. (1,2)
  2. <new>
  3. (1,2:end)
  4. (<input>,<new>)
  5. [book2]sheet3!<new>
 For graph, use index directly to indicate plot range
(1,2) means 1st and 2nd plots on graph
XYZRange

A combination of X, Y, and Z data

  1. (1,2,3)
  2. <new>
  3. [book2]sheet3!(1,<new>,<new>)
ReportTree

A Tree based object for a Hierarchical Report
Must be associated with a worksheet range or a LabTalk Tree variable

  1. <new>
  2. [<input>]<new>
  3. [book2]sheet3
ReportData

A Tree based object for a collection of vectors
Must be associated with a worksheet range or a LabTalk Tree variable. Unlike ReportTree, ReportData outputs to a regular worksheet 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.

  1. <new>
  2. [<input>]<new>
  3. [book2]sheet3
  4. [<input>]<input>!<new>

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

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

ReportData Output

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.

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.

English | Deutsch | 日本語