Expression Library and Expression Editor

 

Content

Overview

Expression Library

Expression Editor

Description

Expression Helpers

Cross SDI Helper

LabVantage Aggregate Expressions

 
 

 

 

Overview

Top../images/arwup.gif (846 bytes)

LabVantage provides two tools to assist in generating expressions used for arithmetic data manipulation and evaluation in Calculations: the Expression Library and the Expression Editor.

See Concepts of Transformations and Calculations for details and examples concerning Calculation syntax and functionality.

At a minimum, you should be familiar with these concepts and the related LabVantage features described therein:

• Concepts of Parameters and Parameter Lists
• Concepts of Parameter Limits
• Concepts of Specifications
• Concepts of Transformations and Calculations

 

Expression Library

Top../images/arwup.gif (846 bytes)

The Expression Library (System Admin → Configuration → Expressions) lets you define Groovy and Java expressions that can be reused in the Expression Editor.

Example Expression in the Expression Library

Field Description
ExpressionId Identifier of the Expression SDI.
Description Text description of the Expression displayed on the Expression List page.
Type Specifies how the expression is implemented:
TypeImplementation
GroovyGroovy closure.
JavaMethod in a Java class.
Namespace

Method

 "Namespace" defines the object on which the "Method" is called:
•The "LV" namespace is called on the LV object. This is the default namespace that is reserved for OOB expressions provided with the LabVantage core application. For example, LV.absoluteUncertainty( absVal ) is a predefined Uncertainty Calculation that is provided OOB with the LabVantage core application. To call this, "Namespace" would be LV and "Method" would be absoluteUncertainty( absVal ).
•If you want to call a method on your own object to generate your own custom expressions, enter your own object name in "Namespace" and specify your "Method". As shown in the example above, if your object is "Custom" and your method is diff( a, b ), the method call on the object would be Custom.diff( a, b ).
Implementation Defines the code required to define and execute the expression:
TypeDescription
GroovyFor Groovy expressions, this is the Groovy closure, e.g., { Math.abs( a - b ) }.
JavaFor Java expressions, "Implementation" is the package. The method must be specified in the "Method" field.
Button Description
Verify Expression Conducts a code syntax and structure check, then returns any errors detected in the expression.

These example expressions (called on the LV object) are currently provided OOB:

Expression Description
Average Returns an average with a < or > operator depending on the entered value. For example:
ValuesReturn
10, 20, >30>20
10, <20, <30<20
10, >20, <3020
DateOffsetInDays Calculates the date by adding or subtracting an offset in days.
DaysBetween Calculates the number of days between two dates.
Difference Returns the absolute value of the algebraic difference between two integers.
HourMinsBetween Calculates the difference (in hours:minutes) between two date times.
HoursBetween Calculates the difference (in hours) between two date times.
UnitConv* General purpose Unit conversion expressions.
UOM* See Parameter Lists → Description → Uncertainty → Uncertainty Calculations.

 

Expression Editor

Top ../images/arwup.gif (846 bytes)

Description

 

The Expression Editor provides an interface to build expressions. It is accessed at these locations:

• "Calculation Rule" field in the Reference detail of the Parameter List Maintenance page.
• "Transformation Rule" field in the Display detail of the Parameter List Maintenance page.
• "Transformation Rule" field in the Parameter Details detail of the Specification Maintenance page.
Field Description
Expression Type Determines the syntax rules used to write the expression. "Internal" refers to LabVantage syntax. "Groovy" refers to syntax used by Apache Groovy.
NOTE:"Internal" does NOT refer to "Internal Calculations" (involving a single SDI) as described in Concepts of Transformations and Calculations → Calculation Rules.
Expression Arithmetic expression for evaluation.
Expression Library Predefined expressions from the Expression Library (if using Groovy) or the LabVantage Aggregate Library (if using LabVantage). Set the cursor where in the Expression area where you want to insert the expression, then click the expression (Groovy example shown):
Parameters Parameters used in the expression. Replace the variable in the Expression area with the desired Parameter (Groovy example shown):

For assistance with specifying Parameters and Parameter Lists, use the Expression Helpers.
Test Tests the expression. Enter test values for the expression, then choose the "Data Type" (Numeric, Text, or Date). Clicking "Test" executes the test (Groovy example shown):

As described in Referencing Data Items by an SDIDataItem Column, you can use the (all) syntax for Groovy expressions to return a map of an entire SDIDataItem record. However, the Expression Editor does not have the capability to return actual values from an SDIDataItem record. Accordingly, it cannot interpret actual values when using the "Test" function for expressions that use the (all) syntax to return a map of an entire SDIDataItem record. The message shown below will be returned.

NOTE:When testing Groovy Calculation Expressions, the Security Policy offers the "Groovy Script Filter" to prevent selected Java packages, classes, and methods from being called from within your Groovy scripts.

Expression Helpers

 

Expression Helpers assist with specifying Parameters (Param Helper), Parameter Lists (ParamList Helper), Primary SDIs (Primary Helper) and Reference Calculations (Cross SDI Helper). Functionality is identical for LabVantage and Groovy expressions (syntax is automatically adjusted for each). Selections are displayed in a cascading fashion, providing the subsequent column based on your selection. As you choose each item, the expression is updated at the top of the page.

Parameter Helper

 

Parameter List Helper

 

Primary Helper

The Parameter dropdown lets you select any Parameter associated with the current Parameter List.

Selecting a Parameter prompts for a Parameter Type. Choose from the list of values for the current Parameter List, or choose a wildcard.

You can then select a Replicate. Specify the Replicate number, or choose a wildcard or max value.

For examples demonstrating syntax and usage, see these areas of Referencing Data Items by an SDIDataItem Column:

Option Description
Column IdColumn Name Reference
AttributeAttribute Reference
Parameter LimitParameter Limit Reference
  

The Parameter List Helper functionality is similar to the Parameter Helper (offering successive choice of Parameter List, Version, Variant and Data Set).

For examples demonstrating syntax and usage, see these areas of Referencing Data Sets by an SDIData Column:

Option Description
Data Set Filter Multiple Column Expressions with Logical AND
Column Id Column Name Reference and Filtering
Attribute Attribute Reference

The ParamList Helper shows AttributeIds defined for the DataSet and SDIWorkItem SDCs (see Attributes Not Defined for a Data Set).

The Param tab functionality is the same as in the Parameter Helper.

   The Primary Helper lets you choose the current SDI and SDI column or SDI Attribute.

 

 

Cross SDI Helper

 

The Cross SDI Helper handles Reference Calculations.

Begin by selecting the Source SDC (this is the SDC associated with the Parameter List). Then, select options for any of the Reference Calculation scenarios described below (follow the links for conceptual examples). As you choose each option, LabVantage provides an textual explanation of what you have chosen. ParamList and Param tab behavior is identical to that of the Parameter List Helper.

NOTE:   The "Primary" tab in the Cross SDI Helper lets you choose SDCs that allow Attributes along with SDCs that allow Data Entry. The Primary tab in other Helpers shows only SDCs that allow Data Entry.

If an SDC that does not allow Data Entry is selected, the ParamList and Param tabs prevent selecting a Data Set or Data Item with the selected link.
Option Scenario and Link to Example Choose...
Absolute Explicit Reference to a Single SDI SDC and SDI.
Foreign Key Foreign Key Reference to a Single SDI Column that contains the link.

The dropdown shows foreign key links from SDIWorkitem, SDIData, and SDIDataItem to the primary SDC that allows Data Entry and Attributes.

When a foreign key link is selected, the linked SDC is automatically selected in the Primary tab and its columns and Attributes (if any) are shown in the dropdown.
Reverse FK Reverse Foreign Key Link SDC and its column.

When a reverse foreign key link is selected, the linked SDC is automatically selected in the Primary tab and its columns and Attributes (if any) are shown in the dropdown.
SDIRelation SDI Relation Relation Type. Multiple Relation Types can be specified.
SDIDataRelation SDI Data Relation Relation Type. Multiple Relation Types can be specified.
Array Array Calculation See Master Data Setup → Array Methods → Adding a New Array Method → Parameters → Calculation Rule.
Sample Parent/Child Relation Sample Parent/Child Relation Relationship between Parent and Child Sample.
AQC Using Calculations with QC Samples (AQC) QC Sample, Position, and Level.
Absolute   Foreign Key   Reverse FK
   
SDIRelation   SDIDataRelation   Array
     
Sample Parent/Child Relation        
       

LabVantage Aggregate Expressions

 

This is the library of predefined expressions available for use in the Expression Editor. All are in LabVantage expression syntax.

The variable "x" is used below to indicate the operand, which can be any representation of a Parameter that is described in Concepts of Transformations and Calculations. When creating an eval expression, the variable [this] can also be used to represent user input as described in Parameter Lists → Description → Display → Create a Conditional Display Format.

Various implementations of rounding functions throughout the LabVantage application use different terminology to describe the same function. Also note that some areas of the application use "Rounding Function" instead of "Function" and "#Digits" instead of "Precision". Here is a translation of the terminology used for the function (where n is the Precision) to the actual calculation syntax that is used in the Expression Editor and described below:
 
FunctionExpression
Basic Roundinground( [x], n )
EvenOdd Roundingastmround( [x], n )
Basic SigFigsigfig( [x], n )
InOrganic SigFigclpinorgsigfig( [x], n )
Organic SigFigclporgsigfig( [x], n )
Hybridmaxsigfigdp( [x], n )
Function Description
abs( [x] ) Calculates the absolute value of x.
astmround( [x], n ) Rounds according to ASTM E29-02 rounding rules (see Note 1).
avg( [x] ) Calculates the average of x, where x represents multiple values. Example: If x = 119 246 322, this returns 229.
case( [x] when [a] then [b] when [c] then [d]... else [e]) Standard case statement. Compares the value of x against other values (a, b, c, d, ..., n), then returns e if no match is found.
ceiling( [x] ) Determines the smallest whole number that is greater than or equal to x.
clpinorgsigfig( [x], n ) Rounds a number x to n significant figures according to USEPA rounding rules for inorganics analysis (see Note 2).
clporgsigfig( [x], n ) Rounds a number x to n significant figures according to USEPA rounding rules for organics analysis (see Note 2).
cos( [x] ) Calculates the cosine of x (where x is in radians).
count( [x] ) Determines the number of rows specified by the argument.
exp( [x] ) Raises e to the power x, where e is the base of natural logarithms.
fact( [x] ) Calculates the factorial of x.
first( [x] ) Returns the first value of x, where x represents multiple values. Example: If x = 7 9 11, this returns 7.
if( [b], [t], [f] ) Evaluates the condition where:

b is a boolean expression that evaluates to True or False.
t is a string containing the value you want returned if the boolean expression is True.
f is a string containing the value you want returned if the boolean expression is False.

See Note 3.
int( [x] ) Determines the largest whole number less than or equal to x.
isnull([x]) Reports whether or not the value of x is Null.  Returns True if Null and False if not.
last( [x] ) Returns the last value of x, where x represents multiple values. Example: If x = 7 9 11, this returns 11.
log( [x] ) Calculates the natural logarithm of x.
logten ( [x] ) Calculates the base 10 logarithm of x.
max( [x] ) Returns the largest value of x, where x represents multiple values. Example: If x = 2 17 9, this returns 17.
maxsigfigdp( [x], n ) Rounds a number x to both n significant figures and n decimal places (see Note 2).
min( [x] ) Returns the smallest value of x, where x represents multiple values. Example: If x = 17 2 9, this returns 2.
mod( [x], n ) Calculates the remainder (modulus) of a division operation, where x is the numerator.
pi( [x] ) Calculates the product of p and x.
rand( [x] ) Obtains a random whole number between 1 and the upper limit specified by x. The lower limit is always 1. The upper limit is 32,767.
round( [x], n ) Rounds a number x to the specified number n of decimal places (see Note 4).
sigfig([x], n ) Rounds a number x to n significant figures (see Note 2).
sign( [x] ) Reports if x is negative, zero, or positive.
sin( [x] ) Calculates the sine of x (where x is in radians).
sqrt( [x] ) Calculates the square root of x.
stdev( [x] ) Returns the standard deviation of x.
sum( [x] ) Returns the sum of x, where x represents multiple values. Example: If x = 10 100 1000, this returns 1110.
tan( [x] ) Calculates the tangent of x (where x is in radians).
truncate( [x], n ) Truncates a number x to the specified number n of decimal places.
var( [x] ) Calculates an estimate of the variance for the specified column. The variance is the square of the standard deviation.
NOTES
1.

astmround( [x], n )

This function rounds a value to a specified number of decimal places.

The rounding method is defined in ASTM Designation E29-02 "Standard Practice for Using Significant Digits in Test Data to Determine Conformance with Specifications", paragraph 6 "Rounding Methods". Note that although the term "Significant Digits" appears in the title of the ASTM Designation, only the decimal-based rounding methods in paragraph 6 apply.

Example: astmround([this], 2) rounds to 2 decimal places according to the rules demonstrated in the following examples:

[this] Result and Rounding Rule
1.234 1.23

If third decimal place is <5, drop it.
1.236 1.24

If third decimal place is >5, round-up second decimal place.
1.235

1.255

 1.24

1.26

If third decimal place is =5, increment second decimal place to an even number.
1.245 1.24

If third decimal place is =5 and the second decimal place is already an even number, drop third decimal place.
2.

sigfig( [x], n )

These basic rules apply to sigfig( [x], n ):

• All non-zero digits are significant. For example, 129.454 contains 6 significant figures.
• All leading zeros of a number are considered placeholders and, as such, are not significant. For example, 0.0012 contains 2 significant figures.
• All zero digits between non zero digits are significant. For example, 3.004 contains 4 significant figures.
• All zeros that occur at the end of a number that includes an expressed decimal point are significant. For example, 1.230 contains 4 significant figures.
• All zeros to the left of an expressed decimal point are significant. For example, 100. contains 3 significant figures.
• All zeros that occur at the end of a number that does not include an expressed decimal point are ambiguous. They are considered not significant. For example, 2000 contains 1 significant figure.

When rounding to the least significant digit, sigfig( [x], n ) uses basic rounding when looking at the first non-significant digit, with optional increment of the least significant digit. For example:

• If the first non-significant digit is less than 5, truncate all non-significant digits. For example, 1.23 rounded to 2 significant figures yields 1.2.
• If the first non-significant digit is greater than 5, increment the least significant digit and truncate all non-significant digits. For example, 1.27 rounded to 2 significant figures yields 1.3.
• If the first non-significant digit is equal to 5, increment the least significant digit and truncate all non-significant digits. For example, 1.25 rounded to 2 significant figures yields 1.3.

clpinorgsigfig( [x], n )

Rounding rules for clpinorgsigfig( [x], n ) differ from sigfig( [x], n ) when the first non-significant digit is equal to 5. For example:

• If there are non-zero digits to the right of the 5, increment the least significant digit. For example, 1.25003 rounded to 2 significant figures yields 1.3.
• If the least significant digit is even, truncate all non-significant digits. For example, 2.25000 rounded to 2 significant figures yields 2.2.
• If the least significant digit is odd, increment the least significant digit and truncate all non-significant digits. For example, 3.35000 rounded to 2 significant figures yields 3.4.

clporgsigfig( [x], n )

Rounding rules for clporgsigfig( [x], n ) differ from clpinorgsigfig( [x], n ) in that the odd/even rule is used even when there are non-zero digits to the right of the 5. For example, when the first non-significant digit is equal to 5:

• If the least significant digit is even, truncate all non-significant digits. For example, 2.253 rounded to 2 significant figures yields 2.2.
• If the least significant digit is odd, increment the least significant digit and truncate all non-significant digits. For example, 3.35000 rounded to 2 significant figures yields 3.4.

maxsigfigdp( [x], n )

This uses the same rounding rules as sigfig( [x], n ). However, maxsigfigdp( [x], n ) always limits the number of decimal places to n, even if n significant figures cannot be displayed in n decimal places. For example:

• 1.23456 rounded to 3 sigfig/dps is 1.23.
• 0.12345 to 3 significant figures yields 0.123.
• 0.01234 to 3 significant figures yields 0.012.
• 0.00123 to 3 significant figures yields 0.001.
• 0.00012 to 3 significant figures yields 0.000.
3.

if( [b], [t], [f] )

When evaluating an if(b, t, f) function that contains null values, the value returned depends on the "Honor Null in Relational Expressions" and "Honor Null in AND/OR Conditional Expressions" properties of the Data Entry Policy.
4.

round( [x], n )

In general, this is intended to be a conventional rounding function, i.e., rounding 1.2345 to 2 decimal places results in a returned numeric value of 1.23.

However, rounding an integer expressed as a decimal (such as 4.00) returns only the integer. For example, rounding 4.00 to 2 decimal places actually calculates and returns 4. This is because Transformation and Calculation expressions return a numeric value, and in this case, 4 and 4.00 have the same numeric value. In order to render the return as 4.00 in the interface, the "Display Format" must be set to render 4.00 (see Parameter Lists → Description → Display), as the Display Format determines the result that is actually displayed.

Be advised that rounding the numeric result affects downstream Calculations and Limit evaluations. As such, it is usually a better option to round using the Display Format.