Aliquot: Workflow Editor Tutorial

This tutorial is aimed at intermediate level users who have explored the use of Antha via the beginners protocol card method, but, wish to advance their use of Antha to provide more flexibility and functionality to their workflows.

About this tutorial

This tutorial will cover how to use the Aliquot element within the Workflow Editor. Specifically it will cover in greater detail the user defined parameters for this element and how the Workflow editor can be used to wire together upstream or downstream elements.

Things you'll need

Before you begin this tutorial it will help you if you take a look at the following UI reference documentation, although it isn't a necessity:

What you'll learn

In this tutorial you will learn how to:

  • Search for and load an element into the Workflow Editor window
  • Set parameters and what these parameters do
  • How to use the configuration section
  • How to simulate the Aliquot element against your chosen parameter and configuration set
  • How to view your simulated results in the graph view
  • How to wire your Aliquot element to upstream or downstream elements

How to search for and load up element

Firstly, you will need to access the Antha Workflow Editor. To navigate to this page you will see an Editor link in the top navigation bar of your log in homepage.

Antha Home page image, showing different links

Once you are in the Workflow Editor you will need to load the Aliquot element into the workflow window. In order to do this you can access The Aliquot element from your element library on the left hand side of the Workflow Editor.

This can be accessed by one of two ways:

  1. You can manually scroll down through your element library
  2. You can use the Search elements field and search by name, in this instance Aliquot.

Loading the aliquot element from the element library search feature

To load the Aliquot element once you have found it then click on its name once from within the element library. After having done so you will see that it has loaded into the workflow window.

If you hover your mouse over the top of the element card you will see several extra pieces of information:

The workflow window showing inputs and outputs of Aliquot

  1. You will notice above the element name, in this case Aliquot, you will also see the element name with a unique code appended. This unique code identifies this specific instance of this element, such that if you have multiple Aliquot elements running in parallel each one has a unique identifier to match that instance of the element to its specific set of parameter values.
  2. You will also be presented with all the parameters that are inputs into your element and the resulting outputs from this element, in this case Aliquots.
  3. You will notice that the different Input parameters are colour coded to the "type" of parameter. the Antha programming language (like its parent language Go) is heavily type based in that a parameter must be declared by the type of data it deals with, e.g. Integers, Volumes, Concentrations, etc. We will cover this in more detail later and explain why it is important. If you cant remember what the colours are you can click on the INPUTS info tab to display a key.

Input colour code key figure

What do the Parameters mean?

Lets take a look at the parameters for the Aliquot element and see what they mean. At the top of the Aliquot Card in the workflow space there is an info icon.

How to access help information regarding the Aliquot element

Clicking on this icon will provide a pop up window with three tabs.

  1. Description
  2. Inputs
  3. Outputs

Figure showing parameter descriptions

The Description tab will provide a description of what the Aliquot element does. This same description can also be seen below the element name in the element library list in the left hand panel of the Workflow Editor.

The Inputs and Outputs tabs provide the colour coded representation of the Input/Output parameters, their names, types and a description of what that parameter is for.

Common use case

You will initially be shown a common use case where the Aliquot element is used alone in the workflow. Later in this tutorial we will cover more complex workflows associated with the Aliquot element.

How to edit the parameter values

In order to set the specific values for these parameters you can access the parameters editor for this instance of Aliquot on the right hand side of the Workflow Editor.

The Aliquot name with unique code identifier in the parameters section is a collapsable menu that will reveal the parameters with a single click on that name.

Parameters window with default parameters

You can see that the element is already set up with default parameters, which you can alter as you need to. For example If you wanted to aliquot out a master mix for a reaction 96 times with a volume of 20ul, but some of the components in the mastermix sink to the bottom therefore i want the solution to be mixed first before pipetting I may change the parameters such that they look like the following:

Incorrect parameters

Once you have set your parameters you are ready to simulate this element in silico against a selected automation platform to test there are no errors in your parameters and for Antha to calculate all the low level liquid handling steps required to run this element.

All you need to do is click on the Simulate button.

Simulation output

Clicking on the Simulate button will open up a console window showing you the progress of the simulation. In this example you will notice that the simulation has failed. The error message in the console is telling us that there is not enough solution for the number of aliquots selected.

Incorrect parameters failed simulation

This is because the code driving the Aliquot element has internal checks in place to make sure that that there is enough of the solution you are using for the number of selected aliquots. There are two ways to rectify this error. Either decrease the number of aliquots or increase the volume of the solution you are using. Here we will increase the volume of our master mix.

Correct parameters

Upon simulating this time you should have success and you will be presented with a few different options of what to do next.

A couple of other things to point out is that an estimated time for how long it will take for your automation platform to run will be presented in the top left hand window of the Workflow Editor.

Successful simulation

Beneath the green success notifications in the console window you are presented with two blue task option buttons to take you to the Antha Dashboard, from where you can continue the set up and running of your element, or to see a graphical representation of your simulated results.

The Dashboard View

The Antha dashboard offers the user a lot of information and options of what you want to do next. For example:

In this tutorial we will primarily focus on the graph view of our simulated results. To learn more about how to use the dashboard take a look at the About Dashboard reference documentation, or one of the associated pages in the list above for individual task options found within the Dashboard view.

To access the graphical view of our simulated results click on the blue "open graph in new tab" task option button from within the simulation console of the Workflow Editor. This will open an interactive graphical representation of what your automation platform will do when it is run. Lets take a look.

Graph view

In this tutorial we will focus on the specifics of the Aliquot element in the graphical viewer rather than how to use the graphical viewer itself. To learn more about how to use the graphical viewer then take a look at the About Graph View Lesson.

The graph view for the Aliquot example

This graphical view is showing you all the low level liquid handling movements that will be made when you run the element. It is showing us that the master mix, in this instance called MyMasterMix, needs to be distributed across 11 wells of our input plate (blue circles) and that 20ul aliquots will be pipetted from these wells into 96 wells in our output plate (purple circles).

Often it can be at this point that you may see that the element and parameter set that you chose isn't giving you the liquid handling behaviour you would expect and that you may need to go back and make some edits to either the element you are using or your chosen parameter values, re-simulate and check again.

In this example of Aliquot, If we were to make a master mix manually, we would still need to manually aliquot it out into 11 wells before the automation does the rest. It would be more prudent for us to change the source location (type of plate) for our master mix such that it doesn't need to be split up into smaller volumes. To do this we can specify the input plate type in the Configuration section of the Workflow Editor.

Close down the graph view tab that opened up in your web browser and head back to the Workflow Editor.

How to use configuration

In the panel on the right hand side of the Workflow Editor where your parameters section is, there is also a Configuration tab. Clicking on this will present the configuration options available to you:

  1. Preferences
  2. Input Plate Types
  3. Output Plate Types
  4. Devices
  5. Plates

Workflow Editor Configuration section

In this tutorial we will focus on setting an input plate for the Aliquot element. If you would like to learn more about how to use the configuration section then please head to the About Configuration reference documentation.

So here we want to set our Input Plate Type to be a plate where the wells can hold a larger volume such that all the mastermix can go into a single well/tube.

Clicking on the Pick plate types drop down menu allows you to select a plate type that is most suitable. For this aliquot example we will select a 24 deep square well plate.

Input plate selection

Once the new plate type has ben selected we can repeat the simulation and open up the graph view in a new tab again.

Modified plate graph view

You will now see that the mastermix is being aliquoted out to the 96 destination wells from a single source well.

Additional Use Cases

So far we have shown you how the aliquot element can be used as a stand alone element to aliquot out a specified solution, in this case a master mix. However, what if you don't want to make the master mix yourself manually before it is aliquoted out? Or what if you want to use the element alone as we have already shown but the Solution you wish to use isn't in the Antha library.

Here we will show you how you can wire an upstream element that makes a solution as an output into the input parameter "Solution" of the aliquot element. We will also show you how you can wire a data element to the aliquot element to create a new Solution definition (LHComponent).

To keep in theme with our example we will use an element called MasterMixMaker that makes a master mix for you from its individual components which will then be used as your solution to be aliquoted out.

In this tutorial we will not go into detail of what the mastermix maker element is doing or how it works, if you want to learn more about this element then take a look at the MasterMixMaker Case Study

In the Workflow Editor search for the MasterMixMaker element from the element library panel on the left hand side.

Searching for MAsterMixMaker element in workflow editor

With a single click on the MasterMixMaker element it will be added to the workflow space alongside the Aliquot element we already have there.

MasterMixMaker element added to workflow space

Note that this element is labelled with a number 2 in a green circle. This does not mean it comes after Aliquot which is number 1 but is there to guide the users eyes between the element cards in the workflow space and the parameters for that instance of that element.

There are two crucial inputs the Aliquot element needs to run correctly when wired to an upstream element:

  1. A Physical Solution (or physical solution described by a data element)
  2. A Solution Volume (total volume of that solution available)

Therefore we need to wire these two pieces of information from the MasterMixMaker element into the Aliquot element.

Firstly, you need to locate the output tab that represents our physical solution, in this case Mastermix. When your mouse curser hovers over this tab you will notice that the input tabs from other elements that are compatible with your chosen output will dynamically migrate alongside that output tab. This makes it easier for the user to establish what can and cant be wired together.

In this example there is only one compatible input that can be connected and that is the parameter called "Solution" in our Aliquot element.

Wiring Mastermix to Solution

A single click on the Output Mastermix tab activates this parameter for wiring into another parameter. This is represented by a purple line now connected to your mouse curser such that it will move to wherever you move your mouse to.

Purple wiring tool once output tab is selected

Now you need to click on the input parameter you would like to wire this output parameter to. As mentioned previously, in this case there is only the one option and that is the parameter "Solution" from the aliquot element. Following clicking on this input parameter you will see a physical connection between the two element cards in the workflow space.

Physical connection between two parameters

You now need to repeat this process but with the Solution Volume parameter. As before if you hover over the output tabs of the MasterMixMaker element card you will see a parameter tab named MasterMix Volume. When your mouse curser hovers over this tab you will be presented with two inputs that this could be potentially wired to in the Aliquot element.

Two Volume options offered for connection

The tabs that dynamically migrate to your output tab do so purely based on variable types (e.g. strings to strings, int to int, Volume to Volume etc.)

In this example Aliquot has two parameters that are both of type Volume. It is for the user to determine which one the output from MasterMixMaker should be wired to. To do this the User should read through the parameter descriptions to get an understanding for what each parameter does in this element.

Here, the two volume options are SolutionVolume or VolumePerAliquot. It should be clear that the volume being output from MasterMixMaker is the total volume of master mix that has been made and therefore should not be wired to the VolumePerAliquot parameter.

The SolutionVolume parameter in Aliquot is for the user to define the total volume of the solution you have to be aliquot out. Therefore this is the match for our MasterMixVolume parameter. Once these options have been chosen and wired together by clicking on the output tab followed by clicking on the correct input tab we now see a second physical connection between our two elements.

Two physical connections made

Now we are ready to simulate our new workflow.

Simulation output

If we simulate the new workflow, by clicking on the simulation button, with the default parameters that are set for both the MasterMixMaker and Aliquot element you will see that we get the same error that we had previously telling us that there is not enough volume for this many aliquots.

This is because the default parameters for MasterMixMaker are set to make 4 x 5ul reactions (therefore 20ul) and our Aliquot element default parameters wants to make 8 x 25ul aliquots. This clearly would not work. So lets change these values to a more real world example.

Lets say you want to make 96 aliquots of mastermix for a construct assembly that can be stored in a multiwell plate. We would set the parameters such that the MasterMixMaker parameters look like:

MasterMixMaker parameters

And the Aliquot parameters would look like:

Aliquot parameters

Now if you simulate you should see all tests are a success an that you can visualise the results of the simulation in the graphical view as we did previously.

Graph view

The graphical view for this simulation now shows the individual components of a master mix being mixed together and then this master mix aliquoted out 96 times.

MasterMixMaker into Aliquot graph view