Find the Container Location of a Derived Sample

As samples are processed in the lab, substances are moved from one container to another. Because container locations are sometimes used to reference the sample in data files, tracking the location of these substances within containers is one of the key values that Clarity LIMS provides to the lab.

Within the REST API (v2 r21 or later), analytes represent the substances on which processes/steps are run. These analytes are the substances that are chemically altered and transferred between containers as samples are processed in the lab.

Each individual sample resource has an analyte artifact that describes its container location and is used to run processes.

In Clarity LIMS, steps are not run on the original submitted samples, but are instead run on (and can also generate) derived samples. In the API, derived samples are known as analytes. Each sample resource, which is the original submitted sample in Clarity LIMS, has a corresponding analyte that is used for running processes/steps and describing placement in a container.

For more information on analyte artifacts and other REST resources, see Structure of REST Resources.

For all Clarity LIMS users, make sure you have done the following actions:

• Added a sample to Clarity LIMS.
• Run a process/step on the sample, with the same process/step generating a derived sample output.
• Added the generated derived sample to a multi-well container (eg, a 96-well plate).

The container location information for an individual derived sample/analyte is located within the XML for the individual artifact resource. Because artifacts are generated by running steps in the LIMS, this is a logical place to keep track of the location.

Within a script, you can use a GET method to request the artifact. The resulting XML structure contains all the information related to the artifact, including its container and well location.

In this example, a derived sample named Brain-600 is placed in well A:1 of a container with LIMS ID 27-1259. This information is found in the location element. The information is highlighted in red.

<art:artifact uri="http://yourIPaddress/api/v2/artifacts/HAM751A481PA1?state=9995" limsid="HAM751A481PA1"> <name> Brain-600 </name> <type>Analyte</type> <output-type>Analyte</output-type> <volume unit="uL">645.0</volume> <concentration unit="ug/mL">0.5478</concentration> <qc-flag>UNKNOWN</qc-flag> <location> <container uri="http://yourIPaddress/api/v2/containers/27-1259" limsid="27-1259"/> <value>A:1</value> </location> <working-flag>true</working-flag> <sample uri="http://yourIPaddress/api/v2/samples/HAM751A481" limsid="HAM751A481"/></art:artifact>

The location elements have two child data elements:

• One linking to the container URI, which specifies which container the analyte is in.
• One for the well location, which has the name value in the XML structure.

Valid values for a well location can be either numeric or alphabetic, and are determined by the configuration of the container in Clarity LIMS.

Well locations are always represented in the row:column format. For example, a 96-well plate can have locations A:1 and C:12, and a tube can have a single well called 1:1.

Use the following XML example to retrieve the artifact:

// Retrieve the artifact artifactURI = "http://${hostname}/api/v2/artifacts/${artifactLIMSID}" artifact = GLSRestApiUtils.httpGET(artifactURI, username, password)

Because the container position is structured in the row:column format, you can store the row and column in separate variables by splitting the container position on the colon character. You can access the string value of the location value node using the text() method, as shown in the following code:

// Separate the artifact's position inside of its container containerPosition = artifact.location.value.text() positionList = containerPosition.tokenize(':') // Output its position row = positionList[0] column = positionList[1] println "This sample is located at row: $row, column: $column"

Running the script in a console produces the following output:

This sample is located at row: A, column: 1

GetContainerAnalyteLocation.groovy.txt