Hands-on: The Experiment's Sample Editor

• 30 min
• Medium

Overview

In the previous tutorial, we learned how to create samples and how to derive them from one another to generate complete lineages. We also saw how protocols can be linked as workflows protocols lists to describe how the samples were processed. We now go a step ahead to learn how we can connect our samples to our electronic lab notebook. Earlier we explained that ELN's experiments reflect the actual execution of one or more protocols (i.e. a protocol is only the recipe while the experiment adds all the details). When performing an experiment you usually consume input samples and generate new output samples; for example, extracting mRNA from a blood sample.

LabID offers a specific editor to manipulate (i.e. link, create) the input and output samples of an experiment: the (Experiment) Sample Editor

• step 1: Creating input/output samples in the sample editor
• step 2: Sample Merge & Split situations
• step 3: Re-using existing samples

Walkthrough

Step 1. Creating input/output samples in the sample editor

First things first, let's take a look at the sample editor and how it works with a simple example.

• Navigate to the Lab Notebook menu and click the Experiment sub-menu.

• Create a new experiment Test Editor using the New experiment :

  • link it to your Tea/Coffee project
  • save the experiment Save

• Scroll down to the Samples panel and click the Edit to bring the sample editor window.

  The sample editor at start

  

  The sample editor lets you link input & output samples. The top buttons allow to import or batch create the samples you need for this experiment.

The top buttons allow to import ( Load samples ) or batch create ( Create input samples or Create output samples ) the samples you need in this experiment. We will see very soon how these work.

Below the top buttons are the two areas:

• the Edit area allows to line up input with output samples. Once a relationship (or multiple) is good, you can move them to the staging area to preserve them from further modifications. This lets you build/edit the input-output relationships in an incremental fashion.
• the Staging area lists all the staged relationships.

Relationships must be staged to be saved Save

After this brief introduction, it's time to construct our first sample relationships. We build on our previous Zebrafish example and assume this experiment reflects the preparation of the sequencing libraries from the extracted mRNA. We will assume that we process 3 samples in parallel; so we need to create three input samples (the mRNA) and three output samples (the sequencing libraries).

• Click on Create input samples to bring up the batch sample creator.

  The sample creator offers to quickly create a batch of samples

  

  The sample batch creator only requires mandatory properties to be described, which vary with the sample type (purple arrow). Many samples of the same type can be batch created by adding as many rows as needed (green arrow).

• Make sure to select the correct input sample type i.e. Sample (purple arrow)

• Add 2 rows as we want to create 3 input samples (green arrow)

• Create three sample of type Sample named zebrafish-rna-1, zebrafish-rna-2, zebrafish-rna-3 (organism: Zebrafish, project: Tea/Coffee Project) and click on Add

  Creating 3 input samples

  

  Controls in column headers allow to set a value to all (or selected) rows at once (purple circles).

The three new samples are added to the Edit area in the Input samples column while the Output samples column is currently empty. Each sample is represented by a rectangular area (boxed in orange) exposing the sample information and action buttons. Importantly, these samples are not yet saved in LabID i.e. they only exist in the editor at the moment as indicated by the new badge (green arrow).

New samples land in the Edit area

The Diagram offers a graphical representation of the sample relationship.

• Click on Create output samples to bring up the batch sample creator and create three samples of type Sequencing library named zebrafish-rna-seqlib1, zebrafish-rna-seqlib2, zebrafish-rna-seqlib3 (organism: Zebrafish ; barcode: AA, CC and GG; project: Tea/Coffee Project )

  Creating 3 output libraries

  

• Click on Add.

  Output samples line up automatically

  

  The stage and Stage all buttons (boxed in red) allow to stage relationships individually or all at once.

The three new samples are added to the Edit area in the Output samples column. LabID automatically lined them up with the input samples (this behavior occurs when all samples are new ).

As one can see in the Diagram area, lining up input and output sample in the same row means creating a connection between the input sample (parent) and the output samples (child).

Let's take a look at the different sample action buttons:

• : duplicate this sample row to build a "merge or split" situation i.e. the sample is itself not duplicated
• : remove this sample ( available for new samples)
• : delete samples (not available for new samples)
• : reorder i.e. move samples up and down (to line up input and output)

We will play with these options in the next exercise. For the moment, we have the expected results so we want to save our work.

• Click on the Stage all to validate the three relationships at once. Notice how the Save is now active : click it.

  Staged relationships

  

  Upon staging relationships move from edit to staging area; and the Save button becomes active.

• After saving, the sample editor remains open. The new badge has disappeared and the sample name is now a hyperlink to the sample detail page.

• Close the editor using the top right

  Experiment's sample section now displays input and output samples

  

• Click on the top-right sample name (boxed in red) to navigate to its sample detail page and check its lineage.

The main features of the sample editor

• the editor's main role is to create relationships between parents (input) and children (output)
• one row represents one parent-child relationship
• new samples can be generated on the fly
• the edit area lets you manipulate the sample relationships
• the staging area lets you freeze the sample relationships (and offloads the edit area)
• save can only happen once all relationships are staged

Step 2. Sample Merge & Split situations

We now explore more complex situations: pooling (or merging) of samples and deriving multiple samples from a parent (or splitting).

For this, we reuse the experiment we just created.

• [if needed] Go to the detail page of your Test Editor experiment and enter Edit mode.

• Scroll down to the Samples panel and click the Edit
  to bring the sample editor window. Notice that the existing relationships are loaded.

  Opening the sample editor with existing relationships

  

  When samples are linked to an experiment, the sample editor loads those relationships in the staging area.

  Why are exiting relationships loaded in the staging area

  This is to avoid mistakenly editing existing relationships. Hence, the user must "unstage" the relationships first.

For the merge situation, we need two new input samples (named s_to_merge_1 and s_to_merge_2 ) and one output sample (s_pooled_1+2).

For the split situation, it is the reverse, we need a new input sample (named s_to_split ) and two output sample (s_out_condition_1 & s_out_condition_2)

Let's create those as we did in the previous exercise.

• Click on Create input samples to bring up the batch sample creator and create three sample of type Sample named s_to_merge_1, s_to_merge_2 and s_to_split (organism: Zebrafish ; project: Tea/Coffee Project) and click on Add

• Click on Create output samples to bring up the batch sample creator and create three sample of type Sample named s_pooled_1+2, s_out_condition_1 & s_out_condition_2 (organism: Zebrafish ; project: Tea/Coffee Project) and click on Add

  The new samples land in the Edit area, misaligned

  

  : you may have a different display and line-up depending on how you executed instructions

The new samples are added to the Edit area panel. When adding the output samples, LabID assumes the default situation (one input -> one output) and lines up the input and output samples, resulting in wrong relationships (you can also check the Diagram section):

• s_to_merge_1 s_pooled_1+2 is correct
• s_to_merge_2 s_out_condition_1 is incorrect
• s_to_split s_out_condition_2 is correct

Remember that one row == one relationship, we, therefore, need 4 relationships:

• s_to_merge_1 s_pooled_1+2
• s_to_merge_2 s_pooled_1+2
• s_to_split s_out_condition_1
• s_to_split s_out_condition_2

Let's see how to do this.

• We need s_pooled_1+2 to appear twice in the Output samples. Click on the (squared in red), a new sample placeholder* is inserted below the row and is lined up with an empty input sample placeholder.

  Duplicating the sample placeholder

  

  Duplicating a sample placeholder allows the creation of "merge and split" situations.

• Drag up the s_to_merge_2 on the empty placeholder using the handle (squared in green).

• The first two rows now reflect the correct relationships for the merge situation. Let's stage them using the stage button under the Alerts & Actions before taking care of the split situation (squared green (1) below).

  Stage individual relationships as early as possible to ease your work in the edit area

  

  Duplicating a sample placeholder allows to create merge and split patterns. A sample placeholder can be cloned (red box 2) and relationships can be individually staged (green box 1) when ready.

• To create the split situation, we also need to duplicate the s_to_split in the Input samples column. As before, click on the (squared in red), of the s_to_split to have a new sample placeholder (also inserted below the row and is lined up with an empty output sample placeholder).

• Drag the s_to_split placeholders to line them up with the s_out_condition_1 and s_out_condition_2 using the handle ; and

  A split situation

  

  A split situation

• Click on the Stage all to validate the two relationships at once; and click Save to save your work. Check the graph in the Diagram section to confirm your work.

  Visual check using the diagram

  

  Merge & Split pattern can be easily checked using the Diagram section

• Close the editor using the top right

Step 3. Re-using existing samples

Re-using samples in multiple experiments is a common scenario. For example, some of the output samples created in the Test Editor experiment would be used as input samples for the next experiment. In such situations, you need to stage the output samples of the Test Editor experiment as inputs for a new experiment. Let's see how this works.

• Create a new experiment Preparing samples for imaging (in Tea/Coffee project), save it and then open the sample editor.

  The sample editor at start

  

  The sample editor lets you link input & output samples. The top buttons allow you to import or batch create the samples you need for this experiment.

• Click on the top Load samples button. We will re-use the output samples we created in the previous exercise. In the pop-up Search for samples, make sure Personal is selected (red arrow) to list only your samples, select s_pooled_1+2, s_out_condition_1 & s_out_condition_2 (red arrow) and click the Add as input samples at the bottom (squared in red, left button)

  Searching for existing samples

  

  The powerful sample search lets you stage existing samples as input or output samples in the editor

  Tip

  Mouse over the table headers to reveal the and click it to unhide the column filters.

• Existing samples are always staged i.e. loaded in the Staging area to prevent mistakes. To connect output samples, we need them in the Edit area : click the Unstage all (squared in red)

  Staging existing samples as input samples

  

  Selected samples are loaded in the staging area of the editor. Connections can be modified after unstaging.

• Click on Create output samples to bring up the batch sample creator and create three sample of type Sample named s_pooled_DAPI, s_condition_1_DAPI & s_condition_2_DAPI (organism: Zebrafish ; project: Tea/Coffee Project) and click on Add. If needed, line up input and output samples to match names up using the handle.

• Click on Stage all and on Save to save your work.

  Linking new output samples to existing input samples

  

• Click on the s_pooled_DAPI sample (squared in red) to open its detail page and check its lineage.

  A lineage with pooling

  

The sample editor is a powerful component to edit sample relationships with options to create samples as you go. It is a focused view on a lineage (i.e. placing you in between 2 sample layers) well suited to the experiment context. Linking input and/or output samples is optional but doing it will greatly enrich the information around your work. We strongly discourage you to soft-link samples in the description of your experiment as we did with e.g. consumables.

How would the samples have been staged if staging them as output ?

You can try to do this in a new experiment; here is how it would look.

Staging existing samples as output samples

When staging samples with parents as output samples, all the relationships with parent samples are also staged (red square).

Unstaging a relationship in the edit area, and deleting it would delete this parent-child relationship from LabID. So be careful!

Congrats! You now have completed this hands-on.

Next we will learn how to use workflows protocols lists templates.