Applying Indexing Patterns to Containers Automatically

The indexing of samples is often performed in patterns, based upon the location of the samples in the container.

This example shows how to automate the default placing of reagents on samples, based on their container position. This greatly reduces the amount of time spent on the Add Labels screen (LIMS v6.x) and also reduces user error.

In this example, reagent labels are assigned to samples in a predetermined pattern as the user enters the Add Reagents screen. This pattern is applied to all containers entering this stage.

Solution

The example AssignIndexPattern.groovy script is configured to run on the Adenylate Ends & Ligate Adapters (TruSeq DNA) 4.0 step.

Parameters

The script accepts the following parameters:

-i	The URI of the step that launches the script (Required)	The {stepURI:v2:http} token, in the form: http://<Hostname>/api/v2/steps/<ProtocolStepLimsid>
-u	The username of the API user (Required)	The {username} token
-p	The password of the API user (Required)	The {password} token

An example command line is shown below:

bash -c "/opt/gls/groovy/current/bin/groovy -cp /opt/groovy/lib /opt/gls/clarity/customextensions/AssignIndexPattern.groovy -i {stepURI:v2:http} -u {username} -p {password}"

NOTE: The location of Groovy on your server may be different from the one shown in this example. If this is the case, modify the script accordingly.

Step Configuration

In the Clarity LIMS web interface, for the Adenylate Ends & Ligate Adapters (TruSeq DNA) 4.0 step (in the TruSeq DNA Sample Prep protocol), configure Automation as follows:

Clarity LIMS v6.x

• Trigger Location: Add Labels

• Trigger Style: Automatic upon entry

AppExample_ApplyingIndexPatternstoContainersAutomatically_config_v5.png

User Interaction

Assuming the user has added 96 samples and has reached the Adenylate Ends & Ligate Adapters (TruSeq DNA) 4.0 step:

1. The user transfers all 96 samples to a new 96-well plate and proceeds with step.

2. When the user enters the Add Labels screen, the script is initiated. A message box alerts the user that a custom script is in progress.

3. Upon completion, the previously defined success message displays.

4. When the success message is closed, the Add Labels screen loads, and the pattern shown below is applied to samples.

Applying_Index_Patterns_to_Containers_Automatically_ReagentPattern.png

About the code

Once the script has processed the input and ensured that all the required information is available, we can start applying the reagents to our samples.

1. To begin, we need to define the reagents and pattern to apply.

   • The storing of reagents can be accomplished by placing the reagents in a Map, comprised of the reagent names indexed by their respective number, i.e. 'AD030' indexed at 30.

   • The pattern can be stored as a List of Lists. This can be arranged as a visual representation of the pattern to be applied.\

     // Reagent Labels
     public static final def REAGENT_MAP = [
      (27):'AD027 (ATTCCT)', (23):'AD023 (GAGTGG)', (20):'AD020 (GTGGCC)',
      (15):'AD015 (ATGTCA)'
     ]
     // Reagent Pattern
     public static final def REAGENT_PATTERN = [
      [27,27,27,27,27,15,27,27,27,27,27,27],
      [27,27,27,27,15,15,15,27,27,27,27,27],
      [27,27,27,15,15,15,15,15,20,20,20,20],
      [27,27,23,23,15,15,15,20,20,20,20,27],
      [27,23,23,23,23,15,20,20,20,20,27,27],
      [23,23,23,23,23,23,23,23,23,27,27,27],
      [27,27,27,27,27,23,23,23,27,27,27,27],
      [27,27,27,27,27,27,23,27,27,27,27,27]
     ]

   • Once we have our reagents and pattern defined, we can start processing the samples:

   • We start by retrieving the node from the reagent setup endpoint. We use this node as a base for subsequent commands.

   • We then gather the unique output artifact URIs and retrieve the output artifacts using batchGET:\

     // Retrieve the reagent setup
     Node reagentSetup = GLSRestApiUtils.httpGET(stepURI + '/reagents', username, password)
              
     // Collect the artifact URIs and retrieve the artifacts
     def artifactURIs = reagentSetup.'output-reagents'.'output'.collect { it.@uri }.unique()
     def artifacts = GLSRestApiUtils.batchGET(artifactURIs, username, password)

   • Next, we iterate through our list of output artifacts.

   • For each artifact, we determine its position and use its components to index our pattern. This allows us to determine which reagent should be placed on which sample.

   • Once we determine the reagent's name, we create a reagent-label node with a name attribute equal to the desired reagent name.

   • In the list of output-reagents in the reagent setup node, we find the output that corresponds to the output artifact that we are processing and add our reagent-label node to it. NOTE: We must strip off the state from our artifact's URI. The URIs stored in the step setup node are stateless and will not match the URI returned from our output artifact.

   ```
   // For each artifact, determine its position and set its reagent label accordingly
   artifacts.each { artifact ->
       // Split the position into its two components
       def positionIndices = parsePlacement(artifact.'location'[0].'value'[0].text())
    
       // Using our relationship maps, determine which reagent should be placed at that position
       String reagentName = REAGENT_MAP[((REAGENT_PATTERN[positionIndices[0]])[positionIndices[1]])]
    <
       // Create and attach the reagent-label node to our setup
       Node reagentNode = NodeBuilder.newInstance().'reagent-label'(name:reagentName)
       reagentSetup.'output-reagents'.'output'.find { it.@uri == GLSRestApiUtils.stripQuery(artifact.@uri) }.append(reagentNode)
   }
   ```
   

• Once we have processed all of our output artifacts, we POST our modified setup node to the reagentSetup endpoint. This updates the default placement in the API.

• We then define our success message to display to the user upon the script's completion.\

  // Set the reagent setup in the API
  GLSRestApiUtils.httpPOST(reagentSetup, reagentSetup.@uri, username, password)
   
  // Define the success message to the user
  outputMessage = "Script has completed successfully.${LINE_TERMINATOR}" +
          "Clarity LIMS reagent pattern has been applied to all containers."

Assumptions and Notes

• Your configuration conforms with the script requirements documented in Solution.

• You are running a version of Groovy that is supported by Clarity LIMS, as documented in the Clarity LIMS Technical Requirements.

• The attached Groovy file is placed on the LIMS server, in the following location: /opt/gls/clarity/customextensions

• GLSRestApiUtils.groovy is placed in your Groovy lib folder.

• You have imported the attached Reagent XML file into your system using the Config Slicer tool.

• The example code is provided for illustrative purposes only. It does not contain sufficient exception handling for use 'as is' in a production environment.

Attachments

Single Indexing ReagentTypes.xml:

6KB

Single Indexing ReagentTypes.xml

AssignIndexPattern.groovy:

7KB

AssignIndexPattern.groovy