3.9.2 Column Label Row Characters

Introduction

Worksheet column label rows typically contain metadata associated with one or more columns of data (datasets). This metadata is accessible via script or at various places in the user-interface:

Element Where is it used? Examples
Axis Title

%(?Y, @LD"Run Type")

Legend

\l(1) %(1, @LD"Run Type")

Text Label

%(1Y,@LD"RunType")

Plot Label

%(wcol[Run Type]$)

Annotations

%(1,@L) = $(x), $(y,y)

Column Formula and Cell Formula

value(D[Mean]$)*A (column formula) =value(D[Mean]$)*A1 (cell formula)

Script
  • General script usage

See Examples below

Note that the above elements support substitution of other types of project data including cell data, project and import file metadata, project variables, etc. For a broader discussion of substitution usage by element, follow the links in the Element column.

Column Label Row Properties

Worksheet label rows are accessed using the following characters as row indices.

Label Row Character Access Description
Short Name G Read/write Short Name (8.6 SR0).
Long Name L Read/write Long Name.
Units U Read/write Units.
Comments C Read/write Comments.
Sampling Interval E Read only Even Sampling Interval (Represented by R prior to 8.0 SR3). Show this column label row using wks.labels(E) and set interval using wks.col -- see examples below.
Sparklines S n/a Sparkline. You can show this label row using wks.labels(S), in which case you could use the sparklines X-Function to show the plot. Note, however, that the sparklines X-Function can be used to show BOTH the sparklines column label row and the plot.
Filter F Read only Filter Condition (90 SR0).
F(x)= O Read/write The F(x)= or Set Values formula (91 SR0).
Categories O1 Read only Categories for a Categorical data column (2015 SR2).
Parameters Pn Read/write Built-in Column Parameter, where n is the parameter index.
User-defined Parameters Dn / <Real Parameter Name> Read/write User-defined parameter, where n is the parameter index. E.g. If you rename 1st user-defined parameter as Mean, you can use either col(B)[D1]$ or col(B)[Mean]$

Examples

//Show, Hide or Move Column Label Rows
wks.labels(0); //Hide all column label rows
wks.labels(LUCO); //Show long name, units, comments and F(x) rows
wks.labels(+EF);  //Add Sampling Interval and Filter rows to the top
wks.labels(*P1O1); // Add Column Parameter 1, Categories rows to the bottom
wks.labels(-F); //Hide Filter row
wks.labels(>C); //Move Comments row to bottom of label rows

// Write long name, units, comments, and parameter1 of column B
col(B)[L]$ = "Temperature"; // Long name
col(B)[U]$ = \+(o)C; // Units
col(B)[C]$ = "Temperature vs Time"; // Comments
col(B)[P1]$ = "Site 1"; // The 1st Parameters row
 
// Set Sampling Interval of column B
wks.col2.xinit = 0.1;  // init value
wks.col2.xinc = 0.001;  // interval
wks.col2.xunits$ = "s";  // units
wks.col2.xname$ = "Time";  // name
 
// Define F(x) cell of column C to set values
col(B)=normal(32); //fill column with normal random values
col(C)[O]$="col(B)*2"; //enter formula to calculate values in column C

//Show sparklines
wks.labels(*S); //Add Sparklines row at the bottom
sparklines sel:=0 c1:=1 c2:=3; //use sparklines x-function to plot sparklines

//Set Column A as Categorical and read strings in Categories cell
patternT irng:=col(A) mode:=random text:="NY LA GZ HK" onerepeat:=2 seqrepeat:=4; //Fill column A with random text
set col(A) -dc 1; //Set column A as Categorical
col(A)[O1]$=; //Read strings in Categories cell
string str1$ = col(A)[O1]$; //Read strings in Categories cell to a string variable;
str1$=; 
 
// Add User Defined Parameter 1 and access it using D1 character
wks.labels(*D1); //Show 1st User Defined Parameter 
wks.UserParam1$ = "Mean"; //Rename 1st User Defined Parameter as Mean
col(B)[D1]$ = $(mean(Col(B)),*3); //Put mean of column B in Mean label row, keep 3 significant digits

//Add User Defined Parameter 2 and access it using real user parameter name
wks.userparam2 = 1; //Show Size column label row, same as wks.labels(*D2);
wks.userparam2$ = Size; //Define 2nd User Defined Parameter Size
col(B)[Size]$ = $(count(Col(B),1),.0); //Put size of column B in Size row, 0 decimal places.

Column label rows contain metadata, or information about the data contained in the column. Please see the Accessing Metadata section for detailed notes on their use.