These release notes detail the key changes to software components for the Next Generation Sequencing (NGS) Extensions Package v5.25.1.
Compatibility
Refer to Compatibility under Instruments & Integrations.
Defects and Security Vulnerability Fixed
Template File Generator - fixed script failure when reading project UDF from a pool containing control sample.
Fixed security vulnerabilities.
Known Issues
An error occurs when reformatting the date using the Lab Logic Toolkit with the Date utility class. The date reformatting can be done with java.time instead.
Release Notes
Next Generation Sequencing Package
The Illumina Preconfigured Workflows Package (PCWP) supports the integration of Clarity LIMS with established lab protocols. The integration provides preconfigured workflows that map to lab protocols and steps, and support Illumina library prep kits, reagent kits, and controls. For detailed information on the installed workflows, see the instrument integrations and protocols documentation.
Label Non-Labeled Outputs
Available from: Clarity LIMS v2.0.5
A user may need to add reagent labels to sample outputs that do not have reagent labels assigned to them.
Script Overview
The labelNonLabeledOutputs script provides the ability to add reagent labels to sample outputs for which there is no pre-existing reagent label.
The script checks each process output for existing reagent labels; if an output does not have at least one pre-existing reagent label then the label supplied as a script parameter is applied.
For each output that does not already have a reagent label applied to it (e.g. control samples), the script will apply a reagent label named with the supplied string.
In the Preconfigured Package for Illumina NGS, all sequencing libraries go through a demultiplex process to both convert data to FASTQ and demultiplex reads if necessary. Note that presently, inputs that do not have a reagent label do not create an output in a demultiplex process even though we need BCL convertor to convert their reads to FASTQ.
Script Parameters
Command Line Example
Example
You may also find the following script useful:
Process Summary Report
Available from: Clarity LIMS v2.0.5
Often, a user wants to determine what work has been performed on several samples by running the Sample History Report. However, suppose they were to use the sampleHistoryReport script on 600 samples that involve the same four processes. The result would be 600 reports (one for each sample), each of which provides information on only that one sample.
A preferable alternative is to use the processHistoryReport script, which is run only once for each process. In this example, therefore, it would produce only four reports (one for each process) allowing for a better grouping of information and less files.
Parameter
Description
-u {username}
(Required) LIMS login username
-p {password}
(Required) LIMS login password
-i {URI}
(Required) LIMS process URI (must have at least one sample output)
The processHistoryReport script has two parts: 1. Retrieve the necessary information, and 2. Compile that information into a report.
The script generates one report ('Process Summary Report') for all inputs, output as a single shared result file.
The script is configured on the Illumina Sequencing (Illumina SBS) 5.0 step, as 'Report creation script.'
The report is generated in XLS format using POI.
The report is automatically attached to the pre-configured report process result file output.
Script Parameters
Parameter
Description
-u {username}
(Required) LIMS login username
-p {password}
(Required) LIMS login password
-i {URI}
(Required) LIMS process URI
Adding Processes to a Report
Add a process UDF of type Checkbox, with the exact name of the process you want to include. For example: "3. Denature, Dilute and Load Sample (MiSeq)"
When the process is run, select the checkbox to include that process in the Process Summary Report.
Note that the script may also be run in the following directory:
Configuration
Report process configuration may be obtained using the LIMS configuration import/export tools or the LIMS Config-Slicer tool.
Rules & constraints
The script must be run from the LIMS Operations Interface.
To be included in the report, a process must have at least one output UDF specified.
The report requires a pre-configured process type + EPP parameter string ('TruSeq Process Summary Report').
The report runs from the specified artifact down the genealogy tree. For complete and correct output, it is recommended that it be run on the original submitted samples.
The Clarity LIMS NGS Extensions Package v5.14 and later includes the validateUniqueIndexes script. When defining a batch of samples for library prep, this script ensures that the resulting batch will be valid for later workflow steps - such as pooling or sample sheet generation.
This section provides details on the script, its parameters, and LIMS configuration requirements.
Script Overview
The validateUniqueIndexes script checks that the reagent labels (referred to as reagent types in LIMS v4.x and earlier) attached to the input samples have distinct index sequences.
By default, validation will fail:
If input samples have the same reagent labels.
If input samples have reagent labels with different names but the same index sequence.
If the Ice Bucket contains more than one unindexed sample (see ).
Pool Types
An input is considered to be a pool if it contains multiple submitted samples and/or multiple reagent labels. A typical pool comprises multiple submitted samples and multiple labels; however, the following less common, and more complex, use cases are also supported.
A submitted pool
This has one submitted sample, but multiple labels - therefore it is considered a pool.
Multiple submitted samples pooled together without labels
This has multiple submitted samples - therefore it is considered a pool.
A single submitted sample with replicates recombined back into a pool
If the recombination is done with adding labels to the replicates, it is considered a pool.
If the recombination is done without adding labels, it is not considered a pool.
Script Parameters
Command Line Example
Example 1
Note that this command line also uses the Sample Placement Helper script (PlacementHelper.jar), included in the Lab Instrument Toolkit.
Example 2
Configuration
The validateUniqueIndexes script is intended to run when the user selects the Begin Work button on the Ice Bucket screen and starts the step.
To achieve this, configure the automation trigger as follows:
Trigger Location: Step
Trigger Style: Automatic upon entry / exit
Rules and Constraints
Each reagent label name must be unique. The label name is only used to look up the corresponding index sequence in the API. However, if two or more label groups (referred to as reagent categories in LIMS v4.x and earlier) contain labels with the same name, the LIMS will not be able to distinguish between them and the validation script will fail.
The script does not look upstream for labels - it only looks at the labels currently applied to the step inputs.
The Ice Bucket may include one input sample with no index assigned, therefore allowing a PhiX or similar control to be included in the pool (a control will typically have no label - this scenario is supported and the validation script will run without error).
If any input sample is a pool (see ). You can change this behavior using the -allowPools command-line option (see ).
If pools are allowed, they will be validated like other input samples.
Every index sequence applied to step inputs in the pool will be considered when checking for duplicated sequences (see ).
For LIMS v4.x and earlier, this also applies to samples with a reagent type that is not an index. Note, however, that in any scenario, the label must exist as a reagent type in the LIMS. If you add a label to an input, and the label does not have a corresponding reagent type, the validation script will fail. See note below.
ℹ In LIMS v4.x and earlier, a reagent type may not be an index type. In this case, it will have a label and a corresponding reagent type, but no sequence value. This scenario is supported and the reagent type is treated as non-indexed. It is also possible, via the API, to add labels arbitrarily to samples, without those labels having a corresponding reagent type - this scenario is not supported.
Parameter
Description
-u {username}
-username {username}
(Required) LIMS login username
-p {password}
-password {password}
(Required) LIMS login password
-i {stepURI:v2}
-stepURI {stepURI:v2}
(Required) LIMS step URI
-allowPools <true/false>
(Optional) Default is false. When provided and set to true, the script will allow pools as inputs to the step.
By default, validation will fail if any input contains multiple submitted samples or multiple reagent labels.
The Clarity LIMS NGS Extensions Package includes the validateSampleCount script, which checks the number of samples being input to or output by the step.
This article provides details on the script and its parameters, and LIMS configuration requirements.
Script Overview
The script validates the number of step inputs or outputs, comparing it against configurable minimum and maximum values - determined by -min and -max parameters.
By default, the script runs in count inputs mode and validates the step inputs. If you supply the optional -o parameter with value set to true, the script runs in count outputs mode and validates the step outputs.
Count inputs mode
The typical use case for count inputs mode is to ensure that the correct number of samples is being input to the step.
The validateSampleCount script is triggered when the user clicks the Begin Work button to exit the Ice Bucket screen and start the step.
The script compares the number of analyte / derived sample step inputs to the -min and -max parameter values.
Count outputs mode
The typical use case for count outputs mode is to ensure that enough replicates (derivatives) are created to fill a flow cell:
The validateSampleCount script is triggered when the user clicks the Begin Work button to exit the Ice Bucket screen and start the step.
Script Parameters
Command Line Examples
Count inputs mode
Two examples are provided below; both set the script to count inputs mode. In the first example, the -o parameter is provided and set to false. In the second example, the -o parameter is omitted.
Count outputs mode
Configuration
The validateSampleCount script is intended to run when the user clicks the Begin Work button on the Ice Bucket screen and starts the step.
To achieve this, configure the automation trigger as follows:
Trigger Location: Step
Trigger Style: Automatic upon entry
Normalization Buffer Volumes
Available from: Clarity LIMS v1.0
This section discusses the normalizationBufferVolumes script, which is used to calculate buffer volumes.
Script Overview
The normalizationBufferVolumes script generates a comma-separated file — Normalization buffer volumes.csv — file that holds the calculated buffer volumes information. The generated file is a attached to the Library Normalization step in the LIMS.
The script calculates the 'Volume of Dilution Buffer (uL)' as follows:
Maximum destination container volume (ul): Numeric, Default = 800
The inputs to the step must have values for the following sample UDFs:
Concentration: Numeric
Conc. Units: Single Line Text
Rules & constraints
One sample input generates one sample output and one shared result file.
The CSV file header contains the date and a record of the user who generated the file.
The contents of the CSV file are ordered by source plate and then source well.
Additional information
Other scripts you may find useful:
Copy UDFs
Available from: Clarity LIMS v2.0.5.
Often, a user has certain values associated with libraries prior to preparing a flow cell. When loading the libraries into the flow cell, the user needs to track these values as attributes of the flow cell lane to help interpret the metrics generated during sequencing.
For example, one might need to record a concentration as a sample UDF on normalized and pooled libraries. This can be accomplished by copying the value of identically named UDFs from inputs to non-shared outputs.
Script Overview
The copyUDFs script provides the ability to selectively copy the value of an input UDF to a UDF of the same name on outputs generated by a protocol step (process). Other capabilities of this script include:
The ability to map a single input to one or more outputs
The ability to define which UDF is copied across to outputs
Script Parameters
Command Line Example
Example
ℹ In the example shown above, the paths may differ for your system. For example, the version number may differ.
Constraints
Only the UDFs named in the -f (fields) parameter will be copied.
If input UDFs are not defined or have no value, nothing will be copied for those UDFs.
UDFs not being defined on an output result in the script aborting after displaying an error message.
NGS Extensions v5.24.0
Last Updated: November 2024
Release Date: February 2024
Document Version: 2
These release notes detail the key changes to software components for the Next Generation Sequencing (NGS) Extensions Package v5.24.0.
Compatibility
Refer to under Instruments & Integrations.
New Features
Added the following scripts:
validate_selected_container
validate_same_udf_valuee_for_analytes
Defects Fixed
None
Known Issues
An error occurs when reformatting the date using the Lab Logic Toolkit with the Date utility class. The date reformatting can be done with java.time instead.
Other
The -s in the stopwatch parameter is replaced with -stopwatch in NGS v5.21 and later.
Revision History
NGS Extensions v5.23.0
Last Updated: November 2024
Release Date: September 2023
Document Version: 2
These release notes detail the key changes to software components for the Next Generation Sequencing (NGS) Extensions Package v5.23.0.
Compatibility
Refer to Compatibility under Instruments & Integrations.
New Features
Updates Java and third-party dependency libraries.
Updates Groovy to v3.0.7.
Stopwatch parameter -s is replaced with the -stopwatch parameter for NGS 5.21.0 and later.
Defects Fixed
The sample sheet for the MiSeq now shows the following information:
The pool name instead of the sample name when the pool contains only one sample.
The well and plate information for submitted samples instead of for libraries.
Fixed issue where the template file generator created duplicate lines for the first data source entry when using multiple data sources.
Fixed issue where the driver file generator did not append the existing log file.
The changeWorkflow script on the No Output step reflects the correct number of samples being routed.
Fixed the Insecure Input Validation (SRCCLR-SID-22742) vulnerability.
Fixed degradation of the LLTK script performance when updating the custom field with an empty string.
Fixed degradation of the log file download performance when automation performs write actions on an existing log file.
Improved the LLTK script error messages to show details of artifacts.
Known Issues
An error occurs when reformatting the date using the Lab Logic Toolkit with the Date utility class. The date reformatting can be done with java.time instead.
Revision History
Version
Changes
2
Updated Compatibility section to reference Compatibility matrix table.
1
Initial release.
The script is not applicable to shared outputs.
UDFs of the same name must be present in the input and enabled as an output detail.
Lies within the -min and -max value range, the user proceeds to the next screen.
Is less than the -min value or more than the -max value, user is returned to the Ice Bucket screen.
The script compares the number of step outputs to the -min and -max parameter values.
The script counts all per-input outputs, both analyte / derived sample and result file / measurement types.
The script ignores Shared ResultFiles / step file placeholders and pool outputs.
If the number of outputs:
Lies within the -min and -max value range, the user proceeds to the next screen.
Is less than the -min value or more than the -max value, user is returned to the Ice Bucket screen.
Parameter
Description
-u {username}
(Required) LIMS login username
-p {password}
(Required) LIMS login password
-i {stepURI:v2}
(Required) LIMS step URI
-o <true/false>
(Optional) Set this parameter to true to run the script in count outputs mode. If the parameter is omitted or has a value other than true, the script will run in count inputs mode.
-min <#>
(Optional) Specifies the minimum number of inputs / outputs required. If not provided, default minimum is 0.
-max <#>
(Optional) Specifies the maximum number of inputs / outputs required. If not provided, default maximum is 2147483647.
This section discusses using the initArtifactUDFs script to transfer the UDFs associated with samples and processes to downstream artifacts. Typically, the script is used to copy UDFs from sample inputs and processes to sample outputs.
Script Overview
For each output, the initArtifactUDFs script searches for UDFs of the same name - in both the input samples and the process. If a match is found, it then copies the UDF values to the corresponding UDFs on the sample output.
How it works:
Identify the list of sample UDFs configured as output UDFs for this process (e.g. as would be defined in the 'Output Details' section of the process configuration).
For each sample UDF, look for an identically named UDF on the submitted sample; if a match exists, copy the value from the submitted sample to the sample's output UDF. If there is no UDF match, do nothing.
For each sample UDF, look for an identically named UDF on the process; if a match exists, copy the value from the process to the sample's output UDF. If there is no UDF match, do nothing.
Useful information
If both process and any number of samples have values for the same UDF name, the process UDF value is used.
If multiple samples have different values for the same UDF name, the values are combined using '+' as a separator (up to 5 values, additional values are omitted and represented with ''...').
In the case where an output UDF value already exists, the initArtifactUDFs script will NOT override existing values. (This scenario is extremely rare - one has to be very fast to manually set UDF values before an EPP script runs.)
Script Parameters
Command Line Example
Example
ℹ In the example shown above, the paths may differ for your system. For example, the version number may differ.
Validate Complete Plate
Clarity LIMS NGS Extensions Package v5.17 and later includes the validateCompletePlateStarted script. This script checks that all samples in a container were started together on the current step. This section provides details on the script and its parameters, and LIMS configuration requirements.
Script Overview
The purpose of the validateCompletePlateStarted script is to make sure that all of the samples in the input plate were started together. The validation supports partially-filled plates and multiple plates.
You can supply additional parameters to the script, to optionally enforce:
'Cannot proceed with partial plate' logic for only for the samples that are queued to the current step, instead of the entire plate contents. Default is false—the entire plate contents are verified.
Contiguous row-major or column-major layout. This makes sure that the input plate(s) are in the expected layout and contain no gaps between the first and last sample. By default, this is not enforced.
Script Parameters
Command Line Examples
Example 1Example 2
Configuration
The validateCompletePlateStarted script is intended to run when the user selects the Begin Work button on the Ice Bucket screen and starts the step.
To achieve this, configure the automation trigger as follows:
Trigger Location: Step
Trigger Style: Automatic upon entry
NGS Extensions v5.25.0
Last Updated: November 2024
Release Date: June 2024
Document Version: 2
These release notes detail the key changes to software components for the Next Generation Sequencing (NGS) Extensions Package v5.25.0.
Compatibility
Refer to under Instruments & Integrations.
New Features
Added the download_attachments script. This script copies one or more result files attached in a step to a user-specified directory within Clarity LIMS. For example, this script can copy a generated sample sheet to a mounted directory so that the user can access it directly from the instrument control software.
Defects Fixed
None
Known Issues
An error occurs when reformatting the date using the Lab Logic Toolkit with the Date utility class. The date reformatting can be done with java.time instead.
Revision History
Compute Replicate Average
The Clarity LIMS NGS Extensions Package v5.14 includes the computeReplicateAverage script, which automates calculation of replicate (referred to as derivatives in the LIMS) average values. The script can also optionally calculate standard deviation and %CV values.
This section provides details on the script, its parameters, and LIMS configuration requirements.
Script Overview
The computeReplicateAverage script uses data stored in a source UDF / custom field (specified by the src parameter) to calculate the average across replicates, and writes the resulting value to a destination UDF / custom field (specified by the dest parameter).
Version
Changes
2
Updated Compatibility section to reference Compatibility matrix table.
Typically, the values will be derived from the submitted sample(s). In some cases, there will also be a need to copy data from the process level (specified by the user executing the process) down to each sample output UDF.
In some cases, there may be a need to account for pooling - i.e., where there are multiple submitted samples for a single output sample. The basic strategy here is to create small groupings of these values, such that each grouping does not contain multiple entries of the same UDF value.
Parameter
Description
-u {username}
(Required) LIMS login username
-p {password}
(Required) LIMS login password
-i {processURI:v2}
(Required) LIMS process URI
(Optional) When provided and set to true the script reports errors in accordance with 'Record Details button' mode, instead of the default 'screen transition' mode. Default is false.
Parameter
Description
-u {username}
-username {username}
(Required) LIMS login username
-p {password}
-password {password}
(Required) LIMS login password
-i {stepURI:v2}
-stepURI {stepURI:v2}
(Required) LIMS step URI
-log {logFileLIMSID}
-logFileName {logFileLIMSID}
(Required) LIMS ID of the log file placeholder
-layout <'ROW'/'COLUMN'>
(Optional) One of 'ROW' or 'COLUMN', if provided. When present, script enforces that the samples are laid out in gap-free, row-major or column-major order.
-queuedOnly <true/false>
(Optional) When provided and set to true, the script ensures that samples queued to the started step were started together. Samples dropped earlier in the workflow will are ignored. Default is false.
The script assumes the step has input analytes / derived samples with replicated per-input results / measurements.
The script groups the per-input results / measurements by their parent analyte / derived sample.
For each group, the script calculates the average of the result UDFs / measurement custom fields specified by the src parameter, ignoring any results that:
Are missing src values, or
Have an exclude field set to true
The resulting averages are written back into the parent analyte / derived sample field specified by the dest parameter for each group.
The exclude parameter is optional and no exclusions are performed if it is missing.
The script can also be used to calculate standard deviation and %CV values and add these results back to the corresponding UDF / field in the parent analyte / derived sample. The names of the Standard Deviation and %CV UDFs must be given to the script for it to update the values.
Script Parameters
Parameter
Description
-u {username}
-username {username}
(Required) LIMS login username
-p {password}
-password {password}
(Required) LIMS login password
-i {stepURI:v2}
-stepURI {stepURI:v2}
(Required) LIMS step URI
-log {logFileLIMSID}
-logFileName {logFileLIMSID}
(Required) LIMS ID of the log file placeholder
-src <srcUDF>
-srcUDF <srcUDF>
(Required) Source UDF / custom field name
-dest <destUDF>
-destUDF <destUDF>
(Required) Destination UDF / custom field name
Command Line Example
When working with the computeReplicateAverage script, the automation command line must be constructed as follows:
Example 1
In this example, the script will:
Average the values captured in the replicate Concentration fields. Replicates whose Ignore field value is set to True will be excluded from the calculation.
Copy the result to the Avg Concentration field configured on the parent derived sample.
Example 2
In this example, the script will:
Average the values captured in the replicate Concentration fields. Replicates whose Ignore field value is set to True will be excluded from the calculation.
Copy the replicate average result to the Avg Concentration field configured on the parent derived sample.
Calculate standard deviation and %CV values.
Copy the standard deviation and %CV results to the Std Dev and %CV fields configured on the parent derived sample.
Example 3
In this example, the script will:
Average the values captured in the replicate Raw CP fields. No replicates will be excluded from the calculation.
Copy the result to the Raw CP field configured on the parent derived sample. No values will be ignored.
Configuration
The inputs to the step must have values for the analyte UDF / derived sample custom field to be used as the source field. There must be an additional analyte UDF / derived sample custom field configured as the destination field - to capture the calculated replicate average. Both field types must be Numeric.
The following table provides example field configuration details.The field names used correspond to those used in the command line Example 1 shown above.
Configured on ResultFile in LIMS v4.2.x and Measurement in LIMS v5.x & later
Field Name
Field Type
Field Constraints / Options
Preset Values / Additional Options
Concentration
In example 1, this is the field specified by the -src parameter
Numeric
Required: Yes
Read Only: No
Decimal Places Displayed: 2
Ignore
In example 1, this is the field specified by the -exclude parameter
Boolean (v4.2.x)
Toggle Switch (v5.x)
Required: No
Read Only: No
Default: None Set
Configured on Analyte in LIMS v4.2.x and Derived Sample in LIMS v5.x & later
Field Name
Field Type
Field Constraints / Options
Preset Values / Additional Options
Avg Concentration
In example 1, this is the field specified by the -dest parameter
Numeric
Required: Yes Read Only: No
Decimal Places Displayed: 2
Linear Regression Calculation
Clarity LIMS NGS Extensions Package v5.17 and later includes computeLinearRegression script. This script calculates values for slope, intercept, and r-squared, and uses these values to populate corresponding fields. The field names are configurable via script parameters, and will differ depending on the LIMS integration.
In addition, the script requires values for y-axis and x-axis. These values are both related to control samples:
y-axis: This is configured as an analyte UDF / derived sample custom field on the control sample. The field name is configurable and is passed in as a script parameter.
Accession Kit Lots
The Clarity LIMS NGS Extensions Package includes the AccessionReagentKitLots script, which automates the accessioning of reagent lots based on container names. This section provides details on the script and its parameters, and LIMS configuration requirements.
Script Overview
Designed for use in automated workflows, the AccessionReagentKitLots creates a new reagent lot, matching the Reagent Kit Name specified in the command line to a reagent kit configured in the LIMS.
The script populates the lot details according to the following logic (see section for details):
Auto-Placement of Reagent Indexes
The Clarity LIMS NGS Extensions Package includes the place_indexes script, which assigns indexes (reagent labels) to samples in the destination container, based on the pattern defined in a specified index pattern file — and optionally validates the indexes against the pattern file.
This section provides details on the script and its parameters, and LIMS configuration requirement
Script Overview
The place_indexes script is intended to be run on entry to, and optionally on exit from, the Add Labels / Reagents screen of a step.
(Optional) Standard deviation UDF / custom field name
-cv <cvUDF>
-cvUDF <cvUDF>
(Optional) %CV UDF / custom field name
x-axis: This is the control type's concentration (entered in the Conc. field). This is not configurable.
Script Parameters
The following table defines the parameters used by the computeLinearRegression script.
Parameter
Description
-u {username}
-username {username}
(Required) LIMS login username
-p {password}
-password {password}
(Required) LIMS login password
-i {stepURI:v2}
-stepURI {stepURI:v2}
(Required) LIMS step URI
-log {logFileLIMSID}
-logFileName {logFileLIMSID}
(Required) LIMS ID of the log file placeholder
-y <FieldName>
-yAxisUDF <UDFName>
(Required) Analyte / Derived sample field name for Y axis.
-slope <FieldName>
-slopeUDF <FieldName>
(Required) Slope process / step field name
Command Line Example
Example
Configuration
This section describes the configuration required for the linear regression calculation.
Step UDFs /Custom Fields
Three step UDFs / custom fields must be configured on the master step / process type, to capture the linear regression slope, intercept, and r-squared values. These fields should display on the Record Details screen at run time.
The following table provides example field configuration details. The field names used correspond to those used in the command line example shown above.
Field Name
Field Type
Field Constraints / Options
Intercept
The field specified for the -ic parameter
Numeric
Required: No
Read Only: No
Custom Entries: Yes
R-Squared
The field specified for the -rsq parameter
Numeric
Required: No
Read Only: No
Custom Entries: Yes
Slope
The field specified for the -slope parameter
Numeric
Required: No
Read Only: No
Custom Entries: No
Global Custom Fields / UDFs
The control samples in the step must have values for a specific derived sample custom field / analyte UDF.
The following table provides example configuration details for this field. The field name used corresponds to the name used in the command line example above.
The field is configured on Analyte in LIMS v4.2.x and Derived Sample in LIMS v5.x and later.
Field Name
Field Type
Field Constraints / Options
Raw CP
The field specified for the -y parameter
Numeric
Required: No
Read Only: No
Custom Entries: Yes
Typically it is the step outputs that need to have this field available to fill in. However, the field could also be made available on the step inputs to support the case where multi-step controls are used as inputs to the step.
Rules and Constraints
Control samples used in the step must have valid concentration values:
Concentration must be a numeric value.
Optionally, the numeric concentration value can have text following it to specify the units, for example - 10.02 nM. Note that units are for display purposes only and are not factored into the calculation.
Concentration must be a value other than 0. Controls with 0 concentration value are ignored.
Slope, intercept, r-squared and -y (Raw CP in the example) field values must all be numeric.
There must be 4 or more control samples in the step that can be used in the calculation - i.e., after passing validation.
Number of control samples can be configured through -minData parameter.
Control samples must have:
A name that matches the pattern provided by the -select parameter (if provided).
A y-axis field filled in with a numeric value.
If -logX parameter is specified as 'true', the calculated log10(concentration) value is used as the x-axis value (see ).
Lot Name = Lot name (specified by lotName parameter)
Lot Number = Container name (specified by from parameter)
Expires = now + expiry days (specified by expiryDays parameter)
Status of Reagent Lot toggle switch is set to Active
Before accessioning the reagent lot, the script verifies that:
The expiryDays parameter value is greater than 0, and is a whole number
The reagent lot does not already exist in the LIMS - lots are not reusable.
The script checks whether there is an existing reagent lot in the LIMS that matches the combination of lot name + lot number provided. If so, validation fails. (Kit name is not checked during this validation process.)
If a unique combination of lot name + lot number is provided, the LIMS creates the new lot—even if there are already lots in the LIMS matching either the name or the number.
Note that it is therefore possible to create both of these lots:
Lot 'ABC' with number '123'
Lot 'ABD' with number '123'
Script Parameters
Parameter
Description
-u {username}
-username {username}
(Required) LIMS login username
-p {password}
-password {password}
(Required) LIMS login password
-i {stepURI:v2}
-stepURI {stepURI:v2}
(Required) LIMS step URI
-log {logFileLIMSID}
-logFileName {logFileLIMSID}
(Required) LIMS ID of the log file placeholder
-from <outputContainer / inputContainer>
(Required) Must be either 'outputContainer' or 'inputContainer'.
This dictates where the 'Container Name' value is copied from. This is used to create the lot number.
Only supports output containers on steps that output samples. See .
-reagentKit <Reagent Kit Name>
(Required) Reagent Kit name on which the generated lot is based.
Command Line Example
Example
Configuration
The following sections describe the configuration intended to support the AccessionReagentKitLots script.
Master Step Custom Fields
Configure master step custom fields (step UDFs in v4.x) for reagent kit name and lot name, and display them in the Step Details area of the Record Details screen. When running the step, the user fills in these values and they are supplied to the reagentKit and lotName parameters in the script. In this scenario, configure the automation command line as follows:
Automation trigger
The script is intended to be automatically triggered at the end of a step. However, you may include the -t option to run the script in test mode and trigger the script via button on the Record Details screen.
Rules and Constraints
Reagent Kit Name specified in the command line must match a reagent kit configured in the LIMS.
expiryDays parameter value must meet the following criteria:
Must be a whole number greater than 0.
Must be a numeric value (i.e., '1' not 'one').
When specifying the from parameter, note that the script only supports the value 'outputContainer' if the step outputs are samples. Step output measurement records with placement are not supported.
Accessioning reagent lots with this script sets each reagent lot status to Active until the expiry date is reached. You cannot use the script to add reagent lots with status set to Pending.
The step should only be run with a single container matching the from definition.
If from is defined as the output container, the step can have multiple input containers but all samples must be placed in the same output/destination container. This is because the script only looks up a single container name. If there are multiple output containers in the step, the script will not fail; however, it will choose a container arbitrarily, which could result in unexpected behavior/results.
On entry to Add Labels / Reagents screen, the script assignes an index (label) to each sample in the destination container, based on the pattern defined in the specified index pattern file.
On exit from Add Labels / Reagents screen, the script validates the indexes against the pattern file. You can also use the script to check:
If the user has modified the indexes.
If the current step permits user modifications.
Script Parameters
Parameter
Description
-u {username}
-username {username}
(Required) LIMS login username
-p {password}
-password {password}
(Required) LIMS login password
-i {stepURI:v2}
-stepURI {stepURI:v2}
(Required) LIMS step URI
-f <pattern file directory and file name>
-patternFilePath <pattern file directory and file name>
(Required) Path (directory + file name) of index placement pattern files
Providing the directory without the file name results in an error. You must provide both.
-ic <'name of reagent category / label group'>
-ignoredCategory <'name of reagent category / label group'>
(Optional, may be provided multiple times) Reagent category for which autoplacement should not occur
-locked <true/false>
(Optional) Provide as true if the index placement is locked and not modifiable by the user. If not provided, defaults to false.
Command Line Example
Example
Note that this command line also uses the Sample Placement Helper script (PlacementHelper.jar), included in the Lab Instrument Toolkit.
Pattern File
The index pattern file is a tab-separated file consisting of two columns, DEST_WELL and INDEX_NAME, and is in the following format:
DEST_WELL
INDEX_NAME
A:1
AD001 (ATCACG)
B:1
AD002 (CGATGT)
C:1
AD003 (TTAGGC)
D:1
AD004 (TGACCA)
E:1
AD005 (ACAGTG)
F:1
AD006 (GCCAAT)
The destination well format provided in the file must match the well placement configuration of the container type intended for use in the LIMS. The reagent index name must match the name of a reagent in the LIMS.
Pattern name files may be customized. However, for out-of-the-box LIMS integrations, the supplied pattern file names follow the convention: placement_pattern_index_xx_yy.tsv, where:
xx is a short description about the step that accesses this file
yy is a 2-digit value in the range from 01 to 99
Validation
There are three levels of validation provided by the script:
Index placement can be modified by the user on the fly.
Index placement is locked down by an administrator and cannot be modified by the user.
Index placement must be locked down by an administrator prior to use.
Two options determine which level of validation to apply:
The presence of a corresponding checksum file for the given pattern file.
The presence of the locked script parameter.
When there is no checksum file, and locked is not provided to the script (or is provided as false), index placement is user-modifiable.
Checksum file
If the reagent index placement pattern is not user-modifiable, an administrator can create a checksum file to ensure that the user has not changed the index placement on the fly.
This checksum file should have the same name as the placement pattern file, but with the file extension .md5. For example:
placement_pattern_index_pcramp_01.tsv
placement_pattern_index_pcramp_01.md5
The checksum file must be placed in the same location as the corresponding index pattern file. When a checksum file is found and the user has modified the indexes on the samples in the step, the script reverses the changes made by the user.
The checksum file contains the .md5 checksum for the corresponding pattern file itself. This checksum value is compared against the pattern file to validate whether the pattern file has been modified. If it has been modified, the script displays an error message and index placement does not occur. If an administrator wishes to change the pattern file contents, they must also regenerate the checksum when the updated pattern is available for use.
Locked patterns
The locked parameter provides an additional layer of validation. If this is provided to the script, the current pattern requires the presence of a checksum file. This ensures that an administrator has approved the pattern for use before it is used in a step.
Ignored categories
In some steps where reagent autoplacement is configured, there may be some reagent categories where this is not desired.
For example, the workflow may permit either a full 96 well plate of samples in the indexing step, or merely 8 samples in tubes. For the 8 samples, a different reagent category is used than for the batch of 96. In this case, the ignoredCategory parameter may be used to indicate that if the 8-sample reagent category is selected for the step, index placement will be performed manually.
Configuration
The place_indexes script is intended to be run on entry to / exit from the Add Labels / Reagents screen of a step.
To achieve this, configure the automation trigger as follows:
Trigger Location: Add Labels screen
Trigger Style: Automatic upon entry / exit
Rules and Constraints
The step must be configured for adding reagent indexes.
The script must run on entry to or exit from the Add Labels / Reagents screen.
The pattern file must be a tab-separated (.tsv) file.
The pattern file headers must be DEST_WELL and INDEX_NAME.
The reagents in the pattern file must match the name of reagents configured in the LIMS.
Only Index type reagents are supported.
The destination container type selected must match the well placement information in the pattern file.
There must not be more samples in the step than are supported by the selected pattern file.
Only a single destination container is supported.
If the locked parameter is provided, a checksum file must be present.
If a checksum file is present, the index placements may not be modified by the user.
The checksum file must be in the same location and have the same name as the pattern file, with extension .md5.
The checksum file contents must be the checksum value for the corresponding pattern file.
If a checksum file is present, the pattern file and checksum file must have the same checksum value.
Routing Script
The routing script allows for the movement of samples from one workflow to another. The script can move sample individually or in bulk.
Individually — the script uses derived sample custom fields (analyte UDFs in v4.x)
In bulk — the script uses master step custom fields (step UDFs in v4.x).
To move samples, first define the workflow and the step to which the samples will be sent. The script can be modified in the automation command line.
This section discusses the Routing script - Normalize Libraries automation used in the Illumina Preset Protocols (IPP). The automation invokes the changeWorkflow script, which routes step outputs to the next protocol in the workflow according to the Sequencing Instrument field value of each sample.
Automation Configuration
Command Line
The default automation command line for the routing script is as follows.
The default command line includes one section, and will always send the samples to the same workflow. To offer multiple workflow and/or step choices, you must add multiple sections, as shown in the following examples.
To send samples into a QC Protocol, use the protocol name instead of the name of the step name.
Script Parameters
Example 1
This example route the output without checking the UDF name and value
Example 2
Routing script configured on DNA/RNA Extraction step in TruSight Tumor 170 v1.0 workflow
Configuration Requirements
Next Step Configuration
For the routing script to be triggered, the Next Step value for all samples in the step must be set to Remove from workflow. You can set this value manually or automatically, using a script.
Set the next step manually
At run time, on the Assign Next Steps screen, the lab scientist sets the Next Step value to Remove from workflow.
ℹ The Remove from workflow option is only available on the Assign Next Steps screen for users who have the RemoveSampleFromWorkflow permission. If you use the manual method, you must make sure that users who need to set this option at run time have the correct permission. For details on configuring role-based permissions, see the Core LIMS documentation.
Set the next step automatically
Add the following script to an automation command line enabled on the step. Configure the protocol and set the Assign Next Step function to Automatic.
On the protocol configuration screen, in the Next Steps section, the method of assigning the next step must be set to Automatic.
Automation Trigger Configuration
By default, the routing script automation should be configured to be automatically triggered at the end of the step.
After the script has completed, a dialog box displays. This dialog box shows the number of samples routed to each step — or an error message if something went wrong.
Global Custom Fields / UDFs
The following table provides configuration details for the global custom field configured to support the routing script automation. This example is based on the Routing Script - Normalize Libraries automation.
The field is configured on Analyte in LIMS v4.2.x and Derived Sample in LIMS v5.x onwards.
Modifying the Default Configuration
You can modify the default configuration by removing / adding instruments.
To remove an instrument
Remove the unwanted FIELD_VALUE from the list of presets.
In the automation command line, remove the section that corresponds to the unwanted FIELD_VALUE.
To add an instrument
Add a field option / preset for the new FIELD_VALUE.
Add a section in the routing script command line to set the parameters for the additional FIELD_VALUE.
For example, to add "New instrument" to the
Rules and Constraints
The --FIELD_NAME and --FIELD_VALUE are only available for derived sample and master step custom fields.
If no custom field should be checked, provide "N/A" to FIELD_NAME and FIELD_VALUE.
If the --FIELD_VALUE parameter value passed to the script does not match the value in the --FIELD_NAME custom field, the routing script does not route the sample.
Set UDF
Available from: Clarity LIMS v2.0.5
Often, a user would like to set or change the value of a UDF. If the UDF is accessible from the initial process URI, the setUDF script can be used.
Script Overview
The setUDF script allows several operations to take place, including - but not limited to the following:
(Optional) Provide as true if you are running this as the final check to make sure autoplacement was not modified.
G:1
AD007 (CAGATC)
H:1
AD008 (ACTTGA)
A:2
AD009 (GATCAG)
A concentration value filled in for their control type, with a non-zero numeric value.
If any of these conditions is not met, the control samples fail validation and are excluded from the calculation. These do not count towards the minimum number of control samples.
-ic <FieldName>
-interceptUDF <FieldName>
(Required) Intercept process / step field name
-rsq <FieldName>
-rSquaredUDF <FieldName>
(Required) R-squared process / step field name
-x <FieldName>
-xAxisField <FieldName>
(Deprecated parameter, not supported) Control type concentration field name for x axis. This value specifies the API name that will be used to read the concentration from the control type. Not configurable.
Note: This field appears as concentration in the API, but displays as Conc. in the user interface. You cannot customize this naming in the API.
In addition, the script does not attempt to read the concentration from the control sample instead of the control type. For example, if you add a UDF / custom field to the control sample, you cannot use that field as the X axis value.
-logX <true/false>
-logXMode <true/false>
(Optional) If set to 'true', reads the concentration value from the control type, calculates the log10 of that value, and uses the result for the x-axis.
Default = false
-minData <#>
-minDataPts <#>
(Optional) Minimum number of data points needed to run linear regression.
Name of LIMS workflow to which the samples will be sent
--STEP
LIMS step within the workflow
--INPUTS_OR_OUTPUTS
Specifies whether the LIMS UDF / custom field is from the input or the output
Routing Script - Normalize Libraries
automation, add the following to the end of the script:
The routing script works with the Remove from workflow function in the Next Steps of any step. Make sure that the correct settings or permissions are in place to allow for this function. For details, see the preceding Configuration Requirements section.
-l <log file path and name>
-logFileName <log file path and name>
Path destination for the log file (Required)
--FIELD_NAME
LIMS custom field name (derived sample (analyte) or step)
--FIELD_VALUE
LIMS UDF preset /custom field option value
If the field type is a check box/toggle, the --FIELD_VALUE should be set as 'true' or 'false'
Field Name
Field Type
Field Constraints / Options
Preset Values / Dropdown Items
Sequencing Instrument
Single-line Text (v4.2.x)
Text Dropdown (v5.x and later)
Required: Yes
Read Only: No
Custom Entries: No
MiSeq
NextSeq
NovaSeq
--WORKFLOW
bash -c "/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ngs-common/v5/EPP/ngs-extensions.jar -u {username} -p {password} -i {stepURI:v2} -l {compoundOutputFileLuid0} script:changeWorkflow \
\
--FIELD_NAME 'Name of the field' \
--FIELD_VALUE 'Preset value of the field' \
--WORKFLOW 'Name of the workflow' \
--STEP 'Name of the Step in the workflow \
--INPUTS_OR_OUTPUTS 'One or the other'"
\
--FIELD_NAME 'Sequencing Instrument' \
--FIELD_VALUE 'New instrument' \
--WORKFLOW 'Workflow name for New instrument' \
--STEP 'Step of the Workflow for New instrument' \
--INPUTS_OR_OUTPUTS 'OUTPUTS'"
Set a UDF on an output container to today's date.
Set a UDF on any sample associated with any input to a person's name.
Set a UDF on any output to a lab name (referred to as 'Account' in Clarity LIMS).
Set the input container name as a process level UDF.
Read a project UDF and set it on a sample.
Script Parameters
Parameter
Description
-u {username}
(Required) LIMS login username
-p {password}
(Required) LIMS login password
-i {URI}
(Required) LIMS process URI
-f {name}
(Required) UDF names
-t {XPath}
(Required) Path to the target object
-s {XPath}
(Optional) Path to the source element/attribute
Examples
There are multiple ways to implement this script, as illustrated by the following examples.
Example 1
Set the UDF named MyUDF on any output containers to the date the process ran:
Example 2
Set the UDF named MyUDF on any sample associated with any input to the name of the technician:
Example 3
Set the UDF named MyUDF on any output to the name of the technician's lab:
Example 4
Set the input container name as a process level UDF:
Example 5
Read a project UDF and set it on a sample:
Example 6
Read a parent process UDF and set it on a sample level UDF called Geneticist:
Example 7
Read the Project name and set it on a sample level UDF called ProjectName:
ℹ In the examples shown above, the paths may differ for your system. For example, the version number may differ. For Clarity LIMS 4 or before, the process URI token should be:
Rules & constraints
Both the target entity and (optionally) the source value are expressed as chains of XPath expressions (using -> as separators).
Even if you are using XPath to specify the source value, setUDF applies a single value per invocation to all target objects. It cannot apply different source values to different target objects.
You can use -z as an option when running the script to simulate the effects it would have. Note that even though an output identifying the target object(s) and the value that would be set is produced no changes are actually made.