Sample Input Sheet Template Sections

Compatibility—NGS v5.16 and earlier

A generic sample input sheet file template may consist of up to seven different sections. These sections are described below.

The metadata describes information about the file that is not retrieved from the API, such as the file output directory to use and how the data contents should be sorted.

• Metadata is not strictly confined to a section, and is not designated by surrounding tags.
• Each piece of metadata information must appear on a separate line from the rest of the text in the template file.
• Metadata entries can be anywhere in the template. However, it is the recommended best practice to group them either at the top or the bottom of the file.

The header block consists of information, which may include plain text and data from the LIMS, that does not appear multiple times in the file (e.g. it is not part of the data rows).

• To include a header block in the template, enclose it within the <HEADER_BLOCK> and </HEADER_BLOCK> tags.
• Tokens that may have more than one value are not fully supported in the header block. If one of these is encountered, such as SAMPLE.NAME, a warning will be logged and the first value retrieved from the API will be used.

For example, using INPUT.CONTAINER.TYPE in the header block when there is only one type of input container would simply result in that type being present in the output sample sheet file. However, if there were more than one type of input container, only the first one encountered while processing the data would appear.

Fully-supported tokens:

• PROCESS.TECHNICIAN
• PROCESS.LIMSID
• PROCESS.UDF

UDF token usage:

To include a UDF token in a template, specify the token as ${PROCESS.UDF.process udf name}, where 'process udf name' is the exact name of the UDF within the LIMS. UDF names with spaces are supported.

The header section describes the header line of the sample sheet file's data section. A simple example may be "Sample ID,Placement".

• This section of the template starts with <HEADER> and ends with </HEADER>.
• The header can only include plain text entries; no tokens are allowed.

The data section of the template describes the contents of the rows that will contain unique values pulled from each input/output to the process.

• This section of the template is enclosed in <DATA> and </DATA> tags.
• The data section allows both tokens and text entries, and any tokens are allowed.
• If there is at least one token relevant to the process inputs or outputs, this section will produce a row for each PerInputentry in the process input-output-map. If no PerInput entries are present in the process input-output-map, the script will attempt to add data rows for PerAllInputs entries.
• Only unique data rows are written to the sample sheet file. As such, the tokens must provide distinctive enough data (i.e. something more than just CONTAINER.NAME) if all of the input-output entry pairs are desired in the generated driver file.
• By default, the script processes only sample entries; however, there are metadata options that allow inclusion of result files and exclusion of samples.
• Metadata sorting options are applied to this section of the sample sheet file only. Artifacts are loaded dynamically and only once, if the tokens that need them have been encountered in the template file.
• Input and Output artifacts are always loaded if <DATA> section is present in the template, due to the need to determine what type of artifacts the script is dealing with.
• Pooled artifacts are treated as a single input artifact. (It is possible to expand the script to process each pooled artifact separately should such a need arise.)

The footer section is very similar to the HEADER section.

• This section is enclosed in <FOOTER> and </FOOTER> tags.
• No tokens are allowed.
• This section is enclosed in <PLACEMENT> and <PLACEMENT> tags.
• The section specifies the way INPUT.CONTAINER.PLACEMENT and OUTPUT.CONTAINER.PLACEMENT tokens are formatted.
• Within the segment valid groovy code must be present (as if it was a separate script).

The inputs to the script are:

• String row
• String column
• Node containerTypeNode

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, as long as it can be compiled by a groovy compiler.

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>

// The inputs to this segment are: String row, String column, Node containerTypeNode

if (containerTypeNode.@name == "96 well plate")

return row + "_" + column

else

return row + ":" + column

</PLACEMENT>

<PLACEMENT>

// The inputs to this segment are: String row, String column, Node containerTypeNode

String zeroPad (String entry) {

if (entry.isNumber() && entry.size() == 1) return "0" + entry

return entry

}

return zeroPad(row) + ":" + zeroPad(column)

</PLACEMENT>

This section defines logic that should be applied to specific tokens in order to change the format in which they appear in the final document produced.

It is enclosed in <TOKEN_FORMAT></TOKEN_FORMAT> tags and supports groovy syntax. The code written is applied to its corresponding token, and then replaces that token's value with the result once the code is evaluated.

The inputs to the script are:

• String token

A variable "token" will be available and set to the current value retrieved from the LIMS. The code is applied to each instance of the token.

In the example below, a custom format has been defined for displaying the name of the technician who ran the process.

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>${PROCESS.TECHNICIAN}

def name = token.split(" ")

return "First name: " + name[0] + ", Last name: " + name[1]

</TOKEN_FORMAT>

In this second example, special formatting is required for two tokens. When applying logic to more than one token, they all appear inside the same set of tags.

This example appends a string to the end of the input and output container names.

<TOKEN_FORMAT>

${INPUT.CONTAINER.NAME}

return token + "-SourcePlateName"

 

${OUTPUT.CONTAINER.NAME}

return token + "-DestinationPlateName"

</TOKEN_FORMAT>

In this example, instead of making a Token, text can be entered into the content of the row. Using this example: "${OUTPUT.LIMSID}, 1" in the <DATA> section, results in each row have the LIMSID in the first column, and a 1 in the second column.