Autoprotocol Standard Changes

ASC-032 - Liquid Handle

Title

New instruction: liquid_handle

Authorship

Yang Choo yangchoo@transcriptic.com

Peter Lee peter@transcriptic.com

Motivation

The movement of liquids between wells is essential to biological studies. More parameters are desirable to allow specificity in transferring liquid handling protocols. Generalizing liquid handling allows for transferring intent while allowing for the use of different liquid handling modalities.

Proposal

We propose the liquid_handle instruction as a framework to allow for more control over liquid handling parameters and to express a broad range of liquid handling operations. This framework also makes explicit many liquid handling assumptions which allows for increased reproducibility and transferability across devices and implementations.

The liquid_handle operation is based around transporting a volume of liquid in and out of a location. Each operation is a locations sequence of location with transports sequences specifying the list of volumes to be transported in or out of the location. The position of device components may reset between elements of locations.

Many parameters are available for specification, but most are not required. For optional parameters without defaults, vendor specific defaults should be applied. Care should be taken as unspecified parameters suggest experimental pliability.

Transports within the same locations use the same consumables (i.e. tips in the case of air_displacement liquid handling) and with few exceptions, consumables will be swapped between liquid_handle instructions.

{
  "op": "liquid_handle",
  "locations": [
    {        
      "location": aliquot,
      "transports": [
        {
          /* 
             * Intended volume to be transferred to target location,
           * positive for adding volume to location,
           * optional, default: "0:microliter"
           */
          "volume": volume,
          /* 
           * Volume which pump will physically move,
           * if specified, will override any "volume" calibrations,
           * positive for adding volume to location, 
           * optional
           */
          "pump_override_volume": volume,
          /* Volume speed, optional */
          "flowrate": {
            "target": flowrate,  // Optional
            "initial": flowrate, // Optional
            "cutoff": flowrate,   // Optional
            "acceleration": volumeAcceleration, // Optional
            "deceleration": volumeAcceleration  // Optional
          },
          /* time after transport, optional, default: "0:second" */
          "delay_time": time,
          /* 
           * additional mode specific params, optional,
           * air_displacement mode parameters follow 
           */
          "mode_params": {
            /* 
             * type of liquid used, optional, either "air" or "default"
             * are currently specified. This params affects flowrate as
             * well as volume tracking
             */
            "liquid_class": Enum("air", "default"),
            /* 
             * dictionary of tip position parameters, optional,
             * `tip_position` defines the position at the end of each
             * transport operation; tip position will be interpolated between
             * the last position and the end position of the next 
             * transport operation. If this is not desired, a "0:microliter"
             * transport can be appended with the desired tip position.
             */
            "tip_position": {
              /*
               * positive x-axis is defined as towards the center,
               * rightmost direction from center; offset as fraction of 
               * distance to well side, optional, default: 0
               */
              "position_x": {
                "position": float,
                "move_rate": {
                  "target": speed,
                  "acceleration": acceleration
                }
              },
              /*
               * positive y-axis is defined as towards the center,
               * topmost direction from center; offset as fraction of 
               * distance to well top, optional, default: 0
               */
              "position_y": {
                "position": float,
                "move_rate": {
                  "target": speed,
                  "acceleration": acceleration
                }
              },
              "position_z": {
                /* 
                 * positive z-axis is defined as towards well opening 
                 * (from bottom), offset from z_reference, optional, 
                 * default dependent on reference
                 */
                "offset": distance,
                "move_rate": {
                  "target": speed,
                  "acceleration": acceleration
                },
                /* 
                 * reference for z_offset, optional, default: "well_bottom"
                 * `preceding_position` will only change position_z by the 
                * specified offset, an array that begins with 
                * `preceding_position` is invalid
                 */
                "reference": Enum("well_top", "well_bottom", "liquid_surface"
                  "preceding_position"),
                /* 
                 * method of "liquid_surface" detection, required if set
                 */
                "detection": {
                  "method": Enum("tracked", "pressure", "capacitance"),
                  /* 
                   * threshold for detection, optional, 
                   * pressure: pascal, capacitance: farad
                   */
                  "threshold": unit,
                  /* time filtering for threshold */ 
                  "duration": time,
                  /*
                   * fallback position_z can be set if detection fails.
                   * Offset from the original z_position is overridden.
                   */
                  "fallback": position_z
                }
              }
            }
          }
        }
      ],
     /* 
      * temperature to incubate the container of the "location",
      * optional
      */
      "temperature": temperature,
    }
  ],
  /* 
   * Mode used for liquid handling, optional, only "air_displacement" is 
   * currently specified, default "air_displacement"
   */
  "mode": "air_displacement",
  /* 
   * additional mode specific params applied to the `objects`
   * sequence, optional, air_displacement mode parameters follow 
   */
  "mode_params": {
    /* tip type to use, device and vendor specific, optional */
    "tip_type": string
  },
  /* 
   * Shape of liquid handle operation, optional, default:
   *    {
   *      "rows": 1,
   *      "columns": 1,
   *      "format": "SBS96"
   *    }   
   */
  "shape": {
    "rows": integer,
    "columns": integer,
    "format": Enum("SBS96", "SBS384")
  }
}

Example 1: Simple transfer from plate1/0 to plate1/1

{
  "locations": [
    {
      "transports": [
        {
          "mode_params": {
            "tip_position": {
              "position_z": {
                "reference": "well_bottom",
                "offset": "0.001:meter"
              }
            }
          }
        },
        {
          "volume": "-10.0:microliter",
          "mode_params": {
            "tip_position": {
              "position_z": {
                "detection": {
                  "method": "tracked"
                },
                "reference": "liquid_surface",
                "offset": "-1.0:millimeter"
              }
            }
          }
        }
      ],
      "location": "plate1/0"
    },
    {
      "transports": [
        {
          "mode_params": {
            "tip_position": {
              "position_z": {
                "reference": "well_bottom",
                "offset": "0.001:meter"
              }
            }
          }
        },
        {
          "volume": "10.0:microliter",
          "mode_params": {
            "tip_position": {
              "position_z": {
                "detection": {
                  "method": "tracked"
                },
                "reference": "liquid_surface",
                "offset": "-1.0:millimeter"
              }
            }
          }
        }
      ],
      "location": "plate1/1"
    }
  ],
  "op": "liquid_handle"
}

Compatibility

This ASC specifies a new instruction.

ASC-031 - Container Sets

Title

Container Sets

Authorship

Peter Lee peter@transcriptic.com

Yang Choo yangchoo@transcriptic.com

Rhys Ormond ormondr@transcriptic.com

Motivation

In biology, the same operations are often done to sets of containers. We would like to formalize this with the introduction of sets. The first implementation of sets would allow plates that hold the same things to be grouped into their own sets. These sets would indicate that plates could be treated similarly and be ordered in accordance with the executor.

Future implementations could allow sets to be used throughout as source or destinations in an aliquot. Setting an aliquot to use a set + well reference would indicate that the instruction should be performed on each container in the set at the given well reference. This could help to demonstrate the parallelism of experiments as they are run on several plates.

Notably, sets are not ordered and plates in sets are unique (the same plate cannot be in a set more than once).

Proposal

We propose to add a “sets” top-level field to the definition of an Autoprotocol run, which is an dict of string set names and their corresponding dict of refs.

E.g.

{
  "refs": {
    "foo": { "id": "ct1", "discard": true },
    "bar": { "id": "ct2", "discard": true },
    "baz": { "id": "ct3", "discard": true }
  },
  "sets": {
    "cells": ["foo", "bar"],
    "enzyme": ["bar", "baz"],
    "read": ["foo", "baz"]
  }
}

The refs in sets must be in the refs section.

Execution

Grouping refs into a set indicates that the refs can be treated similarly, stacked, etc. If refs are used in Autoprotocol instructions, the order of refs may be constrained by their order in the Autoprotocol instruction. The vendor should respect Autoprotocol instruction order, but use refs belonging to sets in parallel instructions in whatever way vendors have optimized.

Compatibility

Tools that consume autoprotocol but do not recognize the “sets” top-level field are free to ignore it, if it is present.

The “sets” top-level field is optional, so any tools which generate autoprotocol will continue to be valid without modification.

ASC-030 - Change object field of measure_mass instruction

Title

Change object field of measure_mass instruction

Authorship

Yang Choo yang@transcriptic.com

Varun Kanwar varun@transcriptic.com

Motivation

Measuring a list of containers with a weighing scale is not well-defined and doesn’t fit into the usual modality of a scale. An instruction should be made as modular and encapsulated as possible, and reflect a single operation. Specifically for this case, if we interpret a list of container measurements as measuring each container sequentially, that makes it hard and ambiguous to handle any failure that happens within that sequence of measurements.

It would make more sense and simplify things if we instead just measured the mass of a single container and return a single dataref associated with the container.

Proposal

{
    "op": "measure_mass",
    "object": ["container"], -> "object": container,
    "dataref": string
}

Execution

The new instruction now looks like:

{
    "op": "measure_mass",
    "object": container,
    "dataref": string
}

The expected output is up to the vendor to decide, but should ideally include the mean and standard deviation of the measured mass.

Compatibility

This ASC changes the acceptable values for an existing field.

This is NOT backwards compatible (however, from a search through the database, all the existing object fields only contain a single container except for the initial test runs).

To make it backwards compatible, we could keep the same format, but enforce a check that the length of the list has to be one. We’ll prefer not to however, since it’ll be much clearer at that point if we define the input-type to not be a list, but a single container.

ASC-029 - Add dispense_speed, nozzle_position, and pre_dispense to the dispense instruction

Title

Add dispense_speed, nozzle_position, and pre_dispense to the dispense instruction

Authorship

Jim Culver jim@transcriptic.com

Motivation

A number of different parameters can affect the accuracy of reagent dispensing, including the dispense speed, nozzle position, and pre-dispense volume. Commercial reagent dispensers are commonly designed to control these parameters, and many protocols rely on tuning these parameters to optimize liquid handling. Since controlling these parameters is important for a number of applications, the dispense instruction should be updated so that they can be explicitly specified.

Proposal

The dispense instruction should accept the additional optional parameters of dispense_speed, nozzle_position, and pre_dispense.

dispense_speed should represent the speed of the peristaltic pump mechanism in units of rpm. The set of allowable values for dispense_speed will depend on the available hardware, and will therefore be vendor specific.

nozzle_position should represent the x, y, and z position of the nozzle with respect to the bottom center of the well. This should be specified as a dictionary of key/value pairs, where all values are given as lengths, and the keys are as follows: position_x, position_y, and position_z. The set of allowable values for position_x, position_y, and position_z will depend on the available hardware, and will therefore be vendor specific.

pre_dispense should represent the volume that should be automatically dispensed and discarded prior to the start of the dispense operation. This is distinct from the priming operation that is typically executed whenever the reagent source is switched. pre_dispense should be specified as a volume and should be an integer multiple of the step_size. The set of allowable values for pre_dispense will depend on the available hardware, and will therefore be vendor specific.

  {
    "op": "dispense",
    "object": container,
    "reagent": reagent,
    "columns": [
      {"column": column, "volume": volume}
    ],
    /* optional */
    "dispense_speed": rpm,
    /* optional */
    "nozzle_position": {
        "position_x": length,
        "position_y": length,
        "position_z": length
    },
    /* optional */
    "pre_dispense": volume,
    /* optional */
    "step_size": volume
    }
  }

Execution

These parameters specify how the given dispense instruction should be executed. There may be vendor-specific and/or device-specific limitations on what parameters can be used.

Compatibility

This ASC specifies new fields for an existing instruction. Dispense instructions without these optional parameters will continue to be executed using vendor-specified defaults.

ASC-028 - Add shaking_params and target_temperature to Incubate instruction

Title

Add shaking_params and target_temperature to Incubate instruction

Authorship

Vanessa Biggers vanessa@transcriptic.com

Motivation

Add optional shaking_params and target_temperature to the Incubate instruction to allow setting a frequency, path of movement, and target temperature to an incubation. This allows for use of devices such as Thermoshakes, where shaking patterns and temperatures can be designated. Many protocols require specific shaking frequencies at specified temperatures which can be achieved through this autoprotocol standard change.

Proposal

The incubate instruction should take additional, optional parameters "shaking_params" and "target_temperature" to specify optional frequency, path of object movement and temperature of an incubation.

{
  "op": "incubate",
  "object": container,
  "where": string,
  "duration": duration,
  "shaking": bool,
  "co2_percent": decimal,  //optional, default: 0
  "target_temperature" : temperature, //optional
   /* optional/*
  "shaking_params": {
    "path": string, //default cw_orbital
    "frequency": frequency // required if “path” specified
    "amplitude": length // default 2mm
  }
}

The combination of temperature, frequency, path of shake, and CO2 levels available will be determined by the vendor.

Execution

Not all vendors/devices will be able to support the additional optional parameters.

To access a thermoshake device, both a valid “path” and a “frequency” must be included. Current supported values in shaking_params and target_temperature are below:

Parameter Type Capability
target_temperature temperature 4 - 70 degrees C
path string “cw_orbital” (clockwise orbital), “ccw_orbital”(counterclockwise orbital), “portrait_linear” (portrait linear), “landscape_linear” (landscape linear), “cw_diamond” (clockwise diamond), “ccw_diamond” (counterclockwise diamond)
amplitude string 2mm
frequency frequency 0, 100 - 2000 rpm

The “where” parameter references the location of the incubate instruction and not the temperature of the device (if available). For example, a thermoshake device could be located at “ambient” temperature but the device temperature could be set to shaking with 25 degrees C with the following code:

{
  "op": "incubate",
  "object": "my_plate",
  "where": "ambient",
  "duration": "10:minute",
  "shaking": True,
  "target_temperature": "25:celsius",
  "shaking_params": {
    "path": "cw_orbital"  ,
    "frequency": "700:rpm"
  } 
}

Compatibility

This ASC specifies new fields for existing instructions. Incubate instructions without these optional parameters will duplicate the previous behavior.

Addendum 1: Clarification on shaking_params path

“portrait_linear”: This refers to a linear shaking path along the width (the shorter side) of the plate, i.e. from A1 to B1

“landscape_linear”: This refers to a linear shaking path along the length (the longer side) of the plate, i.e. from A1 to A2

ASC-027 - Add step_size and reagent_source to the dispense instruction

Title

Add step_size and reagent_source to the dispense instruction

Authorship

Jim Culver jim@transcriptic.com

Motivation

For dispense operations, the volume that may be dispensed is often limited to certain values, depending on the hardware being used. One such limit is when the dispensed volume must be an integer multiple of some fundamental volume step size. This type of limitation is common among reagent dispensers that utilize a peristaltic pump mechanism, because these dispensers must transfer liquid in discrete steps. Adding step_size as an optional parameter to the dispense instruction will therefore allow a protocol to restrict which devices can be used to execute a given dispense operation.

While dispense instructions commonly use a single resource as the reagent source, it is sometimes desirable to dispense a mixture of different reagents that has been freshly prepared during the run. Adding reagent_source as an optional parameter will account for this situation by making it possible to specify a well that can be used as the dispense source.

Proposal

The dispense instruction should accept the additional optional parameters of step_size and reagent_source.

step_size must be a string representation of a volume unit, and will denote that the instruction must be executed on a device with a matching step_size. The list of allowable values for step_size will depend on the available hardware, and so it will be vendor specific.

reagent_source must be a well containing the reagent to be dispensed. This is an optional parameter, so if not specified, then the dispense instruction will be executed using vendor-supplied reagents matching the name or resource id specified by the reagent or resource_id parameters (as it has in the past). If this parameter is specified, however, then the dispense instruction will be executed using the specified well as the reagent source. One and only one of [reagent, resource_id, reagent_source] must be specified.

  {
    "op": "dispense",
    "object": container,
    /* optional */
    "reagent": reagent,
    /* optional */
    "resource_id": string,
    /* optional */
    "reagent_source": well,
    "columns": [
      {"column": column, "volume": volume}
    ],
    /* optional */
    "step_size": volume
    }
  }

Execution

The step_size parameter specifies what type of hardware can be used to execute the given dispense instruction. The instruction should only be carried out using reagent dispensers that are capable of using this step_size. Note that the volume being dispensed into each column must be an integer multiple of step_size.

The reagent_source parameter specifies what well should be used as the reagent source for the given dispense instruction. There may be vendor-specific and/or device-specific limitations on what container types may be used as the reagent_source.

Compatibility

This ASC specifies new fields for an existing instruction. Dispense instructions without the optional step_size parameter will continue to be executed using the device that corresponds to the vendor specified default. Dispense instructions without the reagent_source parameter will continue to be executed using the vendor-supplied reagent, as specified by the reagent or resource_id parameters.

ASC-026 - Add optional parameters to the fluorescence, luminescence, and absorbance instructions

Title

Add optional parameters to the fluorescence, luminescence, and absorbance instructions

Authorship

Vanessa Biggers vanessa@transcriptic.com

Motivation

Addition of the following parameters to the fluorescence, luminescence, and absorbance instructions will enable the level specification often needed to capture the full intent of a measurement. For example, many spectrophotometers have both top and bottom detection modes for fluorescence measurements, using of an opaque plate and a “top” detection mode can reduce background while increasing sensitivity. Additionally, settle_time, integration_time, and lag_time parameters are often optimized for a specific assays and necessary to maintain reproducibility.

Proposed parameters to add:

Fluorescence:

"detection_mode": str, ["top", "bottom"], // optional, defaults to vendor
"position_z": {
"manual": length
"calculated_from _wells": [Well] //
},
"settle_time": time, default 0 ms
"lag_time": time, default 0 ms
"integration_time": time, default 20 ms

Luminescence:

"integration_time": time, default 1s
"settle_time": time, default 0 ms

Absorbance:

"settle_time": time, default 0 ms

Proposal

The fluorescence instruction should accept the additional optional parameters detection_mode, position_z, settle_time, integration_time, and lag_time:

{
"op": "fluorescence",
"object": container,
"wells": [
Well
],
"excitation": length,
"emission": length,
"num_flashes": integer,
"dataref": string,
"temperature": temperature,
"incubate_before": {
"duration": time,
              "shaking": {
                        "amplitude": length,
                        "orbital": bool
              },
            "gain": float,
/*optional, defaults to vendor*/
            "detection_mode": str, ["top", "bottom"]
/*"position_z" is a vendor dependent parameter available when "top"
detection mode is enabled.  Vendor capabilities will determine if this
setting can be specified.  If setting a "position_z, only one of the
modes: "manual" or "calculate_from_well", can be set.*/
"position_z": {
"manual": length
                "calculated_from _wells": [well]
             },
            "settle_time": time, default 0 ms
            "lag_time": time, default 0 ms
            "integration_time": time, default 20 ms
  }

The absorbance instruction should accept the additional optional parameter settle_time:

{
"op": "absorbance",
        "object": container,
         "wells": [well],
         "wavelength": length,
         "num_flashes": integer,
         "dataref": string,
         // optionally:
"settle_time": time, default 0 ms
         "incubate_before": {
                   "duration": time,
                   "shaking": {
                     "amplitude": length,
                     "orbital": bool
                   }
}
}

The luminescence instruction should accept the additional optional parameter settle_time:

{
"op": "luminescence",
        "object": container,
         "wells": [well],
         "dataref": string,
         // optionally:
"integration_time": time, default 1 s,
"settle_time": time, default 0 ms,
         "incubate_before": {
                   "duration": time,
                   "shaking": {
                     "amplitude": length,
                     "orbital": bool
                   }
}
}

Execution

Vendor specific limitations will determine the availability, and default values of these parameters.

Many plate readers for fluorescence measurements only offer “top” reading detection modes. Plate readers which offer both “top” and “bottom”, often will default to “top” mode, however, vendor specifications and defaults should be consulted when using “automatic_optics”. If specifying calculate_from_wells: [Wells], for position_z, within the Fluorescence instruction, the Wells must be within the “object” container.

position_z is the distance from the optics (lens of the measurement head) to the surface of the plate transport. It can be manually entered, eg. 20,000 um, or calculated from a list of Wells, permitting vendor capabilities. If a list of Wells is specified, the device automatically calculates the optimal position_z (the position_z at which the highest obtained signal intensity is measured) for each of the specified wells and calculates the average position_z to be applied to all wells in the measurement.

settle_time - time before the start of a measurement, lag_time - time between flashes and the start of the signal integration, integration_time - duration of the signal recording, per Well

Not all vendors/devices will be able to support the additional optional parameters.

Compatibility

This ASC specifies a new field for an existing instruction. Fluorescence instructions without this optional parameter will read plates in the vendor specified default manner previously used.

ASC-025 - Image Plate - Redacted

ASC-024 - Time Constraints

Title

Time Constraints

Authorship

Jeremy Apthorp jeremy@transcriptic.com

Motivation

Many protocols involve time-sensitive steps, particularly as they relate to light or temperature-sensitive reagents. A successful execution of such a protocol relies not only on the specific actions taken, but additionally on the timeliness of those actions.

Proposal

We propose to add a “time_constraints” top-level field to the definition of an Autoprotocol run, which is an array of constraint objects. Each constraint object specifies: * a “from” timing point, * a “to” timing point, and * an upper bound for the time between “from” and “to”.

A timing point is one of: * the start of an instruction, * the end of an instruction, * the time at which a container is removed from storage, or * the time at which a container is returned to storage.

e.g.

{
  "refs": {
    "foo": { "id": "ct123534", "store": { ... } }
  },
  "instructions": [
    { "op": "pipette", ... },
    { "op": "incubate", ... }
  ],
  "time_constraints": [
    {
      "from": { "ref_start": "foo" },
      "to": { "ref_end": "foo" },[a][b][c][d]
      "less_than": "5:minute"
    },
    {
      "from": { "instruction_start": 0 },
      "to": { "instruction_end": 1 },[e][f][g][h]
      "less_than": "3:minute"
    }
  ]
}

An instruction_start time point is measured after all containers required by an instruction arrive at a device, but before the operation itself begins.

An instruction_end time point is measured as soon as the operation completes, before any containers are considered for transport to their next destination.

A ref_start time point is measured at the time a container leaves its storage environment (freezer, fridge, incubator or supply for “new” containers).

A ref_end time point is measured at the time a container enters its storage environment (freezer, fridge, or incubator) or is discarded.

There are no restrictions on the kinds of time points used in “from” and “to”. That is, it is legal to have a constraint between “ref_start” and “instruction_end” (for example).

Execution

When executing a run with time constraints, all time constraints must be met. For any given constraint, if the timestamp of the “to” timing point minus the timestamp of the “from” timing point exceeds the upper bound, the constraint is not met.

\[ t_{to} – t_{from} ≤ UB \]

When planning the execution of a protocol, given predictions of the duration of each operation and a list of available devices, a scheduler can determine a feasible execution plan (if one exists). This is an instance of the resource-constrained project scheduling problem, which is well-studied in the literature.

Compatibility

Tools that consume autoprotocol but do not recognize the “time_constraints” top-level field are free to ignore it, if it is present. An execution may incidentally comply with such constraints, even if the executor does not explicitly make any special effort to do so.

The “time_constraints” top-level field is optional, so any tools which generate autoprotocol will continue to be valid without modification.

When no constraint is specified between timing points, an executor is free to wait for an unlimited amount of time in between timing points, which fact is unchanged by the introduction of optional constraints.

ASC-023 - Add cycles parameter to illumina_sequence

Title

Add cycles parameter to illumina_sequence

Authorship

Meenakshi Doma meenakshidoma@transcriptic.com

Conny Scheitz conny@transcriptic.com

Motivation

Allow for choice of number of sequencing cycles of read 1, read 2 sequencing primers and the index 1 and index 2 reads for multiplexed libraries.

Proposal

The number of sequencing cycles determine the sequencing read length. Add cycles parameter to Illumina_sequence instruction for specifying read length of read 1, read 2, index 1 and index 2 primers.

{
  "op": "illumina_sequence",
  "flowcell": "SR" | "PE",
  "lanes": [
    {
       "object": aliquot,
       "library_concentration": decimal,  // ng/uL,
    }
  ]
  "sequencer": "miseq" | "hiseq" | "nextseq",
  "mode": "rapid" | "mid"| "high",
  "index": "single" | "dual"| "none",
  "cycles": //optional, vendor default  
{
   "read_1": integer, required if cycles is set
   "read_2": integer, optional,
   "index_1": integer, optional, default to 0
   "index_2": integer, optional, default to 0
}
  "library_size": integer,  // in bp
  "dataref": string
}

index: The index sequences are unique identifiers added to DNA samples during library preparation that allows multiplexing of libraries for sequencing on Illumina SR or PE flowcells. single index sequencing refers to a separate read called the index 1 (i7) read that is done after read 1. When libraries are dual indexed, the sequencing run includes 2 additional reads called the Index 1 (i7) read and Index 2 (i5) read. If there is no multiplexing of libraries, then the none option applies. The index sequences are specific to library prep kits and compatible sequencers specific to the vendor.

cycles: cycles refers to the read length or number of sequenced bases. Each bp is sequenced one cycle at a time. These cycles can be split into two reads, providing paired reads of the same DNA fragment. The read_1 and read_2 cycles refer to the sequencing cycles of the read 1 and read 2 primers. Single read (SR) flowcell allows only read_1 cycles and paired end (PE) flowcell allows both read_1 and read_2 sequencing cycles. The index_1and index_2 cycles can go to a maximum number of 8. All read_1 and read_2 sequencing must contain more than 25 cycles to generate FASTQ files. Depending on the available instruments, their compatible reagents and the type of flowcell (SR vs PE), upto a maximum of 300-600 cycles of sequence data can be obtained as shown below. The cycles required to read the index reads do not count against this maximum number. Most common applications of NGS for RNA/DNA use 50, 75, 100, 150 cycles for both single read and paired end read flowcells.

The table below lists the maximum cycle numbers specified by currently available kits for Illumina sequencers.

cycles miseq nextseq hiseq
Read 1 and Read 2 600 300 500
Index 1 8 8 8
Index 2 8 8 8

cycles is a optional vendor-specific parameter that is specific for the various sequencers and their compatible versions of cluster kits, SBS reagents and sequencer control software for a specific flow cell. cyclesparameter can be customized if customers choose to use the full flowcell during a sequencing run. Please check vendor’s documentation for availability of cycles number specific to each sequencer and associated reagents and software. The default for the cycles in the Illumina_seq instruction will set to the vendor’s availability of instrument and default flowcell choice.

Compatibility

This ASC appends new optional parameter to Illumina_sequence instruction.

ASC-022 - Illumina Sequence Instruction

Title

Illumina Sequence

Authorship

Meenakshi Doma meenakshidoma@transcriptic.com

Conny Scheitz conny@transcriptic.com

Motivation

Next generation sequencing is a set of modern techniques to determine the DNA or transcriptome sequence of organisms. Here we propose an instruction for Illumina Sequencing.

Proposal

Samples will be presented in aliquots and loaded on the indicated lane on a flowcell. Currently, commercial sequencers available are miseq, nextseq and hiseq and their availability is vendor specific. Data will be named according to dataref and presented on a S3 server for use with other 3rd party tools.

{
  "op": "illumina_sequence",
  "flowcell": "SR" | "PE",
  "lanes": [
    {
       "object": aliquot,
       "library_concentration": decimal,  // ng/uL,
    }
  ]
  "sequencer": "miseq" | "hiseq" | "nextseq",
  "mode": "rapid" | "mid"| "high",
  "index": "single" | "dual"| "none",
  "library_size": integer,  // in bp
  "dataref": string
}

flowcell: Single-read flowcell (SR) or Paired-end flowcell (PE). A single flowcell can be either single-read or paired end read. Applies to all Illumina sequencers. Both single-end read and paired-end read use standard sequencing primers compatible with Illumina instruments.

lanes: lanes is a group where each item corresponds to a lane run on the sequencer. Each lane has an object which is the aliquot to load and library_concentration which is the concentration of the object in ng/ul. The number of lanes available per sequencing run depends on the sequencer chosen. For miseq lane maximum is 1, for hiseq lane maximum is 8, for nextseq lane maximum is 4 .

mode: The mode parameter is sequencer and vendor specific and details will be provided by each vendor. Generally, high mode generates the maximum amount of data at normal speed, rapid has faster execution but fewer reads. miseq has a single mode of high output. hiseq has rapid and high output modes. nextseq has mid and high output modes.

library_size: Common library sizes are 200-900. Anything higher than 1000 will give sub-optimal clustering efficiency on Illumina sequencers. This parameter depends on the library preparation method and sequencer chosen.

Compatibility

This ASC only specifies new instructions.

ASC-021 - Modify autopick instruction to allow for batching autopick analysis and allow for a list of wells to be used as a source

Title

Modify autopick instruction to allow for batching autopick analysis and allow for a list of wells to be used as a source

Authorship

Peter Lee peter@transcriptic.com

Ian O’Hara ian@transcriptic.com

Cornelia Scheitz conny@transcriptic.com

Motivation

Analysis of several autopicks from the same container share many analysis steps. Restructuring autopick enables it to be faster by using a single analysis step.

Allowing the from parameter to be a list of wells instead of a single well allows picking colonies across different wells (e.g. to take advantage of varying spread densities).

The min_colony_count parameter was ill-defined and will be deprecated in favor of a min_abort parameter. The run will be cancelled if the number of colonies detected in the aggregate from well(s) of the associated pick group is less than the parameter min_abort.

Proposal

Change autopick to have a list of pick groups instead of a single pick. All pick groups in the list will be analyzed at the same time and data for each pick group will be reported under the same dataref.

Allow each pick group to specify multiple source wells across which colonies are ranked and picked.

Each well in each from list of wells within a single autopick instruction must be from the same container.

Addition of the min_abort parameter to denote total number of colonies that must be detected in the aggregate list of from wells to avoid aborting the entire run.

Deprecation of min_colony_count parameter to reduce ambiguity of the instruction.

{
  "op": "autopick",
  "dataref": string,
  "criteria": {} // optional, default {}
  "groups": [
    {
    "from": [well],
    "to": [well],
    "min_abort": int,   // per aggregated from well(s), optional, default: 0
    },  // all wells in the "from" parameters must be from the same container
  ]
}

Examples:

Example 1: Picking from one source to multiple destination wells (replicating previous autopick instruction).

{
  "op": "autopick",
  "dataref": "pick_from_one”,
  "groups": [
    {
    "from": ["src_plate/A1"],
    "to": ["dest_plate_1/A1", "dest_plate_1/A2"]
    }
  ]
}

Example 2: Picking from multiple source wells to multiple destination wells (pick colonies across all sources) using the same source plate but multiple destination plates.

{
  "op": "autopick",
  "dataref": "pick_from_one”,
  "groups": [
    {
    "from": ["src_plate/A1", "src_plate/A2", "src_plate/A3"],
    "to": ["dest_plate_1/A1", "dest_plate_1/A2"],
    "min_abort": 2
    },
    {
    "from": ["src_plate/A4", "src_plate/A5", "src_plate/A6"],
    "to": ["dest_plate_2/A3", "dest_plate_2/A4", "dest_plate_2/A5", 
 "dest_plate_2/A6", "dest_plate_2/A7", "dest_plate_2/A8"]
    }
  ]
}

Compatibility

This change is not backward compatible with the previous autopick instruction.

Previous autopick instructions should be updated to nest picks under the groups parameter of autopick. The from parameter should be updated to take a list of wells as opposed to a single well. See example 1 for more information on how to convert a previous autopick instruction to be in accordance with this change.

The parameter min_colony_count: int, // optional, default: 1 will be supported until March 31st 2016 - afterwards it will be ignored. Before, March 31st 2016, if a group’s aggregated from well(s) in the instruction contains fewer colonies than specified in this parameter there will be 0 colonies picked from these well(s), however the run will continue.

ASC-020 - Add flow_direction and spin_direction to Spin Instruction

Title

Add flow_direction and spin_direction parameters to spin

Authorship

Conny Scheitz conny@transcriptic.com

Yang Choo yangchoo@transcriptic.com

Peter Lee peter@transcriptic.com

Motivation

Allow for emptying a container by spinning it with the container opening facing outward.

Proposal

We introduce the properties flow_direction and spin_direction to the Spin instruction to allow spinning a container with the opening facing outwards so that well contents can be emptied simultaneously.

Proposed new optional parameters:

flow_direction - specifies the direction that contents will tend towards with respect to the container. If unspecified flow_direction defaults to inward.

      inward - contents are spun into the container

      outward - contents are spun out of a container

spin_direction - a list of cw, ccw. Each element in the spin_direction list, the container will be spun in the stated direction for the set acceleration and duration.

For clockwise(cw) and counterclockwise(ccw), the origin is defined at the top left corner of a container (for a plate that would correspond to well A1) (see inset figure). Axes follow the right hand rule with z-axis pointing out of a well. Movements in the positive direction along any of the axes are clockwise.

Flow Direction Diagram
Flow Direction Diagram

If spin_direction is unspecified and flow_direction is specified, spin_direction defaults to: “outward”: [“cw”,“ccw”] “inward”: [“cw”]

If both spin_direction and flow_direction are unspecified, spin_direction defaults to the original vendor specified spin_direction

{
  "op": "spin",
  "object": <container>,
  "acceleration": acceleration,
  "duration": time,
  "flow_direction": "inward" | "outward"  // optional, default: "inward"
  "spin_direction": [directions]  // optional, "cw" or "ccw",
                         "outward" default:["cw","ccw"],
                         "inward" default:["cw"]
}

spin_direction and flow_direction are vendor specific parameters that may not be available. Please check your vendor’s documentation for availability. The spin_direction and flow_direction parameters are optional. The default for the spin instruction flow_direction will be inward - meaning the well openings will face towards the centrifuge center, causing the liquid to be pushed towards the bottom of the wells using the centrifugal force. The default spin_direction for inward spin is set to cw or the vendor specified default.

Compatibility

This ASC appends new optional parameters with defaults to recapitulate existing behavior to an existing instruction and as such is fully backwards compatible.

ASC-019 - Add incubate_before and temperature to Spectrophotometry Instructions

Title

Add incubate_before and temperature to spectrophotometry instructions

Authorship

Peter Lee peter@transcriptic.com

Ross Trundy ross@transcriptic.com

Motivation

Addition of incubate_before and temperature parameters to spectrophotometry instructions allow for the possibility of recording spectrophotometric observations over a period of time by adding incubation for a duration with the option of shaking prior to reading a plate and setting temperature during the entire instruction recording. Amongst many additional functionalities, these parameters will enable the study of growth and enzyme kinetics, aid in resolving bubbles prior to reading, allow for readings at physiological temperatures, and permit storage for light-sensitive assays prior to reading.

Proposal

The spectrophotometry instruction groups fluorescence, absorbance and luminescence should accept the additional optional parameters of incubate_before and temperature.

/* dictionary of parameters governing conditions prior to reading */
`incubate_before` - object
  /* duration of incubation prior to reading */
  `duration` - time
/* shake parameters during `time` prior to read, optional */
`shaking` - object
`amplitude` - distance  
`orbital` - bool      // true for orbital, false for linear
/* temperature to heat plate environment during incubation and reading */
`temperature` - temperature

Vendor specific limitations may apply to the availability of these optional parameters.

[
  {
    "op": "absorbance",
    "object": container,
    "wells": [
      well
    ],
    "wavelength": length,
    "num_flashes": integer,
    "dataref": string,
    /* optional */
    "temperature": temperature,
    /* optional */
    "incubate_before": {
      /* required if `incubate_before` specified */
      "duration": time,
      /* optional */
      "shaking": {
        /* required if `shaking` specified */
        "amplitude": length,
        /* required if `shaking` specified */
        "orbital": bool
      }
    }
  },
  {
    "op": "fluorescence",
    "object": container,
    "wells": [
      well
    ],
    "excitation": length,
    "emission": length,
    "num_flashes": integer,
    "dataref": string,
    /* optional */
    "temperature": temperature,
    /* optional */
    "incubate_before": {
      /* required if `incubate_before` specified */
      "duration": time,
      /* optional */
      "shaking": {
        /* required if `shaking` specified */
        "amplitude": length,
        /* required if `shaking` specified */
        "orbital": bool
      }
    }
  },
  {
    "op": "luminescence",
    "object": container,
    "wells": [
      well
    ],
    "dataref": string,
    /* optional */
    "temperature": temperature,
    /* optional */
    "incubate_before": {
      /* required if `incubate_before` specified */
      "duration": time,
      /* optional */
      "shaking": {
        /* required if `shaking` specified */
        "amplitude": length,
        /* required if `shaking` specified */
        "orbital": bool
      }
    }
  }
]

Execution

All parameters of the instruction should be completed on a single device such that the time from incubate_before to reading the plate is minimized. Not all vendors/devices will be able to support the additional optional parameters.

Compatibility

This ASC specifies new fields for existing instructions. Spectrophotometry instructions without these optional parameters will read plates without shaking, heating, or delay - duplicating the previous behavior.

ASC-018 - Addition of gel_purify

Title

Addition of gel_purify

Authorship

Ben Miles ben@transcriptic.com

Motivation

Often in cloning it is necessary to separate a gel fragment from a PCR product or digestion product. This is typically done by first running a gel then extracting the band corresponding to the DNA fragment. This functionality is missing from Autoprotocol.

Proposal

The gel_purify instruction performs similar to the gel_separate instruction however takes an additional extract array. extract is an array of extraction groups, which may each have different sub parameters. elution_volume is the final volume that a returned solution of extracted DNA should be returned in. elution_buffer is the solution that the purified DNA should be returned in. lane is the gel lane from which DNA should extracted. band_size_range is the base pair size range from which the band should be extracted from it takes two arguments min_bp and max_bp. Finally each extraction group takes a destination well.

{
  "op": "gel_purify",
  "volume": volume,
  "objects": [wells],
  "matrix": gel,
  "ladder": ladder,
  "dataref": string,
  "extract": [{
    "elution_volume": volume,
    "elution_buffer": string "water" | "TE",
    "lane": int,
    "band_size_range": {
      "min_bp": int,
      "max_bp": int,
    },
    "destination": well
  }, 
  {...}]
}

Execution

When loading gel lanes they should be loaded sequentially concomitant with the sequence of wells provided to the gel_separate instruction. E.g Well A2, could be at index 0 of the WellGroup there should be loaded into lane 0. Well A1 could be at index 7 of the WellGroup therefore should be loaded into lane 7 of the gel.

The data returned by this instruction should both illustrate the size of fragments in the solution either by image, or numeric chromatogram. In addition it should illustrate the fragment collection, be that a annotation on the gel image or a gated region of the chromatogram

Vendor sets the max tolerable size range (max-min) for band extraction.

Gel separation, extraction and purification methods to be determined by vendor.

Compatibility

This is a new instruction and does not affect compatibility.

ASC-017 - Add measure_mass, measure_concentration and measure_volume instructions

Title

Add measure_mass, measure_concentration and measure_volume instructions

Authorship

Cornelia Scheitz conny@transcriptic.com

Motivation

To confirm or determine the properties of a sample, such as weight or volume a set of measure instructions can be used where the operation type determines the type of analysis for example measure_mass. measure_mass and measure_volume do not consume the sample. All concentration measurements (measure_concentration) such as for measurement DNA consume a vendor specific minimum amount of the sample - volume is indicating the amount of sample that will be used for the quantification. The accuracy of all results is vendor specific.

Proposal

{
    "op": "measure_mass",
    "object": ["container"],
    "dataref": string
},
{
    "op": "measure_concentration",
    "object": ["aliquot"],
    "volume": volume,   // default: "2:microliter"
    "dataref": string,
    "measurement": DNA | ssDNA | RNA | protein
},
{
    "op": "measure_volume",
    "object": ["aliquot"],
    "dataref": string
}

Execution

The dataref for measure_concentration contains a concentration in the form of X ng/µL in addition to a 260/280 ratio of type float. The dataref for measure_mass contains a mass in the form of X g. The dataref for measure_volume contains a volume in the form of X uL.

Compatibility

This ASC only specifies new instructions.

ASC-016 - Add gain to fluorescence instructions

Title

Add gain to fluorescence instructions

Authorship

Peter Lee peter@transcriptic.com

Motivation

The current fluorescence instruction is underspecified in terms of how and if signal is being amplified. Adding a gain parameter to the fluorescence instruction will allow for the ability to control for how signal from fluorescence emission is amplified.

This parameter will allow users to control the amount of signal amplification enabling the comparison of results between plates and over time.

Proposal

The fluorescence instruction should accept the additional optional parameter of gain.

gain will be a float from 0 to 1 representing the fraction of maximal signal amplification that a fluorescence reading device can provide.

Vendor specific limitations may apply to the availability of this optional parameter and the sensitivity available to changes in gain (different vendors may have different step sizes for the gain parameter and/or round to the closest step size).

  
  {
    "op": "fluorescence",
    "object": container,
    "wells": [
      well
    ],
    "excitation": length,
    "emission": length,
    "num_flashes": integer,
    "dataref": string,
    "temperature": temperature,
    "incubate_before": {
      "duration": time,
      "shaking": {
        "amplitude": length,
        "orbital": bool
      },
    /* optional, if the parameter is not specified, signal amplification will     
       employ vendor specified defaults */
    "gain": float
    }
  }

Execution

The gain parameter represents a fraction of maximal signal amplification and may need to be rounded to the nearest step if signal amplification is non-linear. If an optimal gain finding feature is available, it’s recommended to use such a feature when the gain parameter is not specified. It is also recommended to report the gain setting used in the dataref of the instruction.

Compatibility

This ASC specifies a new field for existing instructions. Fluorescence instructions without this optional parameter will read plates in the vendor specified default manner previously used.

ASC-015 - Magnetic Transfer

Title

Magnetic Transfer

Authorship

Conny Scheitz conny@transcriptic.com

Peter Lee peter@transcriptic.com

Ian O’Hara ian@transcriptic.com

Motivation

Separation of liquid samples using magnetic particles is a common laboratory practice involving the binding of samples to magnetic particles, followed by cycles of immobilization and washing of those particles, and finally elution of samples from the particles. The “Magnetic Bead Transfer” instruction specifies a method for processing magnetic particles that transfers the particles from solution to solution.

Proposal

This instruction allows the implementation of bead purification protocols by providing control over magnetic pins, protection tips which cover all of the pins, and the heating platform of a magnetic particle processing instrument.

Five sub-operations have been defined to specify magnetic_transfer.

collect - used to collect beads from an object. Protection tips are magnetized and raised and lowered repeatedly pausing at the bottom_position for pause_duration time. The lowering, pausing, and raising is performed a number of cycles times. During this instruction, the object can be optionally heated to temperature.

mix - used to oscillate the tips vertically in an object. The oscillation will last for duration and move with a frequency and amplitude around center. During this instruction, the object can be optionally heated to temperature and the tips can be magnetized.

release - used to release beads into an object. Non-magnetized tips are oscillated vertically. The oscillation will last for duration and move with a frequency and amplitude around center. During this instruction, the object can be optionally heated to temperature.

dry - used to dry beads with tips above and outside an object for a set duration.

incubate - used to incubate an object for a set duration with the tips moved to tip_position. During this instruction, the object can be optionally heated to temperature and the tips can be magnetized.

The magnetic_transfer instruction takes a list of list of dicts. Each dict is a sub-operation. Each list of dicts represents a collection of sub-operations which will be performed in order using the same tip. The list of groups represents the collection of sub-operations, performed in order, with tip changes between each group.

The bottom_position, tip_position, center, and amplitude parameters are expressed as floats of relative well height. Setting one of these parameters to 0 represents positioning from the well bottom or height of 0, 1 represents positioning at the well top or the height of a well, and 2 represents positioning at twice the well height from the well bottom (or one well height above the well top) or twice the height of a well.

If temperature is null or unset, no heat will be applied and the container will not be set onto the heating plate.

Some vendor specific restrictions may apply to the number of containers supported per instruction, the compatibility of containers for the instruction, as well as the ranges supported for parameters in the each sub-operation.

{
  "op": "magnetic_transfer",
  "groups": [
    /* sub-operations in the same group use the same protector tip */
    [
      {
        /* tips are always magnetized during collect */
        "collect": {
          "object": container,
          "cycles": integer,
          /* time spent paused at "bottom_position" */
          "pause_duration": time,
          /* position relative to well height where tips pause,
             optional, default: 0.0 */
          "bottom_position": float,
          /* optional, default: null */
          "temperature": temperature  
        }
      },
      {
        "mix": {
          "object": container,
          "duration": time,
          "frequency": frequency,
          /* optional, default: false */
          "magnetize": bool,
          /* optional, default: null */
          "temperature": temperature,
          /* position relative to well height where oscillation is centered,
             optional, default: 0.5 */
          "center": float,
          /* distance relative to well height to oscillate around "center", 
             optional, default: 0.5 */
          "amplitude": float
        }
      },
      {
        /* tips are never magnetized during release */
        "release": {
          "object": container,
          "duration": time,
          "frequency": frequency,
          /* optional, default: null */
          "temperature": temperature,
          /* position relative to well height where oscillation is centered,
             optional, default: 0.5 */
          "center": float,
          /* distance relative to well height to oscillate around "center", 
             optional, default: 0.5 */
          "amplitude": float
        }
      },
      {
        /* tips are always magnetized during dry,
           tips are held above the "object" for the indicated "duration" */
        "dry": {
          "object": container,
          "duration": time
        }
      },
      {
        "incubate": {
          "object": container,
          "duration": time,
          /* optional, default: false */
          "magnetize": bool,
          /* position relative to well height that tips are held, 
             optional, default: 1.5 */
          "tip_position": float,
          /* optional, default: null */
          "temperature": temperature
        }
      }, ...
    ], ...
  ],
  "magnetic_head": "96-deep" | "96-pcr"
}

Vendor defaults may apply to “droplet_size”.

Compatibility

This is a new instruction.

ASC-014 - Acoustic Liquid Handling

Title

Acoustic Liquid Handling Instruction

Authorship

Tali Herzka tali@transcriptic.com

Peter Lee peter@transcriptic.com

Cornelia Scheitz conny@transcriptic.com

Motivation

Acoustic liquid handling is droplet_size based with most instruments only capable of transferring a single droplet_size. The final volume to be transferred must be an integer multiple of this droplet_size. An additional instruction specifying that liquid is to be transferred via an acoustic liquid handler vs. a tip-based air-displacement pipettor is therefore necessary since these instructions require and permit different parameters.

Proposal

{
  "op": "acoustic_transfer",
  "groups": [
    {
      "transfer": [
        {
          "from": well,
          "to": well,
        "volume": volume
  }
        ...
       ]
    }
  ],
  "droplet_size": volume
}

Vendor defaults may apply to “droplet_size”.

Compatibility

This ASC only proposes the addition of a new instruction.

ASC-013 - Modify stamp instruction format to be consistent with pipette

Title

Modify stamp instruction format to be consistent with pipette

Authorship

Pavel Konov pavel@transcriptic.com

Motivation

The structure of the stamp and pipette commands differ in that stamp takes a list of transfers, instead of the group operations of pipette. However, in order to implement tip-reuse in the case of plate stamping, a way to delineate which groups of transfers will use the same set of tips is required. This problem is already solved in the pipette instruction: the stamp instruction should likewise be a sequence of transfer groups, and not a sequence of individual transfers. This provides consistency between liquid handling systems.

Note that this will open up the possibility of expanding plate stamping capabilities in the future to also support the other three groups used in pipette (distribute, consolidate, mix). At present, only the transfer group is supported.

Proposal

Change stamp to follow the format of pipette groups Move shape and tip_layout out from the individual transfers onto the transfer group itself.

{
  "op": "stamp",
  "groups": [
    {
      "transfer": [
        {
          "from": origin,
          "to": origin,
          "volume": volume,

            // same mix options as a 'transfer' group in the 'pipette' instruction
          "mix_before": {...},  //optional
          "mix_after": {...} //optional
        },
        {...} // additional transfers using same tips
      ],
      "shape": rectangle,  // optional, default: {"rows": 8, "columns": 12}
      "tip_layout" : integer,  // optional, default: 96
    }
  ]
}

Examples:

Example 1: A two-column transfer between plates, where the same set of tips are used for both transfers.

{
  "op": "stamp",
  "groups": [
    {
      "transfer": [
        {
          "from": "src_plate/A1",
          "to": "dest_plate/A2",
          "volume": "10:microliter"
        },
        {
          "from": "src_plate/A3",
          "to": "dest_plate/A4",
          "volume": "20:microliter"
        },
      ],
      "shape": { "rows": 8, "columns": 2 },
    }
  ]
}

Example 2: Two sets of row-wise serial dilutions, each re-using a single row of tips within the serial dilution.

{
  "op": "stamp",
  "groups": [
    {
      "transfer": [
        {
          "from": "src_plate/A1",
          "to": "src_plate/B1",
          "volume": "10:microliter",
          "mix_after": {
            "volume": "35:microliter",
            "repetitions": 10,
            "speed": "100:microliter/second"
          }
        },
        {
          "from": "src_plate/B1",
          "to": "src_plate/C1",
          "volume": "10:microliter",
          "mix_after": {
            "volume": "35:microliter",
            "repetitions": 10,
            "speed": "100:microliter/second"
          }
        },
        {
          "from": "src_plate/C1",
          "to": "src_plate/D1",
          "volume": "10:microliter",
          "mix_after": {
            "volume": "35:microliter",
            "repetitions": 10,
            "speed": "100:microliter/second"
          }
        }
      ],
      "shape": { "rows": 1, "columns": 12 }
    },
    {
      "transfer": [
        {
          "from": "src_plate/E1",
          "to": "src_plate/F1",
          "volume": "10:microliter",
          "mix_after": {
            "volume": "35:microliter",
            "repetitions": 10,
            "speed": "100:microliter/second"
          }
        },
        {
          "from": "src_plate/F1",
          "to": "src_plate/G1",
          "volume": "10:microliter",
          "mix_after": {
            "volume": "35:microliter",
            "repetitions": 10,
            "speed": "100:microliter/second"
          }
        },
        {
          "from": "src_plate/G1",
          "to": "src_plate/H1",
          "volume": "10:microliter",
          "mix_after": {
            "volume": "35:microliter",
            "repetitions": 10,
            "speed": "100:microliter/second"
          }
        }
      ],
      "shape": { "rows": 1, "columns": 12 }
    }
  ]
}

Example 3: One full-plate 96w -> 384w distribute, using 4 transfers with the same tips.

{
  "op": "stamp",
  "groups": [
    {
      "transfer": [
        {
          "from": "src_plate/A1",
          "to": "dest_plate/A1",
          "volume": "20:microliter"
        },
        {
          "from": "src_plate/A1",
          "to": "dest_plate/A2",
          "volume": "20:microliter"
        },
        {
          "from": "src_plate/A1",
          "to": "dest_plate/B1",
          "volume": "20:microliter"
        },
        {
          "from": "src_plate/A1",
          "to": "dest_plate/B2",
          "volume": "20:microliter"
        },
      ]
    }
  ]
}

Compatibility

This change reorganizes existing fields and is not backwards-compatible. To upgrade from a previous version, transfers must be converted to the group format and the optional shape and tip_layout parameters must be moved to the transfer group level.

E.g.: What was previously:

{
  "operation": {
    "transfers": [
      {
        "volume": "10.0:microliter",
        "from": "src_plate/A1",
        "to": "dest_plate/A1",
        "shape": {
          "rows": 8,
          "columns": 1
        }
      },
      {
        "volume": "20.0:microliter",
        "from": "src_plate/A1",
        "to": "dest_plate/A1",
        "shape": {
          "rows": 8,
          "columns": 1
        }
      }
    ],
    "op": "stamp"
  }
}

becomes:

{
  "operation": {
    "groups": [
        {
          "transfer": [
            {
              "volume": "10.0:microliter",
              "from": "src_plate/A1",
              "to": "dest_plate/A1"
            }
          ],
          "shape": {
            "rows": 8,
            "columns": 1
          }
        },
        {
          "transfer": [
            {
              "volume": "20.0:microliter",
              "from": "src_plate/A1",
              "to": "dest_plate/A1"
            }
          ],
          "shape": {
            "rows": 8,
            "columns": 1
          }
        }
      ],
    "op": "stamp"
  }
}

ASC-012 - Modify stamp to accept multi-channel (whole row(s) or column(s)) operations

Title

Modify stamp to accept multi-channel (whole row(s) or column(s)) operations

Authorship

Yang Choo yangchoo@transcriptic.com

Peter Lee peter@transcriptic.com

Ian O’Hara ian@transcriptic.com

Motivation

A more granular multi-channel liquid transfer instruction is required to encompass multi-channel pipetting from/to whole row(s) or whole column(s) (or logical subsets of row(s) or column(s)) of a multi-well plate as defined by SBS recommendations of microplates as a superset of the previous stamp instruction.

Proposal

Rename quadrant to origin and add a new shape field.

As before, origin has the same form as the well type (that is, “:ref/:well_index”), where :well_index refers to the top-left well of a shape.

shape takes in the parameter rectangle which is a dictionary defined with keys rows,columns that describe the shape of the rectangle as defined by the number of wells being transferred in each direction. (e.g. {“rows”: 8, “columns”: 1}).

tip_layout specifies SBS standard-compliant layout of the tips used for the specified transfer operation. Common SBS tip layouts include 96, 384 and 1536.

Some vendor specific restrictions may apply.

For example, in rectangle, values for rows or columns may be constrained to either 8 or 12 respectively with the other key taking values between [1 8] or [1 12]. In the example given, [5 8] and [12 4] are acceptable shape definitions while [5 7] and [9 4] are unacceptable.

As another example, shape and tip_layout may be restricted such that the same shape and tip_layout must be used in all transfers throughout a single stamp instruction.

Finally, tip_layout might be restricted to only certain layouts, like 96.

{
  "op": "stamp",
  "transfers": [
    {
      "from": origin,
      "to": origin,
  "shape": rectangle,  // optional, default: {"rows": 8, "columns": 12}
  "tip_layout" : integer,  // optional, default: 96
"volume": volume,

  // same mix options as a 'transfer' group in the 'pipette' instruction
      "mix_before": {...},
      "mix_after": {...}
    }
  ]
}

Examples:

Example 1: A 96-well to 384-well quadrant transfer omitting the optional shape field.

  "transfers": [{ "from": "src_plate/A1", "to": "dest_plate/B2" }]

Example 2: A transfer from the G row to the H row of another 96-well plate.

  "transfers": [{
    "from": "src_plate/G1",
    "to": "dest_plate/H1",
    "shape": { "rows": 1, "columns": 12 },
    "tip_layout" : 96
  }]

Example 3: A 2-column transfer from columns 1,2 to columns 2,3 of 384-well plates with the specification that all wells in the columns are transferred.

  "transfers": [{
    "from": "src_plate/A1",
    "to": "dest_plate/B1",
    "shape": { "rows": 16, "columns": 2},
    "tip_layout" : 384
  }]

Example 4: A series of row transfers from one source row to multiple destination rows of a 96-well plate using the same shape and tip_layout.

  "transfers": [
    {
      "from": "src_plate/A1",
      "to": "dest_plate/A1",
      "shape": { "rows": 1, "columns": 12 },
      "tip_layout" : 96
    },
    {
      "from": "src_plate/A1",
      "to": "dest_plate/B1",
      "shape": { "rows": 1, "columns": 12 }
      "tip_layout" : 96
    }
  ]

Compatibility

This change extends the existing stamp operation with the addition of the shape and tip_layout parameters.

The default value for the optional shape parameter is {"rows": 8, "columns": 12} and for the optional tip_layout parameter is 96 which replicates the behavior of the previous stamp operation and allows for backwards compatibility.

ASC-011 - Add Stamp Instruction (96-channel pipetting)

Title

Add Stamp Instruction (96-channel pipetting)

Authorship

Ian O’Hara ian@transcriptic.com

Jeremy Apthorp jeremy@transcriptic.com

Tali Herzka tali@transcriptic.com

Motivation

An instruction is needed to specify 96-channel simultaneous liquid handling (also referred to as stamping). This is generally done to transfer liquid from all wells of one 96-well plate to another or to reformat one plate type into another (for example, reformat four 96-well plates onto a single 384-well plate).

Proposal

A stamp instruction consists of a list of transfers, each of which specifies from and to well references representing the top-left well of a quadrant. The volume field specifies the volume of liquid that will be aspirated from every well of the from quadrant and dispensed into the corresponding well of the to quadrant.

{
  "op": "stamp",
  "transfers": [
    {
      "from": quadrant,
      "to": quadrant,
      "volume": volume,

    // same mix options as a 'transfer' group in the 'pipette' instruction
      "mix_before": {...},
      "mix_after": {...}
    }
  ]
}

The quadrant type is new, and has the same form as the well type (that is, ":ref/:well_index"), with the restriction that :well_index must refer to the top-left well of a quadrant. What this means is vendor-specific (see below for details).

Execution

Accepted quadrants depend on the types of the source and destination containers. A vendor is responsible for determining allowable container types and quadrant definitions.

For example, in the context of 96-well plates, only well A1 may be referenced. On 384-well plates, each of the four 96-well containing quadrants can be specified using the well indices A1, A2, B1, or B2 respectively. A vendor may choose to support other container types and/or quadrant definitions based on their hardware.

ASC-010 - Add dataref and criteria fields to autopick

Title

Add dataref and criteria fields to autopick

Authorship

Jeremy Apthorp jeremy@transcriptic.com

Cornelia Scheitz conny@transcriptic.com

Tali Herzka tali@transcriptic.com

Ian O’Hara ian@transcriptic.com

Motivation

The autopick instruction as it currently stands does not allow for relating returned data, such as the number of colonies counted, to an instruction. It also does not specify other options for colony picking such as only picking colonies of a specific size or color.

Proposal

We propose adding two new fields to the autopick instruction: dataref: in order to specify a string for relating data returned from a colony picker criteria: a hash containing specific options related to picking colonies, for example {"color": "white", ...}. Accepted criteria would be determined by the vendor and/or hardware involved in colony picking.

Example

{
  "dataref": string
  "op": "autopick",
  "from": well,
  "to": [well],
  "min_colony_count": int     // optional, default: 1
  "criteria": { ... }         // optional, default: {}
}

Execution

Accepted criteria for colony picking are determined by the vendor/hardware involved in this operation.

Compatibility

This ASC only specifies new fields of an existing instruction.

ASC-009 - Oligosynthesize

Title

Oligosynthesize

Authorship

Jeremy Apthorp jeremy@transcriptic.com

Conny Scheitz conny@transcriptic.com

Tali Herzka tali@transcriptic.com

Motivation

An instruction is required to specify sequence(s) of oligos to be synthesized, in-house or otherwise.

Proposal

The oligosynthesize Autoprotocol instruction specifies a list of oligonucleotides to synthesize, the final destination of the synthesized oligo, and the scale and purification method of synthesis. Vendors determine what constitutes a valid sequence based on their method of synthesis. Typically, at least the IUPAC codes for basepairs are accepted: http://www.bioinformatics.org/sms/iupac.html

Example:

{
  "op": "oligosynthesize",
  "oligos": [
    {
      "destination": "my_plate/A1",
      "sequence": "CATGGGTAVNNNNGAAB",
      "scale": "25nm" | "100nm" | "250nm" | "1um",
      "purification": "standard" | "page" | "hplc",
        // default: standard
    },
    // …
  ]
}

Compatibility

This ASC only specifies a new instruction.

ASC-008 - Addition of RCA to `sanger_sequence`

Title

Sanger Sequencing - RCA

Authorship

Cornelia Scheitz conny@transcriptic.com

Motivation

In addition to basic plasmid sequencing, bacteria can also be a source to submit for sequencing utilizing rolling-circle-amplification (RCA) to generate DNA. Since this is carried out by the sequencing facility, these add-ons should be part of the sequencing instruction.

Proposal

{
    "op": "sanger_sequence",
    "type": "standard | rca", //default: standard
    "object": container,
    "wells": [well_index],
    "dataref": string
    "primer": container //only required for rca, tube containing sufficient primer for all sequencing reactions
}

Execution

The container specified will be sent to the sequencing device or service and subsequently destroyed. The specified wells will be sequenced through the Sanger chemistry.

For the standard type: the specified wells should already contain the appropriate mix for sequencing, including primers and DNA according to the instructions provided by the vendor.

For type RCA: The specified wells should already contain 15 µL of bacterial solution. The primer to be used for sequencing is indicated in the “primer” parameter and must be a container with sufficient primer volume for all sequencing reactions in this instruction plus some vendor defined dead-volume. Only one primer per container is permitted.

Compatibility

This ASC adds 2 new parameters. Instructions without “type” will be considered of “type”: “standard” and thus ensure backwards compatibility.

ASC-007 - Flash Freeze

Title

Flash Freeze

Authorship

Cornelia Scheitz conny@transcriptic.com

Motivation

Flash freezing is done using liquid nitrogen and as such needs special equipment and dedicated sample handling to withstand the ultra-low temperatures. As such it deserves a dedicated Autoprotocol instruction.

Proposal

{
 "op": "flash_freeze",
 "object": container,
 "duration": "30:second" //between 10:second and 180:second
}

Execution

The container specified will be dipped into liquid nitrogen for the set period of time. The container can then be used in other autoprotocol instructions or be stored.

Compatibility

This ASC only specifies new instructions.

ASC-006 - Flow Analyze

Title

Flow Analyze

Authorship

Cornelia Scheitz conny@transcriptic.com

Adam Naguib adam@transcriptic.com

Jeremy Apthorp jeremy@transcriptic.com

Motivation

Multicolor flow cytometry is a common tool in the life sciences and several dedicated devices are available. This instruction takes aliquots and analyzes them with the parameters given. It requires at least one negative control which will be used to define data acquisition parameters as well as to determine any autofluorescent properties for the sample set. Additional negative positive control samples are optional. Positive control samples will be used to optimize single color signals and, if desired, to minimize bleed into other channels.

Proposal

{
 "op": "flow_analyze",
 "dataref": "flow_data",
 "channels": {
   "FSC": {
     "voltage_range": {
       "low": "230:volt",
       "high": "280:volt"
       },
     "area": true,             //default: true
     "height": true,           //default: true
     "weight": false           //default: false
     },
   "SSC": {
     "voltage_range": { … },
     "area": true,             //default: true
     "height": false,          //default: false
     "weight": false           //default: false
     },
   "colors":[{
     "name": "FitC",
     "emission_wavelength": "495:nanometer",
     "excitation_wavelength": "519:nanometer",
     "voltage_range": { … },
     "area": true,             //default: true
     "height": false,          //default: false
     "weight": false           //default: false
   }, … ]
 },
 "negative_controls": [{
   "well": well,
   "volume": volume,
   "captured_events": integer,     // optional, default infinity
   "channel": [channel_name]
 }],                               // at least 1 negative control req'd
 "positive_controls": [{
   "well": well,
   "volume": volume,
   "captured_events": integer,     // optional, default infinity
   "channel": [channel_name],
   "minimize_bleed": [{            // optional
     "from": color,
     "to": [color]
   }, … ]
 }],
 "samples": [{
   "well": well,
   "volume": volume,
   "captured_events": integer,     // optional, default infinity
 }]
}

flow_analyze returns data

{
 "parameters": {
   "FSC_voltage": volt,
   "SSC_voltage": volt,
   "colors":{[
     "name": string,
     "actual_voltage": volt
   ], … },
 }
 "data": {
   "plate1/A3": {
     "fsc_3.1": "url"
   }
 }
}

Execution

The instruction will be executed within the voltage range specified for each channel, optimized for the best sample separation/distribution that can be achieved within these limits. The vendor will specify the device that this instruction is executed on and which excitation and emission spectra are available.

For each sample this instruction asks you to specify the volume and/or captured_events. Vendors might also require captured_events in case their device does not support volumetric sample intake. If both conditions are supported, the vendor will specify if data will be collected only until the first one is met or until both conditions are fulfilled.

Compatibility

This ASC only specifies new instructions.

Public google doc for future updates

ASC-005 - Add co2_percent Parameter to incubate Instruction

Title

Add co2 parameter to incubate instruction

Authorship

Cornelia Scheitz conny@transcriptic.com

Motivation

Incubation for mammalian tissue culture requires control of CO2 concentration to level above the atmospheric composition. This specifies the amount of CO2 to add, in percent.

Proposal

The incubate instruction should take an additional parameter "co2" of type ‘percentage’ to specify the amount of CO2 during an incubation

{
  "op": "incubate",
  "object": container,
  "where": temperature,
  "duration": duration,
  "shaking": bool,
  "co2": percent            //optional, default: 0
}

The combination of temperature and CO2 levels available will be determined by the vendor. For example only: "where": "warm_37","shaking": False, "co2": "5:percent" might be allowed.

Execution

The sample will be incubated according to the specified parameters at the given amount of CO2.

Compatibility

This parameter is optional and will default to 0%. There are no backwards compatibility issues.

ASC-004 - Add type Parameter to seal Instruction

Title

Add type parameter to seal instruction

Authorship

Cornelia Scheitz conny@transcriptic.com

Motivation

The type of seal can be different depending on the application. For example qPCR applications require ultra-clear seals to read the fluorescence data from the wells. Regular PCR can use either foil or clear seals. Sealing a plate with DMSO will require a chemically resistant seal which likely foil based.

Proposal

The seal instruction should take an additional mandatory parameter, "type", of type string. This specifies the type of seal to be applied to the plate.

Example:

{
  "op": "seal",
  "object": container,
  "type": "foil"
}

The types available are specified by the vendor, examples are: “ultra-clear”, “foil”.

Compatibility

To aid transition to the addition of the mandatory "type" parameter, implementations should continue to accept seal instructions with no type specified. If no type is specified, the type shall be assumed to be an ultra-clear seal.

ASC-003 - Cell Spreading and Colony Picking

Title

Cell spreading and colony picking

Authorship

Jeremy Apthorp jeremy@transcriptic.com Cornelia Scheitz conny@transcriptic.com

Motivation

Many important protocols depend on plating bacteria on agar and picking colonies, processes that cannot currently be represented in Autoprotocol.

Proposal

We propose two new instructions: spread and autopick. These instructions are intended to be used with 1- or 6-well SBS microplate pre-filled with agar.

**spread**

{
  "op": "spread",
  "from": well,
  "to": well,
  "volume": volume
}

Execution

Spread the specified volume of the source aliquot evenly across the surface of the agar in the object container.

autopick** #### Parameters**

{
  "op": "autopick",
  "from": well,
  "to": [well],
  "min_colony_count": int     // optional, default: 1
}

Execution

Pick (using a pin tool or pipette tip) at least min_colony_count colonies from the from well into the to wells. If insufficient colonies are available to fill all the to wells, the to wells should be filled in the order specified until no more colonies are available. If fewer than min_colony_count colonies are present in the from well, fail the instruction (see the section below on potentially-failing instructions for details).

Imaging and identifying suitable colonies to pick is left to the vendor to implement. Future work may include additional specifications on selecting colonies by particular criteria (e.g. blue/white selection), but that is outside the scope of this document.

Potentially-failing instructions

A major new concept the autopick instruction introduces is that of an operation that can fail. Since it is not guaranteed that enough colonies grew to fulfill the request, we propose that if the number of available colonies is less than the specified min_colony_count then pick no colonies at all and fail. That is to say, the run should stop and return all containers to their destinations if an insufficient number of colonies are detected.

Compatibility

This ASC only specifies new instructions.

ASC-002 - Sanger Sequencing

Title

Sanger Sequencing

Authorship

Jeremy Apthorp jeremy@transcriptic.com

Motivation

The Sanger sequencing reaction is usually performed by a dedicated sequencing device (or mail-out service), and as such warrants a dedicated Autoprotocol instruction.

Proposal

{
  "op": "sanger_sequence",
  "object": container,
  "wells": [well_index],
  "dataref": string
}

Execution

The container specified will be sent to the sequencing device or service and subsequently destroyed. The specified wells will be sequenced through the Sanger chemistry.

The specified wells should already contain the appropriate mix for sequencing, including primers and DNA according to the instructions provided by the vendor.

Compatibility

This ASC only specifies new instructions.

ASC-001 - add volume Parameter to gel_separate Instruction

Title

Add ‘volume’ parameter to gel_separate instruction

Authorship

Jeremy Apthorp jeremy@transcriptic.com Cornelia Scheitz conny@transcriptic.com

Motivation

The amount of liquid to be added to each well of a gel is an important experimental parameter, as it can affect the distribution of current throughout the gel and thus the quality of the resultant gel image.

Proposal

The gel_separate instruction should take an additional mandatory parameter, "volume", of type volume. This specifies the volume of liquid to be pipetted into each well of the gel. The same volume will be used for all specified wells in the gel_separate instruction, so that results are properly comparable.

Example:

{
  "op": "gel_separate",
  "volume": "15:microliter",
  "objects": [
    "plate1/A1",
    "plate1/A2"
  ],
  "matrix": "agarose(8,0.8%)",
  "ladder": "ladder1",
  "duration": "5:minute",
  "dataref": "gel"
}

Compatibility

To aid transition to the addition of the mandatory "volume" parameter, implementations should continue to accept gel_separate instructions with no volume specified. If no volume is specified, the volume shall be assumed to be 20 microliters.