Lab Logic Toolkit Script Examples

BaseSpace Clarity LIMS Lab Logic Toolkit (LLTK) provides the evaluateDynamicExpression script, which allows for the evaluation of simple dynamic expressions.

This article provides examples that you can modify to suit the needs of your lab.

For details on script parameters and usage, and additional examples, see the Working with Lab Logic Toolkit article.

Setting QC flags

See the Setting QC Flags article.

Setting next actions

See the Setting Next Actions article.

Create string from multiple UDFs and add additional characters

-exp 'submittedSample.::Run Name:: = step.::Source:: + ::_:: + step.::Numeric ID::'

Determine total number of samples

This example assumes that the step UDF / custom field Total samples has a default numeric value of 0:

-exp '(step.::Total samples:: = step.::Total samples:: + 1)'

Without a default value, the expression must set the initial value before continuing to sum:

-exp 'if(step.hasValue(::Total samples::)) { step.::Total samples:: = step.::Total samples:: + 1 } 
else { step.::Total samples:: = 1 }'

Calculate concentration from a dilution factor

-exp 'output.::Concentration (nM):: = (input.::Concentration:: * step.::Dilution Factor::)'

Calculate volume of buffer and source sample to dilute

-exp 'output.::Diluent Needed:: = step.::Desired Volume:: - output.::Sample Volume::'

Calculate the remaining amount of submitted sample left after the step

-exp 'submittedSample.::Sample Volume:: = submittedSample.::Sample Volume:: - output.::VolumeUsed::'

Calculate volumes of all components to add to master mix (e.g., PCR reaction)

-exp ‘(step.::Component1:: = step.::NumberofSamples:: * 1.5) ; 
(step.::Component2:: = step.::NumberofSamples:: * 0.5) ; 
(step.::Component3:: = step.::NumberofSamples:: * 5)’ -log {compoundOutputFileLuid0}"

Calculate nM from concentration and size

-exp 'output.::Concentration (nM):: = (input.::Concentration:: / input.::Average length (bp)::)
* 1540.832'

Determine dilution to populate robot file

-exp 'output.::Sample Needed (uL):: = step.::Input Amount (ng):: / input.::Library Concentration:: ;
 if ( output.::Sample Needed (uL):: > step.::Final Volume (uL):: ) { output.::Sample Needed (uL):: =
 step.::Final Volume (uL):: } ; if (output.::Sample Needed (uL):: < 1.0 ) 
{ output.::Sample Needed (uL):: == 1.0 } ; output.::Diluent Volume (uL):: = 
step.::Final Volume (uL):: - output.::Sample Needed (uL):: ; output.::Final Amount (ng):: =
 output.::Sample Needed (uL):: * input.::Library Concentration::'

Calculate average concentration

This example demonstrates the use of step UDFs / custom fields to store temporary values in order to enable calculations between iteration.

-exp 'output.::Concentration::=input.Concentration ;
if(!step.hasValue(::No. of samples::)) { step.::No. of samples:: = 0 } else { step.::No. of samples:: += 1 }; 
if(!step.hasValue(::Total Conc.::)) { step.::Total Conc.:: = 0 } else { step.::Total Conc.:: += output.Concentration };
if(!step.hasValue(::Average Conc.::)) { step.::Average Conc.:: = 0 } 
else { step.::Average Conc.:: = step.::Total Conc.:: / step.::No. of samples:: };' 

Check container name changed from default value

This example checks that the container name has been changed from the default value (container LIMSID)

-exp 'if (output.container.name == output.container.node.@limsid) { fail(::Invalid Barcode. 
Please verify and try again.::) }'

Calculate yield of sequenced samples using the submittedSamples entity

submittedSamples.each { it.::Workflow Progress:: = ::Sequencing Finished:: }; 
if (!input.hasValue(::Lane Failed?::) || !input.::Lane Failed?::) { def acquiredYield = 0; 
if (input.hasValue(::Yield PF (Gb) R1::)) { acquiredYield += input.::Yield PF (Gb) R1:: }; 
if (input.hasValue(::Yield PF (Gb) R2::)) { acquiredYield += input.::Yield PF (Gb) R2:: }; 
acquiredYield = acquiredYield / submittedSamples.size(); submittedSamples.each { currentSample -> 
def currentSampleAcquiredYield = acquiredYield; 
if (currentSample.hasValue(::Acquired Yield (Gb)::)) { currentSampleAcquiredYield += 
currentSample.::Acquired Yield (Gb):: }; currentSample.::Acquired Yield (Gb):: =
currentSampleAcquiredYield; currentSample.::Missing Yield (Gb):: = 
currentSample.::Required Yield (Gb):: - currentSampleAcquiredYield }

This example includes Groovy Closures, using both implicit variables (it) and explicit variable names (for example, currentSample).

Concatenate strings

submittedSample.::Lab Comments:: = output.::Sample Comment::.toString() + ::; :: 
+ submittedSample.::Lab Comments::.toString()

Regex example: Validate output container barcode mask

-exp 'if ( !output.container.name.matches( ::LP[0-9]{7}-QSTD:: )) 
{fail ( ::Invalid QSTD Plate Barcode. Please verify and try again.:: ) }'

Regex example: Verify format of flow cell / reagent cartridge barcode

Check the flow cell/reagent cartridge format (Illumina’s flow cell check) as follows:

-exp 'if(!output.container.name.matches(::^[Hh][0-9A-Za-z]{4}([Bb][Bb]|[Cc][Cc]|[Aa][Ll])[Xx][Xx]$::)) 
{ fail(::Invalid Patterned Flowcell Barcode. Please verify and try again.::) }'

Regex example: Validate a scanned / manually entered container barcode

-exp 'if ( !output.container.name.matches( ::LP[0-9]{7}-QNT:: ) &&
 !output.container.name.matches( ::LP[0-9]{7}-SQNT:: ) ) 
{fail ( ::Invalid QNT & SQNT Plate Barcodes. Please verify and try again.:: ) }'

Populate a Timestamp (Single-line Text and Text) UDF / custom field

The following expression results in the format: Wed Apr 03 21:28:38 EDT 2015

-exp 'step.::Timestamp:: = new Date().toString()'

Populate a Timestamp (Date) UDF / custom field

The following expression results in the format: 2015-04-03

-exp 'step.::Timestamp:: = new Date().format(::yyyy-MM-dd::)'

Add values within a pool

This example assumes that the analyte / derived sample UDF Pool Volume (uL) has a default numeric value of 0.

-exp 'output.::Pool Volume (uL):: = output.::Pool Volume (uL):: + input.::Volume (uL)::'

This can also be done without setting a default value for the UDF:

-exp 'if(output.hasValue(::Pool Volume (uL)::)) { output.::Pool Volume (uL):: = output.::Pool Volume (uL):: 
+ input.::Volume (uL):: } else { output.::Pool Volume (uL):: = input.::Volume (uL):: }'

Convert placement information to a numeric position

The example below assumes the following:

• The placement is alphanumeric (e.g., A:1)

• The offset for the alphabetical row is 0, and the offset for the numeric column is 1

• The placement order desired is horizontal: A:1 maps to 1, A:2 maps to 2, etc.

• The placement of interest is the output placement

• Placement is configured for a specific, known container type, and the dimensions of this container type are also known. This example uses a 96 well container configuration (12 columns are available and this value is used directly in the expression below). This value can be replaced for other container types.

-exp 'output.::Position:: = (((output.well.split(:: : ::.trim())[0].toString().toUpperCase() as char) 
- (::A:: as char)) * (int) Math.pow(26, 0)*12) + output.well.split(:: : ::.trim())[1].toInteger()'

Note the following:

• The call to split() here will return a list of row:column, so we use [0] and [1] to access these values, respectively.

• :: : ::.trim() is used to obtain the result ':' - because :: is used as a reserved character, and thus ::::: directly results in '': and errors.

Set the error status bar message

See the Failing a Script article.

Check for special characters

In some cases, special characters are not permitted in a field in the LIMS. To prevent users from entering special characters, the best practice is to include validation to check that the field contains only letters and/or numbers. Wherever possible, we recommend that you use this 'positive checking' method as it is much less error-prone. However, if this preferred method is not possible, you can use the Lab Logic Toolkit to check for the presence of special characters, and display an error message if one is found.

The following example use the Groovy matches command to check step output container names for the characters ? ( ) [ ] / \ and quotes or spaces.

-exp 'if (output.container.name.matches(::.*[\u0022\u0027?()\\[\\]/\\\\ ].*::)) 
{ fail(::The following characters are not allowed in the Container Name: ? ( ) [ ] / \ and quotes or spaces.::) }'

The matches command

The matches command takes a regular expression (regex) as its input. Call this command on the field you want to check.

In our example, the matches command is:

output.container.name.matches(::.*[\u0022\u0027?()\\[\\]/\\\\ ].*::)

If we isolate the regex, we have:

.*[\u0022\u0027?()\\[\\]/\\\\ ].*

Here, we're checking for any text that contains any one of the special characters listed. It's important to note that the way regex is supported in Java (and therefore Groovy) leads to some quirks, noted in the following table.

Entry	Standard regex representation	Character being checked for
\u0022 and \u0027	' and "	Single and double quotes
?	\?	Question mark
( and )	\( and \)	Brackets
[ and ]	\[ and \]	Square brackets
/	\/	Forward slash
\	\\	Backslash
(space)	\s	Spaces

Escaping characters Normally, in regex we would need to escape the following characters using a single backslash:

.^$*+?()[{|-]\

However, because of how matches works, not all of these characters need to be escaped - for example the '?' character. Characters that do still need to be escaped, need to be escaped with an additional backslash (e.g., \\).

Checking for quotes Because the command is run via Automated Informatics / Automation Worker, we also need to use a different approach for checking for quotes.

We cannot use them as we typically would when writing a regex expression (e.g., "), or escape them as we would in a call to matches (e.g., \"). Instead, we need to provide them as their unicode number, shown in our example as \u0022 and \u00.

Resources

• Unicode character table

• Java Pattern documentation

• Regex visual tool

• Regex tester

• Groovy dates and times