Available from: BaseSpace Clarity LIMS v5.1.x

When the Template File Generator generates the file, it creates a log file and attaches it to the step in the LIMS.

If the file generation process encounters errors, these error conditions appear in the log file.

If the file generation process completes successfully, the log file contents resemble the following example:

When troubleshooting Template File Generator issues, you will find detailed information in the Automation Worker log files.

Available from: BaseSpace Clarity LIMS v4.2.x

The Template File Generator is a file-generation solution that allows Clarity LIMS admins, such as lab managers, to produce custom template files without requiring scripting or development knowledge or resources.

At run time, the Template File Generator uses a script (driver_file_generator) and the supplied template file to generate a file. This may be a simple file that includes a subset of LIMS data, or a more complex sample sheet file for upload to the sequencing instrument to start a run.

The format of a template file is typically a comma-delimited CSV file. However, the following file formats are also supported: .bak, .groovy, .md5, .tsv, .txt, .xml.

How the Template File Generator Works

1. In Clarity LIMS:

   • An automation is configured and enabled on a step.

   • The driver_file_generator script is triggered from the automation command line.

For example:

For details on template sections and the tokens you can use in your template files, see article.

Lab Instrument Toolkit provides a number of scripts that can be used for custom configuration.

• The driver_file_generator script () is a file-generation solution that produces custom template files without requiring scripting or development knowledge or resources.

• The addBlankLines script allows for the creation of files that require a line entry for every well in a container, including those wells that are empty.

Available from: BaseSpace Clarity LIMS v3.0.0

Some instruments, such as Bioanalyzer and the ABI 7900HT, require input files that include a line for every well in a container.

Currently, files created with the sample input sheet generator can only contain data lines for each well that is in use and cannot add lines for empty wells. This extension script allows you to process a file in a certain format to add customizable lines for the empty container wells.

The Script

The addBlankLines script allows for the creation of files that require a line entry for every well in a container, including those wells that are empty.

To accomplish this, the script takes in an existing file, created with sample input sheet generator, and processes it to add the new lines.

1. The script reads the file and separates it into header, data, and footer sections.

2. Using the API, the script obtains the container size, its unavailable wells, and the placement of each sample.

3. Using this information, the script runs through each possible placement and builds a full set of data. This includes a line for each empty well, in addition to all original lines of data. If desired, a line for each unavailable well may also be included using script parameters described.

Placement information is written using a numeric index that is converted from the LIMS well placement. The line information that is inserted for an empty well is provided to the script. This is controlled by the blankLineString parameter, described.

The logic that determines whether the script uses input samples and containers or output samples and containers is as follows:

• By default the script will use outputs.

• If there are no outputs or if the optional parameter -forceInputs true is configured, the script will use inputs.

Script Parameters and Usage

Parameter Details

Rules and Constraints

The script operates with the following constraints:

• The input file and log file to update must exist locally.

• Only supports TAB and COMMA as separators in the file.

• Only supports processing one container at a time.

Configuration

• The script should be configured to run after the creation of a file occurs - either within the same automation call or as a separate automation triggered after the call that generated the file.

• It can also be configured standalone for files that are locally accessible.

Example Automation Strings

Available from: BaseSpace Clarity LIMS v2.1.0

Often, data can be parsed from an instrument result file in XML format into Clarity LIMS, for the purposes of QC.

For example, perform a TapeStation instrument run. This produces an XML result file, which the user imports into the LIMS. The file includes information of interest for each sample, which should be parsed and stored for a range of capabilities, such as QC threshold checking, searching, and visibility in the LIMS interface.

The XmlSampleNameParser tool allows for sample data to be parsed into UDFs on result files (measurement records) that map directly to the derived samples being measured.

The XmlSampleNameParser tool is installed as a standalone jar file as part of the NGS Extensions Package. Currently it contains one script, parseXmlBySampleName.

Provided the result file is in XML format, this script can be used to match data in the file to samples in the LIMS using the measurement record LIMSID.

Values are mapped to UDFs in the LIMS using a configuration file that contains XPath mappings for the result file. (External resources, such as , can be used to learn more about Xpath, and many XML viewing tools will generate it automatically for elements of interest.)

The format for the data needed to make the association between the file contents and the sample in the LIMS is: LIMSID_NAME.

• The name is optional and is supported for readability. This means it may come from the input sample on which the step is being run.

• The LIMSID must come from the output result file, which is also where the parsed information will be stored in UDFs.

Typically, it is ideal to set up the instrument run with the sample and result file information, so that it will appear in the same format in the XML result file. To automate setup, you can use a tool such as the template driver file generator.

The LIMSID_NAME can be provided to the instrument as the sample name, or as a comment or other field on the sample. The only conditions are that:

• The sample field that you want to use for the LIMSID_NAME must be passed into the file result file (eg via a driver file).

• The configuration file must be set up such that it can access this field from the correct location. (See .)

Script Parameters and Usage

The parseXmlBySampleName script uses the following parameters, all of which are required:

Example

This example shows the script run on a manually imported TapeStation XML file that has been attached to the TapeStation DNA QC process.

Configuration

The process type for the steps on which information will be tracked must be configured with the following output generation:

• 1x fixed ResultFile output per input

• 2x fixed ResultFile outputs applied to all inputs

• Shared output naming pattern example: {LIST:Instrument Result XML (required),XML Parsing Log}

This represents the minimum configuration. Additional shared output files may be added as required.

For each piece of information that will be parsed from the XML file and stored on the step outputs, configure desired UDFs on ResultFile and associate them with the per-input output result files for the process type.

Configuration File Format

The configuration file should be produced as a .groovy file and stored in the /opt/gls/clarity/customextensions directory. Its format allows for four types of entries:

• baseSampleXPath

• sampleNameXPath

• process.run.UDF."UDF name"

• process.output.UDF."UDF name"

The examples provided here use XPath for a TapeStation XML result file.

baseSampleXPath

• Provide this one time.

• This XPath indicates the list of samples and the associated sample information, relative to the root of the XML file. Specific sample information will be retrieved relative to this path.

sampleNameXPath

• Provide this one time.

• This XPath indicates where the LIMS sample association information (LIMSID_NAME) can be found, relative to the sample list indicated by baseSampleXPath. Often this will be stored as the sample name or in a comment field for the sample.

process.run.UDF."UDF name"

• May be provided multiple times.

• Indicates information that is tracked for the entire run, and not on individual samples.

• Typically, this will be XPath relative to the root of the XML file, as shown.

In the example above, three values will be parsed into the LIMS from the XML file, represented on each individual measurement record (result file) output:

• Conc. Units

• Molarity Units

• MW Units

process.output.UDF."UDF name"

• May be provided multiple times.

• Indicates information that is tracked on individual samples.

• Typically, this will be XPath relative to the sample XPath (baseSampleXPath), as shown.

In the example above, five values will be parsed into the LIMS from the XML file, represented on each individual measurement record (result file) output:

• Concentration

• Region 1 Average Size - bp

• Region 1 Conc.

• Peak 1 MW

Additional Information

Some other scripts you may find useful:

Available from: Clarity LIMS v2.0.5

-haltOnMissingSample option and support for header section values (e.g., containerName) are introduced in NGS v5.4.0.

Data might sometimes need to be parsed from an instrument result file (CSV, TSV, or other character-separated format) into Clarity LIMS, for the purposes of QC.

For example, suppose that a 96 well plate is run on a Caliper GX. The instrument produces a result file, which the user imports into Clarity LIMS. The per-sample data are parsed and stored for a range of capabilities, such as QC threshold checking, searching, and visibility in the Clarity LIMS interface.

The parseCSV script allows for the data for each well to be parsed into fields on either derived samples or result files (measurement records) that map directly to the derived samples being measured.

If the instrument result file contains data that applies to the batch of derived samples being measured, this data are stored in fields on the step.

The Script

The parseCSV script automates parsing a separated-value file, configurable but typically comma- or tab-separated, into the LIMS.

1. Data lines in the file are matched to the corresponding sample in the LIMS using well placement information.

2. A line that references well A1 of container Plate123 will have its parsed data mapped to the sample placed in well position A:1 of container Plate123 in the LIMS.

3. Values from the file are mapped to fields (known as UDFs in the API) in Clarity LIMS based on the automation configuration for the script.

Workflow and Configuration

• Configure the step to invoke the script manually via a button in Record Details screen.

• Before pressing the button that invokes the script, upload a shared result file to be parsed.

• Configure the automation command line to match the destination fields configured in Clarity LIMS.

Script Parameters

Script Usage

Example 1

This example uses matching Strategy 1 for a comma-separated file and maps two columns, "Region[100–1000] Conc. (ng/ul)" and "Region[100–1000] Size at Maximum [BP]", to output resultfile fields "Concentration" and "Size (bp)" in the LIMS, respectively:

Example 2

This example uses matching Strategy 2 for a tab-separated file, running in relaxed mode. It maps a column to an input sample field, using that input sample placement information, and maps a header section row to a protocol step field:

Parameter Details

Additional Information

Other scripts you may find useful are as follows.

Available from: BaseSpace Clarity LIMS v3.1.0

Included as part of the NGS Extensions package, the convertToExcel script is designed to convert separated-value files (eg CSV) to Microsoft Excel spreadsheets of type XLS and XLSX.

• The script can be run on comma- and tab-separated files with any file extension. The original file is not edited, unless its name matches the name given for the output file.

• The script can update an existing Excel spreadsheet or produce an entirely new one.

Last Updated: July 2025

Document Version: 2

This article describes the metadata, tokens, and special characters that you can include in your custom template files for use with the Template File Generator.

Available from: BaseSpace Clarity LIMS v5.1.x

Metadata

The following table lists and describes the metadata elements that you can include in your template files.

• Unless otherwise specified, metadata elements are optional. In some cases, a metadata element must be used in conjunction with another element. For example, ILLEGAL.CHARACTERS must be used with ILLEGAL.CHARACTER.REPLACEMENTS.

• Unless otherwise specified, metadata elements can appear multiple times in the template. However, if they are paired with values, only the first occurrence is used. The other lines are silently ignored.

• Unless otherwise specified, if a metadata element requires a single value, any additional values are ignored when the file is generated. For example, suppose you include the OUTPUT.TARGET.DIR <path> metadata in your template file and provide more than one value for <path>. The script will process only the first (valid) path value and will ignore all other values.

For more information on metadata and how to use metadata elements in your template files, see in article.

Tokens

A token is a placeholder variable that is replaced with unique data at run time. You can include tokens in automation command lines, in scripts, and in template files.

For example, suppose you include the INPUT.CONTAINER.NAME token in a template file generated by a step. At run time, this token is replaced with the name of the container that was input to the step.

All tokens included in a template file must appear in the following form: ${TOKEN}, for example - ${INPUT.CONTAINER.NAME}.

Input and Output Tokens

For steps with ResultFile inputs or outputs, refer to the following entries in the table:

• INCLUDE.INPUT.RESULTFILES

• INCLUDE.OUTPUT.RESULTFILES

Process Tokens

Submitted Sample Tokens

Other Tokens

Special Characters

CSV and template file generation special characters have substitution symbols within templates.

Revision History

Available from: BaseSpace Clarity LIMS v4.2.x

You can create template files that the Template File Generator script (driver_file_generator) will use to generate custom files for use in your lab.

This article provides details on the following:

• The parameters used by the script.

• The sections of the template file—these define what is output in the generated file.

• Sorting logic—options for sorting the data in the generated file.

• Rules and constraints to keep in mind when creating templates and generating files.

• Examples of how you can use specific tokens and metadata in your template files.

For a complete list of the metadata elements and tokens that you can include in a template file, see .

Script Parameters

The following table defines the parameters used by the driver_file_generator script.

Command-line example:

Command-line example using -quickAttach and -destLIMS:

See also the section.

Data Source

The input-output-maps of the step (defined by the -stepURI parameter) are used as the data source for the content of the generated file.

If they are present, input-output-maps with the attribute output-generation-type=PerInput are used. Otherwise, all input-output-map items are used.

By default, the data source entries are sorted alphanumerically by LIMS ID. You can modify the sort order by using the SORT.BY and SORT.VERTICAL metadata elements (see section of the article).

Template Sections

The content of the generated file is determined by the sections defined in the template. Content for each section is contained within xml-like opening and closing tags that are structured as follows:

Most template files follow the same basic structure and include some or all the following sections (by convention, section names are written in capital letters, but this is not required):

The order of the section blocks in the template does not affect the output. In the output file, blocks will always be in the order shown.

The area outside of the sections can contain metadata elements (see section of the article). Anything else outside of the section tags is ignored.

The <PLACEMENT> and <TOKEN FORMAT> sections are not part of the list and do not create distinct sections in the generated file. Instead, they alter the formatting of the generated output.

HEADER_BLOCK

The header block section may include both plain text and data from the LIMS. It consists of information that does not appear multiple times in the generated file—ie, the information is not included in the data rows (see section)

Tokens in the header block always resolve in the context of the first input and first output available. For example, suppose the INPUT.CONTAINER.TYPE token is used in the header block:

• If there is only one type of input container present in the data source, that container type will be present in the output file.

• If multiple input container types are present in the data source, only the first one encountered while processing the data will be present in the output file.

For this reason, we recommend against using tokens that will resolve to different values for different samples - such as SAMPLE.NAME. If one of these tokens is encountered, a warning is logged and the first value retrieved from the API is used. (Note that you may use.ALL tokens, where available.)

To include a header block section in a template, enclose it within the <HEADER_BLOCK> and </HEADER_BLOCK> tags.

HIDE feature: If one of the tokens of a line is empty and is part of a HIDE statement, that line will be removed entirely. See and examples.

HEADER

The header section describes the header line of the data section (see section). A simple example might be "Sample ID, Placement".

The content of this section can only include plain text and is output as is. Tokens are not supported.

To include a header section in a template, enclose it within the <HEADER> and </HEADER> tags.

HIDE feature: See 'Hide feature' in section. Also note:

• If multiple <HEADER> lines are present, at least one must have the same number of columns as the <DATA> template line.

• <HEADER> lines that do not match the number of columns are unaffected by the HIDE feature.

DATA

Each data source entry creates a data row for each template line in the section. All entries are output for the first template line, then the next template line runs, and so on.

The data section allows tokens and text entries. All tokens are supported.

Note the following:

• Duplicated rows are eliminated, if present. A row is considered duplicated if its content (after all variables and placeholders have been replaced with their corresponding values) is identical to a previous row. Tokens must therefore provide distinctive enough data (ie, something more than just CONTAINER.NAME) if all of the input-output entry pairs are desired in the generated file.

• By default, the script processes only sample entries. However, there are metadata options that allow inclusion of result files/measurements and exclusion of samples.

• Metadata sorting options are applied to this section of the template file only.

To include a data section in a template, enclose it within the <DATA> and </DATA> tags.

HIDE feature: If the token in a given column is empty for all lines and that token is part of a HIDE statement, that column (including the matching <HEADER> columns) will be removed entirely. There can only be one <DATA> template line present when using the HIDE feature. See and examples.

FOOTER

The content of this section can only include plain text and is output as is. Tokens are not supported.

To include a footer section in a template, enclose it within the <FOOTER> and </FOOTER> tags.

PLACEMENT

This section contains groovy code that controls the formatting of PLACEMENT tokens (see the PLACEMENT tokens in article table).

Within the groovy code, the following variables are available:

Note the following:

• The script must return a string, which replaces the corresponding <PLACEMENT> tag in the template.

• Logic within the placement tags can be as complex as needed, provided it can be compiled by a groovy compiler.

• If an error occurs while running formatting code, the original location value is used.

To include a placement section in a template, enclose it within the <PLACEMENT> and </PLACEMENT> tags.

Placement Example: Container Type

In the following example:

• If the container type is a 96 well plate, sample placement A1 will return as "A_1"

• If the container type is not a 96 well plate, sample placement A1 will return as "A:1"

Placement Example: Zero Padding

TOKEN FORMAT

This section defines logic to be applied to specific tokens to change the format in which they appear in the generated file.

Special formatting rules can be defined per token using the following groovy syntax:

Within the groovy code, the variable 'token' refers to the original value being transformed by the formatting code. The logic replaces all instances of that token with the result.

${token.identifier} marks the beginning of the token formatting code and the end of the previous token formatting code (if any).

• You can define multiple formatting logic rules for a given token, by assigning a name to the formatting section (named formatters are called 'variations'). This is done by appending “##” after the token name (eg “${token.identifier##formatterName}”).

• Using the named formatter syntax without giving a name (“${token.identifier##}”) will abort the file generation.

• If an error occurs while running formatting code, the resulting value will be blank.

To include a placement section in a template, enclose it within the <TOKEN_FORMAT> and </TOKEN_FORMAT> tags.

TOKEN FORMAT Example: Technician Name

In this example, a custom format is defined for displaying the name of the technician who ran a process (step).

The name of the token appears at the beginning of the groovy code that will then be applied. In this code, the variable 'token' refers to the token being affected. The return value is what will replace all instances of this token in the file.

TOKEN FORMAT Example: Appending a String to Container Name or Sample Name

In this second example, when special formatting is required for two tokens, the logic for both appear inside the same set of tags.

The example appends a string to the end of the input container name or a prefix to the beginning of the submitted sample name.

Metadata

Metadata provides information about the template file that is not retrieved from the API — such as the file output directory to use, and how the data contents should be grouped and sorted.

Metadata is not strictly confined to a section, and is not designated by opening and closing tags. However, each metadata entry must be on a separate line.

Metadata entries can be anywhere in the template, but the recommended best practice is to group them either at the top or the bottom of the file.

For a list of supported metadata elements, rules for using them, and examples, see , section.

Sorting Logic

Sorting in the generated file is done either alphanumerically or by vertical placement information, using the SORT.BY. and SORT.VERTICAL metadata elements.

Sorting must be done using a combination of sort keys - provided to SORT.BY. as one or more ${token} values, each of which always produces a unique value in the file. For example, sorting by just OUTPUT.CONTAINER.NAME would work for samples placed in tubes, but would not work for samples in 96 well plates. Sorting behavior on nonunique combinations is not guaranteed to be predictable.

To sort vertically:

Include the SORT.VERTICAL metadata element in the template file. In addition, the SORT.BY.${token}, ${token} metadata must also be included, as follows:

Any SORT.BY. tokens will be sorted using the vertical sorter instead of the alphanumeric sort.

To apply sorting to samples in 96 well plates:

You could narrow the sort key to a unique combination such as:

See also SORT.VERTICAL and SORT.BY. in the article.

Rules and Constraints

The template must adhere to the following rules:

• Metadata entries must each appear on a new line and be the only entry on that line.

• Metadata entries must not appear inside tags.

• Opening and closing section tags must appear on a new line and as the only entry on that line.

If any of the following conditions is not met - the tag, and everything inside it, is ignored by the script and a warning displays in the log file:

• Except for the metadata, all template sections must be enclosed inside tags.

• Each tag must have its own line, and must be the only tag present on that line.

• No other entries, even empty ones, are allowed.

Examples

Illumina Instrument Sample Sheets

The LIMS provides configuration to support generation of sample sheets that are compatible with some Illumina instruments. For details, see the documentation.

Generating Sample Sheets for QC Instruments

The LIMS provides configured automations that generate sample sheets compatible with a number of QC instruments. The default automation command lines are provided below.

Renaming Generated Files

In the template file, the following OUTPUT.FILE.NAME metadata element renames the generated template file 'NewTemplateFileName':

In the automation command line, the following will attach the generated file to the {compoundOutputFileLuid0} placeholder, with the name defined by the OUTPUT.FILE.NAME metadata element.

Using Token Values In File Names

The OUTPUT.FILE.NAME and OUTPUT.TARGET.DIR metadata elements support token values. This allows you to name files based on input / output values of the step - the input or output container name, for example.

The following tokens are supported for this feature:

• PROCESS.LIMSID

• PROCESS.UDF.<UDF NAME>

• PROCESS.TECHNICIAN

• DATE

Rules and Constraints

When using token values in file names, the following rules and constraints apply:

• Container-related functions will return the value from a single container, even if there are multiple containers.

• Other tokens will function, but will only return the value for the first row of the file (first input or output).

• If the OUTPUT.FILE.NAME specified does not match the LIMS ID of the file, the output file will not be attached in the LIMS user interface. To ensure that the file is attached, include the quickAttach and destLIMSID parameters in the command-line string.

Defining a Project Name for Control Samples

You can use the CONTROL.SAMPLE.DEFAULT.PROJECT.NAME metadata element to define a project name for control samples. The value specified by this token will be used when determining one or more values for the SAMPLE.PROJECT.NAME and SAMPLE.PROJECT.NAME.ALL tokens.

Example:

Rules and Constraints

• If the token is found in the template, but with no value then no project name will be given for control samples.

• If the token is not found in the template, then no project name will be given for control samples.

• If multiple values are provided, the first one will be used.

Using HIDE to Exclude Empty Columns

You can use tthe HIDE metadata element to optionally hide a column if it contains no data. The following lines in the metadata will hide a data column when empty:

Assuming ${OUTPUT.UDF.SAMPLEUDF} is one of the data columns specified in the template, then that column will be hidden whenever there is no data to show in the output file. If a list of fields is provided, then any empty ones will be hidden:

You may also hide only one representation of a specific column or field:

Using HIDE to Exclude Empty HEADER rows

You can also use the HIDE metadata element with tokens in the header section. If one or more tokens are used for a header key value pair, and there are no values for any of the tokens, the entire row will be hidden.

Assuming ${OUTPUT.UDF.SAMPLEUDF} is one of the rows specified in the template header section, that header row will be hidden whenever there is no data to display in the output file.

If a list of tokens is provided for the value, the row will only be shown if one or more of the tokens resolves to a value:

Generating Multiple Files

If you would like to generate multiple files, you can use the following GROUP.FILES.BY metadata elements:

• GROUP.FILES.BY.INPUT.CONTAINERS

• GROUP.FILES.BY.OUTPUT.CONTAINERS

These elements allow a file to be created per instance of the specified element in the step, for example, one file per input or per output container. Step level information appears in all files, but sample information is specific to the samples in the given container.

For example, suppose that a step has two samples - each in their own container - with a template file calling for information about process UDFs and sample names. Using this metadata will produce two files, each of which will contain:

• One sample entry

• The same process UDF information

As a best practice, we recommend storing a copy of generated files in the LIMS. To do this, you must use the quickAttach script parameter. This parameter must be used with the destLIMSID parameter, which tells the Template File Generator script which file placeholder to use. (For details, see .)

Naming The Files

When generating multiple files, the script gathers them all into one zip file so only one file placeholder is needed regardless of how many containers are in the step.

The zip file name may be provided in the metadata as follows:

Inside the zip file, include any paths specified for where files should be written. An example final structure inside the zip, where the subfolders are specified using the container name token, could be as follows:

The file naming, writing, and uploading process works as follows:

• The outputPath parameter element is required for the script. You can use this parameter to specify the path to which the generated files will be written and/or the name to use for the file. Use this in the following scenarios:

  • When the target path/name is constant OR

  • When the target path/name includes something that can only be passed to the script via the command line - for example, if you want to include the value of a {compoundOutputFileLuidN} in the path.

If you provide all three of outputPath, OUTPUT.TARGT.DIR, and OUTPUT.FILE.NAME, the result is that outputPath is ignored and the path specified by OUTPUT.TARGET.DIR is used as the parent under which OUTPUT.FILE.NAME is created, even if OUTPUT.FILE.NAME includes a path in addition to the file name.

If you wish to only attach files to placeholders in the LIMS and do not wish to also write anything to disk, then omit OUTPUT.TARGET.DIR and provide the outputPath parameter value as ".". This will cause files to only be written to the temporary directory that is cleaned up after the automation completes.

To produce the example of MyZip.zip, you could use the following:

Script parameters:

Template:

Rules and Constraints

• You can only use one GROUP.FILES.BY metadata element in each template file.

• To attach the files in the LIMS as a zip file, you must provide the quickAttach parameter along with the destLIMSID.

• The zip file name may optionally be specified with the GROUP.FILES.BY metadata.

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

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.

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.

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 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.

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

Example 1

This example uses source well placement and a pattern file placed in: /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

Pattern File Selection

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

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:

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 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 .)

• 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.

Script Parameters and Usage

Example 1

This example uses the minimum configuration for the script:

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:

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: