This topic covers how to capture and use these sample parent relationships in LabKey Server.

• Derive Aliquots or Compounds Using the User Interface
• Capture Sample Parentage: Alias Parent Column
• Update Parent Information During Import
• Capture Sample Parentage: MaterialInputs and DataInputs
• Capture Sample Parentage Through the API
• Include Ancestor Information in Sample Grids
• Include Aliquot Information in Sample Grids
• Lineage SQL Queries
• Lineage Graphs

Derive Aliquots or Compounds Using the User Interface

You can derive samples using the user interface, either by splitting samples up into smaller portions to create aliquots or mixing multiple samples together to create compounds. The user interface for both operations is the same, the difference being that for aliquots you would derive from a single parent, and compounds would be composed of multiple samples.

• From a Sample Type, select one (or more) sample(s) to use as parent, then click Derive Samples.

• Specify Source Materials:
• Name. The source samples are listed here.
• Role. Roles allow you to label each input with a unique purpose.
• Create new roles by selecting Add a New Role... and typing the role name in the box.
• Roles already defined will be on the dropdown list alongside "Add a new role..."
• Number of Derived Samples. You can create multiple derived samples at once.
• Target Sample Type. You have the option to make derived samples part of an existing sample type. If you select no existing sample type, the derived output sample becomes part of the generic Materials table. You can access Materials from the Sample Types web part by clicking Show All Materials.
• Click Next.
• On the next page, you will see input sample information.
• Enter a Name (required if no naming pattern is defined) and any properties specific to the Output Sample(s).

• Click Submit.

• The Roles specified become labels within the graphical view of the samples. To see the graph, click the link next to Lineage Graph:

There is also a link to Derive samples from this sample link on the details view of each individual sample, making creation of aliquots straightforward from here.

Capture Sample Parentage: Alias Parent Column

Within a Sample Type design, you can indicate one or more columns that contain parentage information. The parentage information can exist in the same or a different Sample Type. Parentage information can also exist in a Data Class. On import of new sample data, the Sample Type will look for the indicated column for the parentage information. Note that the column indicated is not actually added to the Sample Type as a new field, instead the system merely pulls data from indicated column to determine parentage relationships.

For example, if you want to import the following samples table:

You would indicate the parent column alias as "ParentVial" (see screenshot below).

To add parentage columns to a Sample Type:

• Navigate to the folder or project where the Sample Type lives.
• In the Sample Types web part, click the target Sample Type.
• In the Sample Type Properties panel, click Edit Type.

• On the Update Sample Type page, click Add Parent Alias.

• In the Parent Alias enter the column name which contains the parentage information. The column name is case sensitive. The column name you enter here should not refer to a column in the existing Sample Type, instead it should refer to a column in the source data to be imported.
• Use the drop down to indicate the Sample Type (or Data Class) where the parent samples reside. This may be in the same Sample Type "(Current Sample Type)", a different Sample Type, or a Data Class.

• You can add additional parent aliases as needed.
• Click Save.

The system will parse the parentage information, and create lineage relationships. Learn about lineage graphs below.

Update Parent Information During Import

You can also update parent information during import (change or delete parents) by selecting the "Update data for existing samples during import" checkbox.

Learn more in this topic: Update or Remove Sample Lineage During Import

Capture Sample Parentage: MaterialInputs and DataInputs

When importing samples, you can indicate parentage by including a column named "MaterialInputs/<NameOfSampleType>", where <NameOfSampleType> refers to some existing sample type, either a different sample type, or the current one. Similarly, "DataInputs/<NameOfDataClass>" can be used to refer to a parent from a data class.

Note that the MaterialInputs (or DataInputs) column is not actually added to the Sample Type as a new field, instead the system merely pulls data from the column to determine parentage relationships. For example, the following indicates that DerivedSample-1 has a parent named M-100 in the sample type RawMaterials.

You can point to parents in the same or different sample types. The following shows child and parent samples both residing in the sample type MySampleType:

To indicate multiple parents, provide a list separated by commas. The following indicates that DerivedSample-2 is a mixture of two materials M-100 and M-200 in the RawMaterials sample type.

You can indicate parents across multiple sample types by adding multiple MaterialInput columns. The following indicates that DerivedSample-3 has three parents, two from RawMaterials, and one from Reagents:

Samples can be linked to a parent from a data class member using a similar syntax. The following indicates that DerivedSample-4 is derived from an expression system ES-100:

Capture Sample Parentage: API

You can create a LABKEY.Exp.Run with parent samples as inputs and child derivatives as outputs.

Include Ancestor Information in Sample Grids

You can include fields from ancestor samples and sources by customizing grid views.

For example, if you had a "PBMC" sample type and wanted to include in the grid both the "Draw Date" field from the parent "Blood" sample type AND the "Strain" field from a "Mouse" source, you would follow these steps:

• Open the details page for the "PBMC" sample type.
• Select > Customize Grid.
• Expand the "Ancestors" node, then "Samples", then "Blood".
• Check the box for "Draw Date".
• In the "Ancestors" node, expand the "Registry And Sources" node, then "Mice".
• Check the box for "Strain".

• In the Selected Fields panel, drag the new fields to where you want them to be displayed, in this case to the right of the "Processing Operator" field.
• You can use the to edit the title if desired, shown here we include the name of the parent type in the display title for each column.

• Save the grid view, making sure to share it with all users.
• You can decide whether to save it as the Default grid, or save it with a name that will let you find it under the menu.
• Now the grid will include your fields. You could then filter, sort, and search based on that parent metadata. Shown below, we're showing only samples that come from "BALB/c" mice.

Include Aliquot Information in Sample Grids

When viewing a grid of samples, you will see the following calculated columns related to aliquots. Both of these columns are populated only for the original samples; they are set to null for aliquots themselves.

• Aliquot Total Amount: Aggregates the total available amount of all aliquots and subaliquots of this sample. Includes any aliquot with a status of type "Available".
• Aliquots Created Count: The total number of aliquots and subaliquots of this sample.
• This column is populated only for samples, and set to zero for samples with no aliquots.

Lineage SQL Queries

Syntax for querying the lineage of samples and dataclasses provides the opportunity to write SQL queries leveraging these relationships. The "expObject()" method available on some datastructures (Sample Types, Data Classes (i.e. Sources), exp.Runs, exp.Materials, exp.Data) returns a lineage object that can be used with the following variations of the IN/NOT IN operators. Using these operators on anything other than what expObject() returns will result in an error.

Example 1: Find Blood ancestors of a given PBMC sample:

SELECT Name
FROM samples.Blood 
WHERE Blood.expObject() IN EXPANCESTORSOF
(SELECT PBMC.expObject() FROM samples.PBMC WHERE PBMC.Name='PBMC-2390')

Example 2: Find PBMC descendants of a given Blood sample:

SELECT Name
FROM samples.PBMC 
WHERE PBMC.expObject() IN EXPDESCENDANTSOF 
(SELECT Blood.expObject() FROM samples.Blood WHERE Blood.Name='Blood-1464')

Example 3: Find "Cell Line" (Registry Source) ancestors of all the samples linked from an assay run:

SELECT Name
FROM exp.data.CellLine
WHERE CellLine.expObject() IN EXPANCESTORSOF
(SELECT Runs.expObject() FROM assay.General.MiniAssay.Runs WHERE Name = 'Run1')

Example 4: Find "Cell Line" (Registry Source) children of two Vectors:

PARAMETERS
(
   Vector1 VARCHAR DEFAULT 'Vector-1',
   Vector2 VARCHAR DEFAULT 'Vector-2'
)
SELECT Q1.Name
FROM (SELECT Name
   FROM samples.CellLines 
   WHERE CellLines.expObject() IN EXPDESCENDANTSOF 
   (SELECT Vectors.expObject() FROM exp.data.Vectors WHERE Vectors.Name=Vector1)) AS Q1
INNER JOIN (SELECT Name
   FROM samples.CellLines 
   WHERE CellLines.expObject() IN EXPDESCENDANTSOF 
   (SELECT Vectors.expObject() FROM exp.data.Vectors WHERE Vectors.Name=Vector2)) AS Q2
ON Q1.Name = Q2.Name

Lineage Graphs

Derived samples are represented graphically using "lineage graphs". To view:

• Go to the Sample Type of interest.
• Click the individual sample id or name.
• In the Standard Properties panel, click the link for the Lineage Graph, i.e.: Lineage for <Your Sample Name>. If there is no parentage information, there will be no link and no graph.

Samples are represented as rectangles and the derivation steps are shown as diamonds. Note that elements in the graph are clickable links that navigate to details pages. By default you will see the Graph Detail View:

If you click the Graph Summary View tab, you will see a different presentation of the same process and lineage.

Clicking Toggle Beta Graph (New!) from the Graph Summary View will give you a another way to view the same information. Click any node to reset the point of focus of this graph, explore details in the panel to the right, and zoom/resize the graph using the controls.

Rendering Differences

Note that lineage graphs can differ depending on the way that the data is entered. When you manually derive multiple child samples from a parent via the Derive Samples button, the lineage graph summary view will show these child samples on one graph, as shown below in a case where two additional samples have been derived from the "Derived Yeast Sample".

When the sample parent/child relationships are imported via copy-and-paste or via the API, separate lineage graphs will be rendered for each parent/child relationship. A single graph showing all the child sample simultaneously will not be available.

Related Topics

• LabKey Data Structures
• Data Classes
• Update or Remove Sample Lineage During Import
• Experiment Lineage Graphs