The software was written in Scala and can interoperate with any other language that runs on the Java Virtual Machine, so extensions can be written in Java, Python (via Jython), Lisp (via Clojure), and many other languages.
Files and formats
The software reads in several kinds of files: system configuration, protocol, protocol customization.
The system configuration file specifies the available robots, commands, and devices.
It is in YAML format, which is a convenient, human-editable standard for configuration files.
This file specifies labware, variable, and commands to run in the lab.
It can either be in JSON or YAML format. JSON is a standard for exchange of information
with programs that run in the web browser, making it easy to write custom web application
to control your robots.
Since the protocol may be quite generic, it needs to be customized to different labs.
This is a simple JSON or YAML file that assigns values to the variables in the protocol
and specifies other customizations that aren't explicitly referenced in the protocol.
Additional configuration files
For Tecan robots, configuration is initally performed using Tecan's Evoware software.
Our software reads Evoware's configuration files to ascertain the available devices, labware,
and liquid classes. Evoware also produces template table files which we use in order
to specify the robot's table setup.
When the software is given a protocol which has been customized for a given lab,
it can run that protocol immediately. Generic protocols, however, first undergo
three customization steps.
Customization step 1
Starting with a generic protocol, the software will ask the user to customize
some of its features:
- For each labware, the user selects a labware model
- For each variable, the user selects a value (e.g. volume or concentration)
- For each command, the user selects an agent, a device, and a method (who does it, with which tool, and how)
- For each robot agent, the user selects a table setup
Methods may also specify variables which need to be specified by the user before continuing
Customization step 2
Once the user has finish the first step, the software figures out how to
fulfill any action prerequisites. Examples of this include making sure that
plates are moved to the appropriate locations for pipetting, shaking,
thermocycling, etc., as well as removing a plate lid before pipetting. Since
the software automatically ensures that any prerequisites are fulfilled before
an action is started, the protocol does not need to specify such details. So
now the user is presented with a plan for executing the protocol. The plan will
probably allow for some flexibility, however, so the user is given the
- Set or change variables
Re-order certain steps (e.g. should a plate be unsealed at the beginning of the script or immediately before use)
Customization step 3
The plan could now be executied. However, we can still improve the plan by
adding convenient "post-conditions". Post-conditions complement an action's
prerequisites: they are optional actions to be performed after a primary
action. For example, the pipetting action will require that a plate's lid is
removed, so the post-condition would be to optionally cover the plate again.
So the optional post-condition actions are added to the plan, and the user is
given the opportunity to:
- Set post-condition variables
- Re-order the post-condition actions within the total plan
Remove post-condition actions they don't want
At this point, the planner sets any variables or orderings that the user left unset, and
it optimized pipetting and plate transportation details. The actions are then compiled
into instructions for the target robots, technicians, and stand-alone devices.
The execution of the script generally involves at least two agents (a
technician and a robot), and it may involve multiple stages wherein
measurements determine what should happen next. The software component that
handles this coordination is called the Manager. Instructions for technicians
can be displayed on the computer or communicated over the network to a remote
application. In the case of instructions for a Tecan robot, the manager
generates an Evoware script and runs it via Evoware.
Feedback loops and conditional branches
There are many cases where measurements need to be made before deciding what to
do next. Often this involves repeating a certain procedure until a desired
readout level is achieved. The Manager handles this by first executing
instructions up until a branching point. Once the agents have completed the
instructions, the Manager checks the condition and chooses the appropriate
branch to procede on, again executing instructions up until the next branching
The Manager also supports executing a subset or the entire script as well as
pausing script execution and resuming later.
This section describes some of the most common built-in commands that the software provides.
Most liquid handling is performed by the following commands
dilute: create a dilution series.
distribute: distribute a single reagent to destination wells.
mix: create any number of mixtures in destination wells.
titrate: create a titration series.
transfer: transfer reagents from source to destination wells.
move: move a piece of labware from one site to another
shake: shake a plate
spin: spin down a tube
seal: seal a plate
peel: peal a plate
cover: cover a piece of labware
uncover: remove the cover from a piece of labware
thermocycle: thermocycle a plate or tubes
measure: perform a measurement on a reader
ensureWellMixed: ensure that wells are well-mixed via an unspecified method (e.g. shaking, spinning, centrifugation, or mixing with pipettes)
log: write information to the log file
prompt: display a message to the technician and away their response
Low-level pipetter commands
aspirate: aspirate liquid from a well
dispense: dispense previously aspirated liquid into a well
cleanTips: clean pipetting tips, either by washing or replacing them
washTips: wash pipetting tips
dropTips: drop pipetting tips into the waste bin
getTips: get new pietting tips
Statistical quality control
The software can randomize mixture positions on labware in order to remove some
confounding factors involving sequence or position. The Manager produces CSV
and HTML files describing the mixtures it produces and their positions, so
subsequent measurements can be properly analyzed in an automated or manual
fashion. If you want to perform statistical analysis during protocol execution,
the Manager can interface with statistical software such as R for calculations,
graphs, and deciding what steps to take next.
Sophisticated quality control commands are provided that can be used to
calibrate measurement and pipetting devices, as well as to calculate their
accuracy and determine whether their variance is within specification.
Various planning and optimization algorithms are used at various stages in the
planning process. We use a partially ordered planner for the prerequisite and
post-condition actions, so that the user can rearrange them when permissible.
For variables and action orderings which the user leaves unspecified,
a depth-first tree search is currently performed, though we're considering
changing this to constraint-based search. Labware transport is determined by
a shorted path graph search, where the graph nodes are labware sites, and edges
represent the ways an agent can move the labware between two sites. Several
different algorithms are used to optimize pipetting instructions, depending on
their characteristics: a full A* search is performed for pipetting actions
involving less than 10 well, a best-first search with limited backtracking is
performed for 50 wells or less, and a greedy search is performed for larger
numbers of well.
Software components currently in development
This section concerns components that are still under development.
The software has several components. There is a command line program that
allows for all functionality to be managed from the command line and automated
by others programs. The *Manager* is a server that can be accessed through
a web interface, a network API, or the command line. The *Relay* components
interface between the *Manager* and the target agents (technicians, robots, and
stand-alone devices), and they too can be accessed through a web interface,
a network API, or the command line.
UI for interactive planning and execution
A web application runs on the server which allows for interactively planning
the execution of a generic protocol. At each step of the planning process, the
application displays the current plan, requests missing data, and allows the
user to make modifications. Once planning is complete, execution can begin.
During execution, the application displays the current status along with any data,
graphs, warnings and errors.
In addition to running user-created protocols, the software includes
several specialized applications available through the web interface.
- A demo application for "drawing" on a plate using various concentrations of a dye and diluent
- Applications for constructing titration and dilutions series
- A quality control application for running quality control checks.
Extending the software
Adding your own: web apps, devices, commands, robots
A lab may wish to extend the software in order to better fit their
requirements by adding new application, devices, commands, or robots.
Since the server provides a network API that communicates via JSON,
a programmer is completely free to design a new web application in whatever
way he's most comfortable. For example, an HTML page could be added to the
to generate a new protocol and send it to the server for validation and
Adding new commands
The software supports various kinds of commands, each of which are created
First of all there are *tasks*, which are specified in the system configuration
file. Tasks are merely command names that require the user to select a more
concrete method for achieving the task: for example, a task named `ensureWellMixed`
might list both the `shake` or `centrifuge` commands as potential candidates
for the user to choose from.
Then there are *procedures*, which can be defined in the protocol or in
separate text files. They are basically just a list of commands, making it
easy for users to group together steps that they may use repeatedly.
To add a new device, a programmer will derive a new Java `Device` class
and then reference it from the system configuration file. The `.class` file
will need to be placed in the software's search path, done in the standard
way for Java programs.