5 Simple Protocols

Roboliq was developed to help automate protocols on liquid handling robots, especially for lab experiments in molecular biology. This chapter will explain the four properties in simple protocols and how to write write them.

First consider this short example – it uses Roboliq version “v1”; it defines a Plate named sourcePlate; and it instructs us to shake the plate:

roboliq: v1
description: Shake a plate, just because we can
objects:
  sourcePlate:
    type: Plate
steps:
  1:
    command: shaker.shakePlate
    object: sourcePlate

The protocol consists of properties and values. A property is a name followed by a semicolon and then a value. In the above example, we see the following properties and values:

  1. The first property is roboliq, and it has a string value of v1 which indicates we’re using Roboliq version 1.

  2. The second property is description, whose value is also a text string.

  3. The third property is objects, which defines the materials we’ll use in the protocol. In contrast to the previous properties, the value starts on the next line and is indented by two spaces. This means that the value of objects is another set of properties: sourcePlate is the name of a material whose type property is set to Plate.

  4. The forth property is steps, which defines the steps to be performed. Its value is usually a numbered set of steps, and each numbered step is assigned properties as well: in this case, step 1 has the properties command: shaker.shakePlate and object: sourcePlate which tell Roboliq to shake the plate named sourcePlate.

Most of your protocols will have those four basic properties, and perhaps additional properties as well.

Next we will describe the objects and steps properties in more detail.

5.1 Objects

In order to add more objects, just give them a name and assign them the appropriate properties. Here we extend objects to include another plate for mixing named mixPlate:

objects:
  sourcePlate:
    type: Plate
  mixPlate:
    type: Plate

Objects are the things that can be used in the protocol’s steps, including labware, liquids, and equipment. Each object requires a type property (e.g. Plate in the example above) – the two most common types used in protocols are:

  • Plate: for defining labware, including tubes and troughs.
  • Liquid: for defining liquids.

A complete list of types can be found in the Commands & Types documentation, but most of them are only used in robot configurations rather than in protocols.

In addition to the type property, object have other properties as well (also available in the type documentation), and all objects have an optional description property that you can use to add your own notes about the object. Here are examples of the two main object types to indicate that a liquid named specialMix is in all wells on plate1:

objects:
  plate1:
    type: Plate
    description: Plate to be used for initial mixing
    model: ourlab.roboto.model.96microwell
    location: ourlab.roboto.P1
  specialMix:
    type: Liquid
    description: Our special mad-scientist mix
    wells: plate1(all)

5.2 Steps

A step is either a command or a numbered list of sub-steps, and a protocol’s steps property specifies the steps that should be taken during the protocol. Here is an example with two numbered steps in which a plate is sealed and shaken:

steps:
  1:
    command: sealer.sealPlate
    object: plate1
  2:
    command: shaker.shakePlate
    object: plate1

A command is indicated by a command property, such as the commands sealer.sealPlate and shaker.shakePlate above. Besides the command property, you will need to specify additional properties to tell the command exactly what to do. In the above example, the line object: plate1 tells the command to act on plate1.

Command names have two parts separated by a period. First is the command category, which contains related commands. Second is the actual command name. Roboliq’s standard commands are listed in the Command documentation, and Evoware’s special commands are listed in the Evoware Command documentation.

Steps can also be given a description property that let’s you explanation what’s happening for someone else who reads the protocol (or for yourself later after you’ve forgotten). Step can also be given a comment property, which is intended to be used as programmer comments that aren’t of interest to others.

Here is an example that contains nested steps, descriptions and commands - it is the same as the previous example, but applied to two plates:

steps:
  1:
    description: "Handle plate1"
    1:
      command: sealer.sealPlate
      object: plate1
    2:
      command: shaker.shakePlate
      object: plate1
  2:
    description: "Handle plate2"
    1:
      command: sealer.sealPlate
      object: plate2
    2:
      command: shaker.shakePlate
      object: plate2

5.3 Conclusion

Simple protocols can be writen using four properties: roboliq, description, objects, and steps. The roboliq property indicates the version of Roboliq, and description lets you document what the protocol does. In objects you specify the labware and liquids used in the protocol. And in steps you create a list of numbered commands; the steps can be nested and documented however you prefer. You can find documentation for the objects and commands in the Commands & Types documentation.