3.9.13 Text Label Substitution

Introduction

When making graphs of worksheet or matrix data, most auto-generated labels -- including axis titles and graph legends -- are created by assigning plot metadata to a named label object. Each of these named label objects is saved in the graph template as an "empty", predefined string of characters which map to various bits of plot metadata. We refer to the run-time assignment of plot metadata to these labels as "substitution" and the syntax used to construct the "empty" strings as "substitution notation."

This page covers named label objects -- legends, axis titles and user-added labels created with the Text tool or by script (e.g. label -sl). For information on plot data labels, see Notations and syntax used in labeling plotted data.

Text Label Names

Text labels on a graph, worksheet or matrix page typically have an object name that is exposed in the GUI or by script (axis tick labels are an exception). These labels or "objects" have a name that can be identified by opening the object's Properties dialog:

  1. Select a text object by clicking on it with your mouse, then right-click, and select Properties.
  2. In the Text Object dialog box, click on the Programming tab and look to the Name field.

As previously mentioned, LabTalk supports inserting metadata (project, page and dataset information) into your text labels using substitution notation. You can return or define which bits of metadata are used by a named label object, using objectName.text$.

Examples

Legend

For example in a graph legend, you might use... 

legend.text$=\l(1) %(1,@LG) \l(2) %(2,@LG) \l(3) %(3,@LG);

to specify that for the each of three Y plots in the layer, use the Long Name, if available, plus Units to create the legend object.

Alternately, you could use the legendupdate X-Function to create the same legend, using the same @LG option: 

legendupdate mode:=custom custom:=@LG;


Also, see this page on Legend Substitution Notation.

Axis Title

Besides legend other text object names on a graph include yl (left-side y-axis), xb (bottom x-axis), so that 

yl.text$ = %(?Y,@WL);   // Left Y axis title = the workbook Long Name of plotted Y
xb.text$ = %(1X,@LU);   // Bottom X axis title = the units of the 1st plot's X dataset 
yl.text$ = %(?Y,@(@LL<@LU>)); //Left Y axis title = the workbook Long Name of plotted Y followed by Units enclosed in < >.

The %(?Y) is a variable syntax that causes the axis title to default to a pre-specified data plot index (set in Plot Details: Legends/Titles: Data Plot Index for Auto Axis Titles), instead of an index (1, 2, ... n) that you supply.

User-created Text Objects

The following examples demonstrate substitution of data and metadata in user labels created by various methods:

Example 1: Use Text tool to create a label named "text" added and linked to display a value in a column label "User-parameter" row named named "No. of points": 

text.text$="Number of points: %([S15-125-03.dat]Trial Run 1,@LD"No. of points",2)"
AtOptions LT text label.png

Example 2: Add a label named "filedate" via script that displays a formatted import file date for metadata associated with the worksheet or graph: 

label -sl -n  filedate "File Date: $("%(Book2, @W,SYSTEM.IMPORT.filedate$)",D0)";
AtOptions LT text label ex2.png

Example 3: Numbers in a worksheet often display at lower precision than the internally-stored cell value. Add a label named "celldigits" that displays the worksheet value at the displayed precision: 

label -sl -n celldigits "Col(Signal)[3] displayed value is %([Book2]Sheet3, @WL, Signal[3], W)";

Add a label named "fullprecision" that displays the internally-stored, full precision cell value: 

label -sl -n fullprecision "Col(Signal)[3] full precision value is %([Book2]Sheet3, @WL, Signal[3])";
AtOptions LT text label ex3.png

For more information on formatting substituted numeric values, see Return value in current column format with "W" and "@WL".

Syntax

These syntaxes can be used for different applications. In some cases, you can combine and adapt notations as shown in the last example under User-created Text Objects, above.

objectName.text$= Application
%(PlotIndex[PlotDesignChar], @option)
  • Refer to a data plot by PlotIndex and a column from this plot by PlotDesignChar such as X, Y or Z. This syntax is used for legends and axis titles.
  • Variable "@ options" and examples are listed under List of @ Options, below.
%([workbookName]sheetName, @WL, column[row], W)
%([workbookName]worksheetName, @option, columnNumber)
%([workbookName]worksheetName!columnName,@option, varOrNodeName)


Notes:

To combine multiple @options interspersed with arbitrary text, use the following syntax:

%(PlotIndex,@(@option1(@option2...)))

For example, 

%(1,@(@LL(@LU)))// shown as '''Long Name(Units)'''

Complete List of @Options

Below is a table of available @ text-label options for customizing the text labels, including legend text and axis title. See the screenshots for the worksheet properties which will be referenced by the sample expressions:

Worksheet Properties Legend Option 01.png

Note: While many of these "@" label options can only apply to workbook data, some of them are applicable to matrix data. For instance, the expression ... 
%(1,@W)

... will return the matrixbook short name.

@option Substitute Text From... Example
@C Column Short Name. Equivalent to @LS. %(1,@C) --> B
@D Dataset name %(?Y,@D) --> Book1_B
@GG Group Name of current plot in a graph %(2, @GG)
Show the group name of current plot. The default group name g# will show as blank.
@GL Layer Name of current plot in a graph %(2, @GL)
Show the layer name of current plot. The default layer name Layer# will show as blank.
@L Column Long Name, will return to missing value if long name does not exist. Equivalent to @LL. %(1Y,@L) --> Delta Temperature
@L,n The nth X value %(1,@L,2) --> 0.02
@LA Long Name, if available, else Short Name. %(1,@LA) --> Delta Temperature
@LC Comments, if available, else Long Name, otherwise Short Name %(1,@LC) -->
YBCO
milled
@LC[n] The nth line of the Comments label row cell. Note that n is optional and that @LC1 = @LC. %(1,@LC2) -->milled
@LD[n] The nth user-defined parameter. Note that n is optional and that @LD1 = @LD. %(1,@LD2) -->235
@LD"name" The user-defined parameter of specified name. %(1,@LD"RunNo")-->07
@LF[n] The filter condition of the data plot. When there are multiple conditions, optional n = the nth line of filter condition (list order shown in Filter label row cell). Also, see LabTalk system variable @SFD Make = %(1,@LF)-->Buick

Text label options @LF.png

@LG Long Name (if not available then Short Name) and Units (if present). Equivalent to @U. %(1,@LG) -->Delta Temperature (K)
@LH The name of the first User-Defined Parameter. %(1,@LH) -->UserDefined
@LH[n] The nth User-Defined Parameter. Note that n is optional and that @LH1 = @LH. %(1,@LH3) -->RunNo
@LL Equivalent to @L. %(1,@LL) --> Delta Temperature
@LM 1st line of Comment, if available, else Long Name, otherwise Short Name. %(1,@LM) --> YBCO
@LN 1st line of Comments (if not available then Long Name, otherwise Short Name) and Units. Equivalent to @(@LM(@LU)). %(1,@LN) --> YBCO(K)
@LP The first System Parameter. %(1,@LP) --> Version 2.1
@LP[n] The nth System Parameter. Note that n is optional and that @LP1 = @LP. %(1,@LP2) --> 12/15/2004
@LQ The first User-Defined Parameter and Units (if available). %(1,@LQ) --> S21(K)
@LQ[n] The nth User-Defined Parameter and Units (if available). Differs from @LH by including Units. Note that n is optional and that @LQ1 = @LQ. %(1,@LQ2) --> 235(K)
@LQ"name" The User-Defined Parameter (specified by name) and Units (if available). %(1,@LQ"RunNo") --> 07(K)
@LS Column Short Name, equivalent to @C %(1,@LS) --> B
@LU Units %(1,@LU) --> K
@PLE Holder Book Long Name. Returns the Long Name of container workbook for embedded Graph, Matrix, Notes or HTML Report. %(%H,@PLE)
@R Dataset range %(1,@R) -->

[Book1]"Trial Run 2"!Col("Delta Temperature")[1:32]

@R1 Dataset range without row index %(1,@R1) -->

[Book1]"Trial Run 2"!Col("Delta Temperature")

@RB Starting row index of the plotted data %(1,@RB) -->

1

@RE Ending row index of the plotted data, same as @RN if @RB is 1 %(1,@RE) -->

32

@RN Total number of rows in the plotted data (will not exclude missing values or masked data points) %(1,@RN) --> 32
@SC Holder Sheet Comment. Returns the Comment of sheet for an embedded Graph, Matrix, Notes or HTML Report. %(%H,@SC)
@SN Holder Sheet Display Name; if Label exists use Label. Returns the Display Name or Label of sheet for an embedded Graph, Matrix, Notes or HTML Report. %(%H,@SN)
@SNL Holder Sheet Label. Returns the Label of sheet for an embedded Graph, Matrix, Notes or HTML Report. %(%H,@SNL)
@SNS Holder Sheet Name. Returns the Name of sheet for an embedded Graph, Matrix, Notes or HTML Report. %(%H,@SNS)
@U Long Name (if not available then Short Name) and Units (if present). Equivalent to @LG %(1,@U) -->Delta Temperature (K)
@V, n The value of the nth point in the data plot.  %(1Y, @V, 2) -->0.02863
@V"above"/@V"below" Use in Fill Area Under Curve graph only. When Fill to next data plot - Above Below Color is selected, this notation is used for labels to indicate the filled-color above / below base curve.

%(1, @V"above") %(1, @V"below") -->
Above B
Below B

@W Short Name of book
(workbook, matrix) 		%(1,@W) -->Book1
@WC[n] The nth line of the WorkBook Comment. If optional n is not specified, only the first line will be shown. %(1,@WC2) -->

<Origin EXE Folder>\Samples\Curve Fitting

@WL Long Name of book
(workbook, matrix) 		%(1,@WL) -->S21-235-07
@WNL Long Name of sheet
(workbook, matrix) 		%(1,@WNL) -- See LabTalk System Variable @SSL
@WNS Short Name of sheet
(workbook, matrix) 		%(1,@WNS) -- See LabTalk System Variable @SSL
@WM[n] The nth line of the WorkSheet Comment. If optional n is not specified, only the first line will be shown. %(1,@WM) -->Data imported from
@WP Project Explorer (PE) path of the book
(workbook, matrix) 		%(1,@WP) -->/Folder1/
@WS Name of the sheet (workbook, matrix) %(1,@WS) -->Trial Run 2
@WT, ColIndex/ColName, RowIndex The sheet cell value specified by the column index (or short name) and row index.
  • %(1, @WT, 2, 3)
    the cell value at column 2, row 3 in the source sheet (worksheet, matrix) of the 1st data plot. Because it's numeric, you can use $($(%(1, @WT, 2, 3), .2)*100) to get string of the number with two decimal place times 100.
  • %(1, @WT, B, 3)
    the cell value at column B, row 3 in the source worksheet of the 1st data plot.
@WT, ColIndex/ColName, ColLabelRowCharacter The worksheet cell value specified by the column index (or short name) and column label row character.
  • %(1, @WT, B, C)
    Similar to B[C]$, this will get the Comment from column B, in the source worksheet of the 1st data plot.

Note: When units are displayed in the substituted texts, the English and Japanese versions of Origin enclose the units in parentheses (), while the German version will use square-brackets [].