Sample Placement Helper

Compatibility: Clarity LIMS v2.5 or later, and v3.0 or later

The sample placement helper tool allows for automated sample placement and validation in Clarity LIMS. It consists of the following scripts, each of which handles different use cases.

Container Name Validation

Clarity LIMS supports renaming of destination containers in a step in two ways:

• Renaming the containers on the Placement screen.

• Renaming the containers on the Record Details screen.

Often, the container name will be the barcode of the physical container (plate, chip, and so on) in the lab, which is entered into the system using a barcode scanner. However, it's possible for the barcodes to be small or close together and for the scanner to have a wide scanning range.

The purpose of this script is for validation that the same barcode has not been scanned twice during container renaming.

How it Works

The script validates the names of the destination containers in the step, and reports if any duplicates are found.

The script may be run on any step that includes sample placement, and may be run:

• Manually from the Record Details screen OR

• Automatically on transition at any point after placement has been done (for example, on exit from the Placement screen).

The script may be configured to do the following:

• Report either a warning or failure if duplicate container names are detected.

• Reset the destination container names in the step to the default value of the container LIMSID.

Modes

Trigger Node

• Trigger mode must be provided when configuring the script to be triggered manually.

• This mode determines how the script reports the outcome of its validation to the user, which is a different underlying mechanism when run on-screen transition.

Error Mode

• The errMode parameter accepts values of "warn" and "fail."

• When in "warn" mode, you are still able to proceed in the step if duplicate destination container names are detected.

• If set to "fail," you will not be able to continue as long as duplicates are present.

Reset Mode

Typically, a duplicate name is caused by an accidental repeated scan of a barcode.

• Reset mode may be used to automatically reset the destination container names in the step if duplicates are detected.

• This option resets all destination container names in the step to each LIMSID, which is the default value used for container names in the LIMS.

Script Parameters and Usage

Parameter	Description
-i {URI}	Step URI (Required)
-u {username}	LIMS username (Required)
-p {password}	LIMS password (Required)
-t, -triggerMode	Provide as "true" if script will be triggered manually (Optional)
-errMode	Provide as "warn" or "fail" to determine behavior when duplicate container names are detected (Required)
-reset	Provide as "true" to reset all container names to their default LIMSID when duplicates are found (Optional)

Example 1: Validate container names on Record Details

In this example, the script is triggered manually on the Record Details screen. It will warn the user if duplicates are detected, and the destination container names will not be changed.

bash -c "/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ngs-common/v5/EPP/PlacementHelper.jar script:validate_container_names \ -i {stepURI:v2:http} \ -u {username} \ -p {password} \ -errMode 'warn' \ -t 'true'"

Example 2: Validate container Names on Transition

In this example, the script is configured to run automatically on-screen transition. It will fail if duplicates are detected, preventing the user from advancing in the step, and the destination container names will be reset to the container LIMSID.

bash -c "/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ngs-common/v5/EPP/PlacementHelper.jar
script:validate_container_names \
-i {stepURI:v2:http} \
-u {username} \
-p {password} \
-errMode 'fail' \
-reset 'true'"

Placement by Pattern File

Some instruments or workflows require specific placement patterns based on the container type. Clarity LIMS may need to place samples in an unusual pattern, such as every second well in a plate. To handle this, the ability to specify new patterns based on specific types of containers is required.

The purpose of the Placement by Pattern File script is to automate sample placement according to a specific pattern based on container type. The script reads the pattern in from a file, allowing for easy customization.

There are two script modes:

• Source sample index placement: This is the default mode. This mode assigns an index to each input sample and their replicates, and then transfers them to a particular well in the output container. This mode allows for cherry picking of samples.

• Source well placement: This mode uses the well position of an input sample to transfer it to a certain well position in the output container. In this mode, samples from one well will always be transferred to the same well in the output container.

How it Works

Pattern files are stored in a directory that is passed as a parameter to the script.

Files are automatically selected based on the mode of the script and the container names:

• Source sample index placement is toggled with the useIndexMode parameter. When using this mode, the file name must contain "IndexedTransfer" and the selected container type.

• When using source well placement, the file name must contain the input container and selected container types of the protocol step.

For example, suppose that there are samples in a 96 well plate that are to be transferred into several 12x1 BeadChips.

• If source well placement is used, the pattern file would be named 96 well plate_12x1 HD BeadChip.tsv.

• If source sample index placement is used, the pattern file would be named IndexedTransfer_12x1 HD BeadChip.tsv (for information on the format of the pattern files, see the Pattern File Format section).

Both script modes support multiple input containers of the same type and multiple output containers of the same type. Only source sample index placement supports multiple types of input containers.

All input samples are sorted by container LIMS ID to ensure accurate placement. If useIndexMode is set to "true", samples will be further sorted to assign index. After being sorted by container LIMS ID, they are sorted based input sample well position. The sortOrder parameter specifies whether indexed samples are sorted by row or by column with respect to well position. The sortOrder parameter is only used with source index placement. Input samples are indexed from 1, and sample replicates of a particular sample are all assigned the same index.

Output containers are created and given temporary names of "Plate 1," "Plate 2," "Plate 3"... These can then be updated as desired, for example, by scanning in the barcode of the container. This temporary naming is done for ease-of-use, to make sure that the visual order in the interface is correct, making it easier to confirm that the placement pattern was followed.

⚠️ The script is intended to be used with fresh destination plates, rather than plates that exist in the system. If a preexisting container is selected, it too will have the temporary naming applied and will become "Plate 1."

It is possible to configure the script to fail or produce a warning message if the number of samples does not match the contents of the pattern file. There are three parameters to enforce the number of samples and replicates in the step: replicatesMode, minSamplesMode, and maxSamplesMode.

For example, if replicatesMode is set to "warn" and maxSamplesMode is set to "fail", then the script will produce a warning after placement occurs if the number of replicates is inaccurate and it will fail if there are more samples in the step than specified in the pattern file.

Process and Workflow Configuration

The script may be configured on any process that includes sample placement:

• Configure this script to run automatically on entry to the Sample Placement screen.

• Before using the script, confirm that the desired pattern files are correctly configured and are located in the correct location with the appropriate parameter provided. (See Script Parameters and Usage.)

Script Parameters and Usage

Parameter	Description
-i {step URI}	Protocol step URI (Required)
-u {username}	LIMS username (Required)
-p {password}	LIMS password (Required)
-d {pattern file directory}	Directory for placement pattern files (Required)
-useIndexMode {use index mode}	Determines whether source sample index placement is used instead of source well placement (Optional)
-replicatesMode {replicates mode}	Provide as "warn"/"fail" to determine script behavior if the number of replicates does not match the pattern file (Optional)
-minSamplesMode {min samples mode}	Provide as "warn"/"fail" to determine script behavior if the number of samples in the step is lower than specified by the pattern file (Optional)
-maxSamplesMode {max samples mode}	Provide as "warn"/"fail" to determine script behavior if the number of samples in the step is higher than specified by the pattern file (Optional)
-sortOrder {sort order}	Provide as "horizontal"/"vertical" to sort samples by row/column for source sample index placement - default is "horizontal" (Optional)

Example 1

This example uses source well placement and a pattern file placed in: /opt/gls/clarity/extensions/conf/infinium/placementpatterns

bash -l -c "/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ngs-common/v5/EPP/PlacementHelper.jar
script:place_samples \
-i {stepURI:v2:http} \
-u {username} \
-p {password} \
-d /opt/gls/clarity/extensions/conf/infinium/placementpatterns"

Example 2

This example uses source sample index placement. Replicates mode fails the script if there is an inaccurate number of replicates, minSamplesMode warns the user that there are fewer samples than specified in the pattern file, and maxSamplesMode fails the script if there are more samples than specified in the pattern file. The pattern file is located in: /opt/gls/clarity/extensions/quantstudio/conf/placementpatterns

bash -l -c "/opt/gls/clarity/bin/java -jar /opt/gls/clarity/extensions/ngs-common/v5/EPP/PlacementHelper.jar script:place_samples \
-i {stepURI:v2:http} \
-u {username} \
-p {password} \
-d /opt/gls/clarity/extensions/quantstudio/conf/placementpatterns \
-useIndexMode true \
-replicatesMode fail \
-minSamplesMode warn \
-maxSamplesMode fail"

Pattern File Selection

The location of the pattern file is customized using the appropriate parameter, as described in Script Parameters and Usage.

When source well placement is used, the exact file to use is selected based on the names of the input container type and destination container type:

• The name must contain an exact match for each of the container types (eg "384 well plate_96 well plate.tsv")

• Container type names must be separated from other text by underscores; any other text in the name is ignored. For example, "{type}_{type}.tsv" and "{type}_{type}_transfer file.tsv" are both valid pattern file names.

• For a transfer from one container to another of the same type, "{type}.tsv" is a valid pattern file name. However, the script currently uses the first file it finds with a name containing the source and destination container types. If both "{type1}.tsv" and "{type1}_{type2}.tsv" are found in the same location, the script may not accurately detect which should be used for a protocol step that has input and output containers of type "type1." This can be avoided by using the long form for naming, ie {type1}_{type1}.tsv.

When source sample index placement is used, the pattern file name is slightly different:

• The name must contain "IndexedTransfer" along with an exact match for the destination container type (eg "IndexedTransfer_96 well plate.tsv")

• As with source well placement, container type names must be separated from other text by underscores; any other text in the name is ignored.

Pattern File Format

The pattern file format is a tab-separated file (.tsv) that has three columns with headers. These headers depend on the script mode. For source well placement, SRC_WELL, DEST_CONTAINER_INDEX, and DEST_WELL are the required headers. When useIndexMode is enabled, the pattern file must contain SRC_SAMPLE_INDEX, DEST_CONTAINER_INDEX, and DEST_WELL.

The table describes the four columns:

Column header	Description	Required for source well placement	Required for source sample index placement
SRC_WELL	Well position of the input sample, in the format A:1	Yes	No
SRC_SAMPLE_INDEX	Index of the input sample, indexed from 1	No	Yes
DEST_CONTAINER_INDEX	Output container index, indexed from 1	Yes	Yes
DEST_WELL	Destination well position of the sample, in the format A:1	Yes	Yes

Part of an example pattern file for source well placement is shown below:

An example of a pattern file for placement via source sample index is shown below. It expects samples to have eight replicates each.

Placement by Robot Transfer File

Some labs require support for a robot-driven sample placement scenario, in which sample placement is performed on the robot and is then recorded in the LIMS, without requiring manual entry of the sample placement.

The purpose of the Placement by Transfer File script is to automate sample placement according to a transfer file produced by a robot. The script covers a one-to-one, many-to-one (pooling), or one-to-many (replicates) mapping of samples for placement. Support for reagents is planned for a future release.

The script is available as of Clarity LIMS v3.0. Replicate support added in NGS Extensions Package v5.3.1 (Placement Helper v2.1.0). Pooling support added in NGS Extensions Package v5.4.0 (Placement Helper v2.2.0) and requires LIMS v3.1.

How it Works

The robot produces a transfer file (worksheet, work list file, and so on) that contains information about which samples were used and their source and destination locations. Upload this file to the protocol Step Setup screen in the LIMS.

The Placement by Transfer File script automatically performs the same placement as the robot, recording the work that has been done in the lab, not manually enter this information.

The script looks at the protocol step inputs and matches these to the source information in the transfer file, then uses the destination information to place the protocol step outputs. On pooling steps, the script will have the intermediary step of creating the pools. After the pools are created, you are given the opportunity to make sure that their contents before the script does placements for the pools.

(For information on the format of the pattern files, see the Transfer File Format section.)

The script will first search for containers that exist in the LIMS with names matching the destination container names provided in the transfer file, and if only a single container matches a given destination container name it will be used. Otherwise the containers will be created using the destination container type, or selected container type if type information is not provided in the transfer file. The only case where the script will proceed if it finds multiple containers in the LIMS matching a destination container name in the transfer file is if one of those containers is the selected container for the protocol step.

The sample name column is used for validation. If the sample found in the LIMS that matches the input placement information does not have the same name, an exception will be thrown by the script.

Process and Workflow Configuration

• The script may be configured on any protocol step that includes sample placement.

• Configure this script to run automatically on entry to the Sample Placement screen. (See Script Parameters and Usage.)

• If you are pooling samples, the script must also be configured to run on entry to the Pool Samples screen. The configuration strings would be the same for both automatic EPP triggers.

• The Step Setup screen should also be enabled in the protocol step configuration, to allow for attachment of the transfer file.

Script Parameters and Usage

Parameter	Description
-i {URI}	LIMS process URI (Required)
-u {username}	LIMS username (Required)
-p {password}	LIMS password (Required)
-f {placement file LIMSID}	LIMS ID of the file used to map samples to new placements (Required)
-headerIndex {header index}	Numeric index of file header row, starting from 1(default is 1) (Optional)
-srcContainer {source container}	Name of column containing source container ID (Required)
-srcWell {source well}	Name of column containing source container well (Required)
-sampleName {sample name}	Name of column containing sample ID (name) (Optional)
-destContainer {destination container}	Name of column containing destination container ID (Required)
-destWell {destination well}	Name of column containing destination container well (Required)
-destType {destination type}	Name of column containing destination container type (Optional)
-separator {separator}	File separator, provide tab as "tab" and comma as "comma" (default is comma) (Optional)

Example 1

This example uses the minimum configuration for the script:

bash -l -c "/opt/gls/clarity/bin/java -cp /opt/gls/clarity/extensions/ngs-common/v5/EPP/PlacementHelper.jar place_samples_by_robot_file
-i {stepURI:v2:http}
-u {username}
-p {password}
-f {compoundOutputFileLuid0}
-srcContainer 'S_PLATE_ID'
-srcWell 'S_PLATE_XY'
-destContainer 'D_PLATE_ID' -destWell 'D_PLATE_XY'"

Example 2

This example provides some of the optional parameters. The script will parse a tab-separated file that has its header on the third line, with additional validation on sample name and destination container type:

bash -l -c "/opt/gls/clarity/bin/java -cp /opt/gls/clarity/extensions/ngs-common/v5/EPP/PlacementHelper.jar place_samples_by_robot_file
-i {stepURI:v2:http}
-u {username}
-p {password}
-f {compoundOutputFileLuid0}
-headerIndex '3'
-srcContainer 'S_PLATE_ID'
-srcWell 'S_PLATE_XY'
-sampleName 'SAMPLE_ID'
-destContainer 'D_PLATE_ID'
-destWell 'D_PLATE_XY'
-destType 'D_PLATE_TYPE'
-separator 'tab'"

Transfer File Format

Currently the script supports comma- and tab-separated formats with a single-line header followed by data rows for the transfer information.

The minimum information required in the transfer file is a column for each of the following:

• source container

• source well location

• destination container

• destination well location

For additional validation, it is possible to specify columns to use for the following:

• sample name

• destination container type

The contents of the transfer file must correspond to the number of sample outputs per input configured for the step. In the transfer file, replicates are represented as multiple lines with the same source container and well, but different destination containers or wells. A line must appear for each expected output, including replicates, or else an exception will be thrown by the script and placement will fail.

To pool multiple inputs together, make sure that the corresponding inputs have the same destination container and well. If so, and the step is configured for pooling, when the script is triggered on entry to the pooling screen your pools will be created. If the step is not configured for pooling, then such a transfer file will cause an error to be thrown by the script.

An example from a Hamilton robot (.tsv, tab-separated file) is shown below:

Constraints

• Placements separated by a colon (e.g., 1:1) or that are alphanumeric (e.g., A1) are valid. Placements that are numeric only (e.g., 11) are not supported.

• If the destination container type information is not supplied, the selected container type for the protocol step will be used to place the samples.

Additional Information

Some other scripts you may find useful:

• Parse CSV