When working with multiplexing, you can do the following:

• Find the Index Sequence for a Reagent Label

• Demultiplexing

• Pool Samples with Reagent Labels

• Apply Reagent Labels with REST

• Apply Reagent Labels When Samples are Imported

• Apply Reagent Labels by Adding Reagents to Samples

When importing sample data into Clarity LIMS using a spreadsheet, you can specify the reagent labels to be applied during the import process. To do this, you must include the reagent label names in the spreadsheet, in a column named Sample/Reagent Label.

Prerequisites

Before you follow the example, make sure that you have the following items:

• Reagent types that are configured in Clarity LIMS and are named index 1 through index 6.

• Reagents of type index 1 through index 6 that have been added to Clarity LIMS.

• A compatible version of API (v2 r14 to v2 r24).

Code Example

The following example spreadsheet would import six samples into the system. These samples are Sample-1 through Sample-6 with reagent labels Index 1 through Index 6:

Although not mandatory, it is recommended that you name reagent labels after reagent types using the Index special type. This allows you to relate the reagent label back to its sequence.

Verify with the REST API

If you examine the REST API representation of the samples imported, you are able to verify the following:

• The sample representation shows no indication that reagent labels were applied.

• The sample artifact (the analyte artifact linked from the sample representation) will indicate the label applied via the <reagent-label> element.

The following example shows how an imported sample artifact (Sample-1), with reagent label name applied (Index 1), appears when verified via the REST API:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<art:artifact xmlns:udf="http://genologics.com/ri/userdefined"
    xmlns:file="http://genologics.com/ri/file" xmlns:art="http://genologics.com/ri/artifact"
    uri="http://yourIPaddress/api/v2/artifacts/RCY1A97PA1?state=301" limsid="RCY1A97PA1">
    <name>Sample-1</name>
    <type>Analyte</type>
    <output-type>Analyte</output-type>
    <qc-flag>UNKNOWN</qc-flag>
    <location>
        <container uri="http://yourIPaddress/api/v2/containers/27-12" limsid="27-12" />
        <value>A:1</value>
    </location>
    <working-flag>true</working-flag>
    <sample uri="http://yourIPaddress/api/v2/samples/RCY1A97" limsid="RCY1A97" />
    <reagent-label name="Index 1" />
</art:artifact>

A common requirement in applications involving indexed sequencing is to determine the sequence corresponding to a reagent label. This example shows how to configure index reagent types, which you can then use to find the sequence for a reagent label. Before you follow the example, make sure that you have a compatible version of API (v2 r14 to v2 r24).

Code Example

Reagents and reagent labels are independent concepts in the API. However, the recommended practice is to name reagent labels after reagent types. This allows you to use the label name to look up the sequence information on the reagent type resource. This practice is consistent with the Operations Interface process wizards. When a reagent is applied to a sample in the user interface, a reagent label with the same name of the reagent type is added to the analyte resource.

The following actions are also recommended:

1. Configure an index reagent type with the correct sequence for each type of index or tag you plan to use.

2. Use the names of the index reagent types as reagent labels.

Following these practices allows you to find the sequence for a reagent label by looking up the sequence in the corresponding reagent type.

Step 1. Configure Index Reagent Types

For each index or tag you plan to use in indexed sequencing, configure a corresponding index reagent type as follows.

1. As administrator, click Configuration > Consumables > Labels.

2. Add a new label group.

3. Then, to add labels to the group:

   • Download a template label list (Microsoft® Excel® file) from the Labels configuration screen.

   • Add reagent type details to the downloaded template.

   • Upload the completed label list.

Step 2. Retrieve the sequence for a reagent label using the REST API

After you have configured reagent types for each indexing sequence you intend to use, and have used those reagent type names as reagent label names, you can easily retrieve the corresponding sequence using the REST API.

The following code snippet shows how to retrieve the index sequences (when available):

// Determine the URI of the labeled artifact and retrieve it
labeledArtifactURI = "http://${hostname}/api/v2/artifacts/${labeledArtifactLIMSID}"
labeledArtifact = GLSRestApiUtils.httpGET(labeledArtifactURI, username, password)
 
// Gather its reagent labels
reagentLabels = labeledArtifact.'reagent-label'.@name
if (!reagentLabels) {
    println "No labels found"
    return
}
 
// Build a query URI for possibly multiple reagent labels and execute it
queryParameters = reagentLabels.collect { "name=${it.replace(' ', '+')}" }.join('&')
reagentTypesURI = "http://${hostname}/api/v2/reagenttypes/"
reagentTypeQueryURI = reagentTypesURI + '?' + queryParameters
reagentTypeLinks = GLSRestApiUtils.httpGET(reagentTypeQueryURI, username, password)
 
// For each reagent type found, retrieve it
reagentTypeLinks.'reagent-type'.@uri.each {
    reagentType = GLSRestApiUtils.httpGET(it, username, password)
    reagentTypeName = reagentType.@name
    reagentLabels.remove(reagentTypeName)
    index = reagentType.'special-type'.'attribute'.find { it.@name = 'Sequence' }?.@value
 
    // Output the result
    println "Label: $reagentTypeName"
    println "Index: $index"
}
 
// If there are reagent labels that found no matches
if (reagentLabels) {
    unmatchedLabels = reagentLabels.join(',')
    println "No reagent types found for labels: $unmatchedLabels"
}

For an artifact labeled with Index 1, this would produce the following information:

Label: Index 1
Index: ATCACG

Attachments

RetrievingReagentLabelIndex.groovy:

Demultiplexing is the last step in an indexed sequencing workflow. While the specifics depend on the sequencing instrument and analysis software used, taking pooled samples through sequencing and analysis produces result files/metrics per lane/identifier tag.

These results will likely be in the form of multiple files that you can import back into Clarity LIMS. To do this, you need to set up a configured process that generates process outputs that apply to inputs per reagent label, usually in the form of ResultFile artifacts.

Prerequisites

Before you follow the example, make sure you have the following items:

• Configured reagent types named Index 1 through Index 6 in Clarity LIMS.

• Reagents of type Index 1 through Index 6 in Clarity LIMS.

• A compatible version of API (v2 r14 to v2 r24).

Code Example

Create a Demultiplexing Process in the Clarity LIMS Operations Interface

Configure a process that generates ResultFile with process outputs that apply to inputs per reagent label. It is recommended to name your outputs in a way that clearly identifies the samples to which they correspond (eg, Results for {SubmittedSampleName}-{AppliedReagentLabels}).

Demultiplexing in the User Interface

Running the demultiplexing process on a labeled pooled input produces a process run in the Operations Interface, similar to the one illustrated below.

Note the following:

• There were three reagent labels in the input analyte (sample) artifact. As a result, three outputs were generated (the process was configured to produce one output result file per label per input).

• The names of the outputs of the demultiplexing process expose the original sample name and label.

• The Operations Interface shows details of the genealogy from the downstream result file all the way back to the original sample.

While reagent labels are not explicitly exposed in the Clarity LIMS client user interface, genealogy views in the Operations Interface are aware of reagent labels and will show the true sample inheritance. As noted above, you can use the {AppliedReagentLabels} output naming variable to show the reagent labels applied to each artifact in the user interface.

Demultiplexing in the API with a Process POST

Executing a demultiplexing process by issuing a process POST via the REST API is similar to the typical process execution found in Run a Process/Step.

The key difference is that when executing a demultiplexing process through the REST API, outputs per reagent label are automatically generated from the inputs provided. You do not need to explicitly specify them.

For example, when running the demultiplexing process configured against a single (pooled) sample, you could post a process execution representation like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<prx:process xmlns:prx="http://genologics.com/ri/processexecution">
    <type>Demultiplex</type>
    <technician uri="http://yourIPaddress/api/v2/researchers/4"/>
    <input-output-map>
        <input uri="http://yourIPaddress/api/v2/artifacts/2-424"/>
    </input-output-map>
</prx:process>

The input-output-map only refers to inputs, not outputs, because the demultiplexing process is configured to exclusively produce outputs per reagent label.

If your process produces other outputs, such as shared or per-input outputs, you must explicitly specify input-output-maps for them.

Verify with the REST API

Irrespective of whether you use the user interface or the REST API to run the demultiplexing process, the REST API representation for the process looks something like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<prc:process xmlns:udf="http://genologics.com/ri/userdefined"
    xmlns:file="http://genologics.com/ri/file" xmlns:prc="http://genologics.com/ri/process"
    uri="http://yourIPaddress/api/v2/processes/DMX-RCX-110816-24-95"
    limsid="DMX-RCX-110816-24-95">
    <type uri="http://yourIPaddress/api/v2/processtypes/38">Demultiplex</type>
    <date-run>2011-08-12</date-run>
    <technician uri="http://yourIPaddress/api/v2/researchers/4">
        <first-name>RC</first-name>
        <last-name>RC</last-name>
    </technician>
    <input-output-map>
        <input post-process-uri="http://yourIPaddress/api/v2/artifacts/2-424?state=335"
            uri="http://yourIPaddress/api/v2/artifacts/2-424?state=324" limsid="2-424">
            <parent-process
                uri="http://yourIPaddress/api/v2/processes/PSA-RCX-110812-122-221"
                limsid="PSA-RCX-110812-122-221" />
        </input>
        <output uri="http://yourIPaddress/api/v2/artifacts/92-163?state=339"
            output-generation-type="PerReagentLabel" output-type="ResultFile"
            limsid="92-163" />
    </input-output-map>
    <input-output-map>
        <input post-process-uri="http://yourIPaddress/api/v2/artifacts/2-424?state=335"
            uri="http://yourIPaddress/api/v2/artifacts/2-424?state=324" limsid="2-424">
            <parent-process
                uri="http://yourIPaddress/api/v2/processes/PSA-RCX-110812-122-221"
                limsid="PSA-RCX-110812-122-221" />
        </input>
        <output uri="http://yourIPaddress/api/v2/artifacts/92-164?state=336"
            output-generation-type="PerReagentLabel" output-type="ResultFile"
            limsid="92-164" />
    </input-output-map>
    <input-output-map>
        <input post-process-uri="http://yourIPaddress/api/v2/artifacts/2-424?state=335"
            uri="http://yourIPaddres/api/v2/artifacts/2-424?state=324" limsid="2-424">
            <parent-process
                uri="http://yourIPaddress/api/v2/processes/PSA-RCX-110812-122-221"
                limsid="PSA-RCX-110812-122-221" />
        </input>
        <output uri="http://yourIPaddress/api/v2/artifacts/92-162?state=338"
            output-generation-type="PerReagentLabel" output-type="ResultFile"
            limsid="92-162" />
    </input-output-map>
</prc:process> 

For each input with reagent labels, one output was created per reagent label.

In the example, the process ran on one pooled input, and produced three outputs (the pooled input included three reagent labels). The following example shows one of the demultiplexed result file outputs:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<art:artifact xmlns:udf="http://genologics.com/ri/userdefined"
    xmlns:file="http://genologics.com/ri/file" xmlns:art="http://genologics.com/ri/artifact"
    uri="http://yourIPaddress/api/v2/artifacts/92-163?state=339" limsid="92-163">
    <name>Results for SAM-3 - Index 3</name>
    <type>ResultFile</type>
    <output-type>ResultFile</output-type>
    <parent-process
        uri="http://yourIPaddress/api/v2/processes/DMX-RCX-110816-24-95"
        limsid="DMX-RCX-110816-24-95" />
    <qc-flag>UNKNOWN</qc-flag>
    <sample uri="http://yourIPaddress/api/v2/samples/RCY1A104"
        limsid="RCY1A104" />
    <reagent-label name="Index 3" />
</art:artifact> 

The output contains only one reagent label, and relates only to the sample that was tagged with the same reagent label. Compare this to the case of a pooled artifact, which has several labels and relates to several samples. This level of traceability (from a demultiplexed output back to its specific original sample) is only possible because the artifacts were labeled before they were pooled.

The artifact name generated by the demultiplexing process output name pattern is ("Results for SAM-3 - Index 3"). You can use the {SubmittedSampleName} naming variable to show true ancestors, and the {AppliedReagentLabels} to show any reagent labels applied to an output.

Before pooling samples in a multiplexed workflow, apply reagent labels using one of the methods described in . After the analyte (derived sample) artifacts are labeled, they can be pooled together without loss of traceability.

Pooling samples is accomplished either by running a pooling step in the user interface, or by using the process resource in the REST API.

For an overview of how REST resources are structured, and to learn how the process resource is used to track workflow in Clarity LIMS, see and .

Prerequisites

Before you follow the example, make sure that you have the following items:

• Reagent types that are configured in Clarity LIMS and are named index 1 through index 6.

• Reagents of type index 1 through index 6 that have been added to Clarity LIMS.

• A compatible version of API (v2 r21 or later).

Code Example

Pooling in the User Interface

The following screenshot shows a pooling step run from Clarity LIMS.

Pooling in the API with a Process POST

In general, automation scripts access information about a step using the processURI, which links to the individual process resource. The input-output-map in the XML returned by the individual process resource gives the script access to the artifacts that were inputs and outputs to the process.

Information about a derived sample is stored in the analyte resource. This is used as the input and output of a step, and also used to record specific details from lab processing. The XML representation for an individual analyte contains a link to the URI of its submitted sample, and to the URI of the process that generated it (parent process).

The following example pools all samples found in a given container into a tube it creates.

NOTE: No special code is required to handle reagent labels. As processes execute, reagent labels automatically flow from inputs to outputs.

Verify with the REST API

Irrespective of whether you use the user interface or the REST API to pool samples, the pooled sample is available via process GET requests.

The following example shows one pooled output (LIMS ID 2-424) created from three inputs - LIMS IDs RCY1A103PA1, RCY1A104PA1, and RCY1A105PA1:

Besides deriving from the ancestral sample artifacts, the resulting pooled sample artifact inherits the reagent labels from all inputs. The pooled output produced by the pooling step appears as follows. The pooled artifact shows multiple reagent labels, and multiple ancestor samples.

As processes are executed, reagent labels flow from inputs to outputs.

Attachments

PoolingSamplesWithReagents.groovy:

Reagent labels are artifact resource elements and can be applied using a PUT. To apply a reagent label to an artifact using REST, the following steps are required:

1. GET the artifact representation.

2. Insert a reagent-label element with the intended label name.

3. PUT the modified artifact representation back.

You can apply the reagent label to the original analyte (sample) artifact or to a downstream sample or result file.

Prerequisites

Before you follow the example, make sure that you have the following items:

• Reagent types that are configured in Clarity LIMS and are named index 1 through index 6.

• Reagents of type index 1 through index 6 that have been added to Clarity LIMS.

• A compatible version of API (v2 r14 to v2 r24).

Code Example

In this example, you can adjust the following code:

By inserting the reagent-label element, you end up with the following code.

Although it is not mandatory, it is recommended that you name reagent labels after reagent types using the Index special type. This allows you to relate the reagent label back to its sequence.

If your samples are already in Clarity LIMS, you can assign reagent labels by running the Add Multiple Reagents process/protocol step from the Clarity LIMS user interface. Adding a reagent implicitly assigns a reagent label to every sample artifact. The reagent label applied is derived from the reagent type used.

Prerequisites

Before you follow the example, make sure that you have the following items:

• Reagent types that are configured in Clarity LIMS and are named index 1 through index 6.

• Reagents of type index 1 through index 6 that have been added to Clarity LIMS.

• A compatible version of API (v2 r14 to v2 r24).

For more information on indexes with reagent labels, see .

Code Example

The following illustrations show the Add Multiple Reagents process, as run from the Operations Interface.

Run the Add Multiple Reagents process

In the Add Multiple Reagents wizard panel, reagents (Indexes 1 to 3) are selected and then assigned to the samples (SAM-1 to 3) in the Sample Workspace, using a click and drag process.

The cells of the Sample Workspace represent the wells of the container used for this process.

When the wizard completes, the Add Multiple Reagents process replaces the input sample artifacts with output analyte artifacts.

In the following illustration, the Name column shows the reagent labels applied to the outputs. These are generated by the default output naming pattern for the Add Multiple Reagents process: {InputItemName}-{AppliedReagentLabels}.

Verify with the REST API

When running the Add Multiple Reagents process, the output analyte artifact names show the reagent label applied, as the output naming pattern in the process configuration uses the {AppliedReagentLabels} variable.

By examining the REST API representation of the Add Multiple Reagents process, you can verify the following information:

• The output analyte artifacts show a reagent-label element matching the name of the reagent type used.

• The input analyte artifacts are not modified and do not have reagent labels added.

• The input analyte artifacts do not have a location element, as they were displaced by the outputs.

• You can only determine that reagent labels were applied. You cannot determine which reagent was applied.

The following shows an example of an output from an Add Multiple Reagents process when viewed with the REST API:

Although adding a reagent to a sample automatically assigns a reagent label, reagents and reagent labels are independent concepts in Clarity LIMS. There are ways to add reagent labels that do not involve reagents, and that even when using reagents, it is not possible to accurately determine the reagent used based on the reagent label attached to an artifact.