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.

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.
-fc <true/false> -finalCheck <true/false>	(Optional) Provide as true if you are running this as the final check to make sure autoplacement was not modified.

Command Line Example

Example

bash -c "/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ngs-common/v5/EPP/PlacementHelper.jar \
-i {stepURI:v2:http} \
-u {username} \
-p {password} \
script:place_indexes \
-f /opt/gls/clarity/extensions/conf/infinium/indexplacementpatterns \
-ic 'NoIndex' \
-locked true \
-fc true"

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)
G:1	AD007 (CAGATC)
H:1	AD008 (ACTTGA)
A:2	AD009 (GATCAG)

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.