Autoprotocol Standard Changes

Title

Revision to Compound

Authorship

Asuka Ota asuka.ota@strateos.com

Motivation

Some of the challenges in representing molecular structures in 2D include the lack of standardized representation with enough structural data, and the lack of standardized method to interpret one representation to another without altering the data it represents (as perceived by the end user). For instance, standard InChI ‘InChI=1S/C8H9NO2/c1-6(10)9-7-2-4-8(11)5-3-7/h2-5,11H,1H3,(H,9,10)’ represents a molecule that can be described by multiple SMILES including CC(=O)NC1=CC=C(C=C1)O, OC1=CC=C(NC(C)=O)C=C1, and CC(=O)Nc1ccc(O)cc1. In this case, each SMILES actually carry slightly different information on the atom locations, and represents different isomers while InChI collectively label them as the ‘same molecule’. As a result, when the molecule is interpreted from one representation to another, the molecular structure can be misinterpreted.

We initially chose to represent Compound using standard InChI. However, the consensus from the primary users suggest that SMILES is more commonly used method of representing molecule, and each time SMILES is interpreted in InChI (or vice versa) there is a chance of misinterpretation due to the challenges mentioned above.

Proposal

Standardization of chemical structures represented with diverse chemical information in many different methods is a very complicated feat, and it is an ongoing effort in the field. To best minimize the chance of altering the molecular data or intent contained in the string, we propose to revise Compound class to utilize more widely used representation of molecule in the form of Daylight Canonical SMILES which indicates a canonical SMILES with isotopic and chiral specifications. SMILES was originally developed by Daylight Chemical Information Systems, and non-proprietary SMILES specification described in SMILES Theory Manual has been the golden standard. Daylight Canonical SMILES is also more human readable, compact, and represents a specific molecular structure.

{ “format”: Enum(“InChI”, “Daylight Canonical SMILES”), “value”: String }

Example valid values for different compounds:

Note there are multiple ways to represent e.g. ethanol in SMILES including “C(O)C”, “OCC”, “C-C-O” to name a few. However, the canonical, unique representation of ethanol in Daylight Canonical SMILES would be “CCO”. There is an algorithm to generate a unique SMILES from any one of these generic SMILES such as SmilesGenerator, RDKit, or based on a structure as in ChemDraw. It is important to note that Daylight Canonical SMILES is not a perfect solution as SMILES canonicalization algorithm depends on the software package, and it is recommended to compare SMILES strings within the same platform to best preserve the structural information. Furthermore, the interpretation of different representation methods is up to the vendor.

Compatibility

This introduces change in existing Compound class. Other methods that utilize Compound may need to be updated to reflect the change.

Title

Add Compound to derived types

Authorship

Yang Choo yang.choo@strateos.com

Motivation

The usage of chemical compounds (or substances) is common throughout science. We should have some first-class representation of this type in Autoprotocol.

Proposal

Let us add a new derived type, Compound, which shall be represented as a String. We shall standardize on the IUPAC InChI (International Chemical Identifier) notation as the representation of choice. Note that we will be standardizing on the standard InChI convention and not the InChiKey convention.

The reasons for choosing this format are its unambiguous nature, readability and the wide availibility of tools to interconvert to other popular formats such as SMILES.

Here are example valid values for different compounds

Compatibility

Since this is an addition, not a modification, there’s no anticipated backwards compatibility issues.

Title

Add dispense mode to liquid_handle instruction

Authorship

Rhys Ormond rhys.ormond@strateos.com Peter Lee peter.lee@strateos.com

Motivation

Devices such as reagent dispensers are configurable in many of the same ways that channel-based air_displacement liquid handlers are. The primary difference between them is the concept of a flow of liquid between two aliquots.

Proposal

We propose the dispense mode for the liquid_handle instruction to represent the mode of liquid handling used by devices such as reagent dispensers.

This mode follows the same general structure of air_displacement differing primarily in how locations are interpreted. In dispense the first location referenced is always the source aliquot. All other locations that reference aliquots are destinations. Locations with no aliquot specified indicate a waste position.

The aspirated (negative) volume in the source location must equal the total volume dispense across all other locations.

{
  "op": "liquid_handle",
  "locations": [
    {
      "location": aliquot,
      "transports": [
        {
          "volume": volume  // negative for source aliquot
        }
      ]
    },
    {
      "location": null,  // no location for dispense into waste
      "transports": [
        {
          "volume": volume  // positive for destination
        }
      ]
    },
    {
      "location": aliquot,
      "transports": [
        {
          "volume": volume  // positive for destination,
          /**
            *Unless otherwise specified all other parameters within transports are optional
            */
          "pump_override_volume": volume,
          "flowrate": {
          // target is required for flowrate
          "target": flowrate,
            "initial": flowrate,
            "cutoff": flowrate,
            "acceleration": volumeAcceleration,
            "deceleration": volumeAcceleration
          },
          “delay_time”: time,
          "mode_params": {
            "volume_resolution": volume,
            "liquid_class": Enum("air", "default"),
            "tip_position": {
              "position_x": {
                "position": float,
                "move_rate": {
                  "target": speed,
                  "acceleration": acceleration
                }
              },
              "position_y": {
                "position": float,
                "move_rate": {
                  "target": speed,
                  "acceleration": acceleration
                }
              },
              "position_z": {
                "offset": distance,
                "move_rate": {
                  "target": speed,
                  "acceleration": acceleration
                },
                "reference": Enum(
                  "well_top",
                  "well_bottom",
                  "preceding_position"
                )
              }
            }
          }
        }
      ],
      “temperature”: temperature
    }
  ],
  "shape": {
    "rows": int,  // optional
    "columns": int,  // optional
    "format": enum("SBS96", “SBS384”)  // optional
  },  // optional
  "mode": "dispense"
}

Compatibility

This ASC specifies a new mode for an existing instruction and should be entirely backwards compatible.

Title

Modifying instruction: provision

Authorship

Asuka Ota asuka.ota@strateos.com
David Lyon david.lyon@strateos.com

Motivation

provision transfers specific quantities of sample from a resource to single or multiple wells. Currently, provision only allows sample quantity to be specified in volume. However, there often are cases where sample needs to be specified in mass for both liquid and solid samples. To allow for different transfer units, we are adding measurement_mode to specify unit type. We are also adding dict specific for mass mode in the to parameter. For backward compatibility, we are keeping the to parameter the same for volume mode.

Proposal

We propose a more versatile provision instruction to support mass mode to allow provisioning by mass unit in addition to volume.

{
  "op": "provision"
  /* Mode of Provision. Optional with default value to 'volume' */
  "measurement_mode": Enum("mass", "volume")
  /* 
   * Destination wells. To keep `provision` backward compatible, this can
   * be a list of either `volume`-specific dict or `mass` dict. Adding `mass` dict
   * as shown below.
   */
  "to":[
    /* parameters for 'mass'. Optional */
    {
      "well": Well
      "mass": Mass
    }
    ...
  ]
  ...
}

Execution

Devices present in the execution environment are capable of respecting specific volume or mass, and that optional parameters default to sensible values when unspecified.

Compatibility

This change is backwards compatible; there are enough unit tests to ensure the changes will not break any existing operations and features.

Title

Modifying instruction: liquid_handle

Authorship

Asuka Ota asuka.ota@strateos.com

Motivation

liquid handle allows the transfer of liquid from one container to one or more other containers. The viscosity of liquid samples used in the laboratory ranges from very fluid (ie. acetone) to very thick (ie. glycerol). A limitation to the current liquid_handle instruction is that there are only two modes of volumetric manipulation available: dispense and air-displacement. While this is sufficient for liquids with relatively low viscosity, they should not be used for viscous samples due to the inability for air pressure to overcome surface tension. To provide a more accurate way to handle these samples, ‘positive-displacement’ method is added to mode, and ‘viscous’ is added to liquid_class. Furthermore, there are devices that are capable of requesting liquid transfer amount in mass instead of volume. To allow such , optional density parameter should be added to convert mass to volume (and vice versa) as needed.

Proposal

We propose a more versatile liquid_handle instruction to support positive-displacement mode, and optional density field in addition to the currently-available capabilities.

{
  “op”: “liquid_handle”,
  /* Parameters describing the transport of liquid locations, speed, acceleration and any other device-specific parameters that may need to be provided by the user. Optional */
  “locations”: List[{
    transports: [
        {
          /* Density of the liquid being handled. If this value is specified, the transport volume is converted
          to mass. Optional. */
          "density": Unit
          "mode_params": [{
            /* Type of liquid transported. Optional. */
            "liquid_class": Enum("air", "default", "viscous")
          }]
          ...
        }
    ],
    ...
  }],
  /* Allowed modes for liquid handling. 'positive_displacement' should be included as a new mode. 'positive_displacement' mode will use the same mode_params as other modes. */
  “mode”: Enum(“air_displacement”, ”dispense”, “positive_displacement”)
}

Execution

Vendors must ensure that devices present in the execution environment are capable of respecting specific mode and transport parameters, and that optional parameters default to sensible values when unspecified.

Compatibility

This change is backwards compatible; there are enough unit tests to ensure the changes will not break any existing operations and features.

Title

Add concentration Unit to Units Definitions

Authorship

Alex Hadik alex.hadik@strateos.com

Motivation

We should formalize how we represent matter and concentration so that we adhere to BIPM standards and have a standard way of defining solution concentrations.

Proposal

Matter

Currently we use the term matter to refer to mole, millimole and micromole. In accordance with BIPM standards, matter will now be referred to as amount.

Mass, Volume and Moles

Add three types of concentration units to the units definition list: mass, volume and amount. These concentration types will be defined as follows:

• MassConcentration: milligram/milliliter, nanogram/microliter
• VolumeConcentration: milliliter/milliliter, microliter/microliter
• AmountConcentration: mole/liter, millimole/liter, micromole/liter, molar, millimolar, micromolar

These units are validated by validating the numerator and denominator units. The numerator must be any valid unit from the following set: (Mass, Volume, Amount) The denominator must be a recognized unit from the Volume category.

Given this validation approach, it should be noted that the proper format is singular/singular as in milligram/milliliter - NOT milligrams/milliliter.

Put together, the format is Float:Concentration.

Compatibility

Since this is an addition, not a modification, there’s no anticipated backwards compatibility issues. The only anticipated concerns are that some undocumented approaches to concentration exist in codebases already. These would ideally need to be refactored to be in alignment with these updates.

Title

Update Units Definitions with units in use at Strateos

Authorship

Yang Choo yang.choo@strateos.com

Motivation

There are a number of units we have since adopted at Strateos for chemistry and biology purposes which are currently not present in the Autoprotocol specification.

Proposal

Add the following units - Acceleration: millimeter/second^2 - ElectricPotential: nanovolt, microvolt - Frequency: kilohertz, rpm - Length: nanometer - Mass: nanogram - Matter: nanomole - Power: microwatt, milliwatt - Pressure: bar, torr - Velocity: millimeter/second - Volume: nanoliter - VolumeAcceleration: milliliter/second^2 - VolumeFlow: milliliter/second

Compatibility

No backwards compatibility issues as this is just adding new units.

Title

Flow cytometry

Authorship

Peter Lee peter@transcriptic.com

Motivation

Flow cytometry is a common tool in life science. This instruction provides a non-ambiguous set of parameters for the performance of flow cytometry.

Proposal

{
  "op": "flow_cytometry",
  "dataref": string,
  "samples": [well],
  "lasers": [
    {
      "excitation": wavelength,
      /* laser power, optional */
      "power": milliwatts,
      /*
       * value to scale height and area equivalently,
       * optional
       */
      "area_scaling_factor": number,
      "channels": [
        {
          /*
           * wavelengths are not needed if channel
           * name is FSC or SSC.
           */
          "emission_filter": {
            "shortpass": wavelength,
            "longpass": wavelength,
            "channel_name": string,
          },
          "detector_gain": millivolts,
          /*
           * pulse properties to record
           * optional, default: all true
           * sub-properties are optional, default: true
           */
          "measurements": {
            "area": boolean,
            "height": boolean,
            "width": boolean
          },
          /*
           * channel intensity threshold,
           * events below this threshold
           * will not be recorded, optional
           */
          "trigger_threshold": integer,
          /*
           * operator used to combine threshold,
           * optional, default: "and"
           */
          "trigger_logic": "and | or"
        }
      ]
    }
  ],
  "collection_conditions": {
    "acquisition_volume": volume,
    "flowrate": flowrate,
    /*
     * end_conditions are combined,
     * under "or" logic,
     * optional, if left unset,
     * the aquisition_volume will be used
     * sub-properties are optional
     */
    "stop_criteria": {
      "volume": volume,
      "events": integer,
      "time": time
    },
    "wait_time": time,
    /* mixes before acquisition */
    "mix_cycles": integer,
    "mix_volume": volume,
    /* rinses before acquisition */
    "rinse_cycles": integer
  },
  /*
   * threshold to determine width measurement,
   * optional
   */
  "width_threshold": number,
  /*
   * front and rear window extension,
   * optional
   */
  "window_extension": number,
  /*
   * remove coincident events,
   * optional, default: false
   */
  "remove_coincident_events": boolean
}

Execution

For each flow_cytometry instruction, the channel information will be collected for each sample given the collection conditions specified.

Compatibility

This ASC only specifies new instructions.

Title

Add cover field to Ref specification.

Authorship

Donald Dalton donald@transcriptic.com

Motivation

We should allow creation of Refs that are initially covered.

Proposal

Allow Refs to optionally specify the type of cover they are initially covered with. If no cover is specified the Ref is assumed to be uncovered.

{
  "instructions": [...],
  "refs": {
    "<ref name>": {
      ...,
      "cover": Option<String>,
      ...
    }
  }
}

Available cover types are specified by the vendor.

Compatibility

This is entirely backwards compatible as only new parameters are added. Vendors should indicate if they are unable to respect any of the parameters.

Title

Add read position parameters to spectrophotometry instruction

Authorship

Yang Choo yang@transcriptic.com

Motivation

The z-axis positioning of the probe has a critical impact on the read values returned. This is a common feature that’s exposed in various plate-readers, and a common paradigm is to either manually set the probe-height or allow that to be automatically determined based on a device-specific algorithm.

Proposal

We propose adding optional mode_parameters to the spectrophotometry instruction to address the need outlined in the motivation.

The parameters outlined closely follow conventions from ASC-026.

{
  "op": "spectrophotometry",
  …,
  "groups": [
    {
        /** optional params for all modes */
        "mode_params": {
          /** all params below are optional */
          "read_position": Enum("top", "bottom"),
          "position_z": {
            "manual": {
                "displacement": Length,  // displacement of probe from reference. E.g. if probe is below reference, displacement is negative
                "reference": Enum("plate_bottom", "plate_top", "well_bottom", "well_top")
              },
            "calculated_from_wells": {
                "wells": List(wells),
                "heuristic": Enum("max_mean_read_without_saturation", "closest_distance_without_saturation")
            }
        }
    }
  ]
}

Execution

The position_z parameters control the z-axis positioning of the probe. When set to manual, the probe will be positioned the stated length from the reference point.

If calculated_from_wells is specified, the z-axis distance of the probe will be calculated from the selected wells using the specified heuristic.

closest_distance_without_saturation refers to the z-position which is closest to the reference without obtaining saturated values for any of the specified wells.

max_mean_read_with_saturation refers to the z-position which corresponds to the maximum signal from the mean readings per height, excluding heights with saturated readings. If there is a tie amongst the mean values, the closest distance to the reference is taken.

Only either manual or calculated_from_wells should be specified.

As always, all non-specified parameters will be interpreted as not critical for the experiment execution and will be left to the vendor to decide on the appropriate defaults.

Compatibility

This is entirely backwards compatible as only new parameters are added. Vendors should indicate if they are unable to respect any of the parameters.

Title

Add a store parameter to uncover and a retrieve parameter to cover to allow lids to be explicitly stored and retrieved when not on containers

Authorship

Peter Lee peter@transcriptic.com

Katherine Lai klai@transcriptic.com

Motivation

It’s useful to be able to keep lids from containers when a container needs to be temporarily uncovered and used. These parameters allow us to be able to explicitly specify storing and retrieving lids.

Proposal

{
  "op": "uncover",
  "object": container,
  "store_lid": Boolean, optional, default: false
},
{
  "op": "cover",
  "object": container,
  "lid": <lid type>,
  "retrieve_lid": Boolean, optional, default: false
}

Execution

Vendors are responsible for tracking where lids are and associating them with their respective containers. Only 1 lid can be stored per container at any given time. When “cover” with “retrieve_lid” is specified, the lid from the previous “uncover” with “store_lid” on the same container should be returned to that container. Explicitly, “cover” with “retrieve_lid” must be preceded by a “uncover” with “store_lid”. There may be vendor specific variations to the number of lids that can be stored overall.

Compatibility

These parameters are optional and backwards compatible

Title

Add a shake_after parameter to the Dispense instruction.

Authorship

Rhys Ormond ormondr@transcriptic.com

Motivation

Several reagent dispensers have built in shaking functionality. This shaking is often used to mix liquids and consolidate droplets that may have collected on the sides of the object.

Proposal

The dispense instruction will have an additional, optional parameter shake_after to specify shaking behavior to be executed at the end of the instruction after volume has been dispensed into the wells of the object.

{
  "op": "dispense",
  …
  /* optional */
  "shake_after": {
    “duration”: time
    "frequency": frequency // optional
    "path": enum(“landscape_linear”), // optional, see Appendix: Shake Path
    "amplitude": length // optional
  }
}

The combination of shaking_params available will be determined by the vendor.

Execution

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

Compatibility

This ASC specifies a new field for an existing instruction. Dispense instructions without this optional parameter will duplicate the previous behavior.

Appendix: Shake Path

The shake path parameter will follow existing ASC-028 conventions.

Title

Add spectrophotometry instruction

Authorship

Yang Choo yang@transcriptic.com

Motivation

spectrophotometry refers to an instruction with one or a series of plate reading steps executed on a single plate with the same device. This could be executed once, or at a defined interval, across some total duration.

In biology, this instruction is generally useful for all kinds of experiments such as for optical density reads, or ELISA reads. When executed at a fixed interval, this can be used to capture growth curves, enzyme kinetics, or any other sort of general reaction kinetics measurement.

Proposal

We propose adding an optional spectrophotometry instruction.

The groups list consists of a list of various tasks, each specified by their mode and parameterized by their mode_params. Fields used in mode_params are borrowed from existing ASCs whenever reasonable. Please refer to the previous absorbance, fluorescence, luminescence and incubate ASCs for a more detailed breakdown of the various terms.

If a target_temperature parameter is specified, the reader will be brought up to that environment prior to all tasks. If a shake_before parameter is specified, shaking will be done after reaching the target_temperature (if relevant) and prior to the start of the first group task.

After both temperature and shaking is complete, each task in the groups will be executed in order. The first task will be executed at time 0, and this will be repeated at every specified interval until the total_time is reached.

If total_time is not reached at the end of executing all the tasks in the groups, there will be an implicit wait step until the beginning of the next interval.

{
  "op": "spectrophotometry",
  "dataref": String,
  "object": Container, // required to have a reference for shaking
  /* optional */
  "interval": Time,
  /* optional */
  "num_intervals":Integer,
  /* optional */
  "temperature": Temperature,
  /* optional */
  "shake_before": {
    "duration": Time,
    /* optional parameters below, if the parameter is not specified, will default to device/vendor */
    "frequency": Frequency,
    "amplitude": Length,
    "path": Enum("portrait_linear", "landscape_linear", "cw_orbital", "cw_double_orbital")
  },
  "groups": [
  {
      "mode": Enum("absorbance", "fluorescence", "luminescence", "shake"),
      / ** params for absorbance mode */
      "mode_params": {
        "wells": List(wells),
        "wavelength": List(Wavelength) // if a list of wavelengths is specified, this means reading with multiple wavelengths sequentially at the same well
        /* optional parameters below, if the parameter is not specified, will default to device/vendor */
        "num_flashes": Int, // number of reads per well
        "settle_time": Time // time for liquid to settle after movement, before reading
      }
      /** params for `fluorescence` mode */
      "mode_params": {
        "wells": List(wells),
        "excitation": List({
            /* optional */
            "shortpass": Wavelength,
            "longpass": Wavelength,
            "ideal": Wavelength
        }),
        // if both `short_pass` and `long_pass` are specified a bandpass filter may be used. When a monochromator or laser is used, `target` may be specified instead.
        "emission": List({
            /* optional */
            "shortpass": Wavelength,
            "longpass": Wavelength,
            "ideal": Wavelength
        }),
        /* optional parameters below, if the parameter is not specified, will default to device/vendor */
        "num_flashes": Int,
        "settle_time": Time,
        "lag_time": Time, // time to wait before reading
        "integration_time": Time,
        "gain": float,
        "read_position": Enum("top", "bottom")
      }
      /** params for `luminescence` mode */
      "mode_params": {
        "wells": List(wells), // these wells have to belong to the Ref
        /* optional parameters below, if the parameter is not specified, will default to device/vendor */
        "num_flashes": Int,
        "settle_time": Time,
        "integration_time": Time,
        "gain": float
      }
      /** params for `shake` mode */
      "mode_params": {
        /* optional, only if there is one shake parameter with no specified time. Refer to `Execution` section for more details */
        "duration": Time,
        /* optional parameters below, if the parameter is not specified, will default to device/vendor */
        "frequency": Frequency,
        "amplitude": Length,
        "path": Enum("portrait_linear", "landscape_linear", "cw_orbital", "ccw_orbital", "portrait_down_double_orbital", "landscape_down_double_orbital", "portrait_up_double_orbital", “landscape_up_double_orbital”, “cw_diamond”, “ccw_diamond”), // Refer to appendix for more information on shake path
      }
  }
  ],
}

Execution

For each item in the groups list, the “mode_params” key should only accept values that are relevant for the selected “mode”.

The intention of this method is to support the execution of a spectrophotometry instruction on a single plate with the same device. If the device is unable to support all of the “groups”, then it’s unable to execute this instruction.

The number of group executions shall be equivalent to the total number of intervals (“num_intervals”), and this will be executed every “interval”, starting at 0s. I.e. if “num_intervals” is 3 and “interval” is 10s, reads will be at the 0s, 10s and 20s mark.

To handle the issue of intending to shake for the remainder of the duration until the next read interval but not knowing how long a read takes, one would specify a shake mode with no specified duration. This will be interpreted as shaking for the remainder of the available duration during the current interval.

For example, imagine an instruction with an interval of 10s, with a groups list with two items: “mode: absorbance”, followed by “mode: shake” with no specified duration. Suppose the first absorbance read takes 2s. Since no duration was set for shake, the shaking operation will now be executed for the remaining 8s. Support of shake with no duration at different indices of the groups list may be limited due to vendor support.

Support of multiple types of reading in groups may be limited due to vendor support.

Compatibility

This change is fully backwards compatible as it involves adding in a new instruction. Vendors should indicate if they are unable to respect any of the parameters.

Appendix: Shake Path

The shake path shall follow existing ASC-028 conventions, i.e.

There will be four new shake path types added as part of this ASC

Title

Add a constraint for the ideal execution time between two Autoprotocol events

Authorship

Yang Choo yang@transcriptic.com

Motivation

The existing time constraint implementation only allows for hard time window boundaries. Allowing for ideal time specification enables the scheduler to further optimize to a specific time using a cost function to weigh the impact of deviations on that time. The introduction of an ideal time provides greater control on the schedule and may lead to more consistent schedule execution.

Proposal

We propose to add an “ideal” field to the “time_constraints” top-level field. This is an object with a “value” and “optimization_cost” field

The time difference between two timing points shall occur as close to the “value” field as possible. There will be an associated “optimization_cost” term for calculating a penalty for any deviation. The value specified in the “optimization_cost” will map to the corresponding type of function for calculating the cost.

Previous “more_than” and “less_than” time constraints will remain respected and serve as an effective upper and lower bound.

See the Execution section below for more details.

"time_constraints" : [
  {
  ...,
  /** optional */
  "ideal": {
    "value": time,
    /** optional */
    "optimization_cost": Enum("linear", "squared", "exponential")   // default: "linear"
  },
  ...
  }
]

e.g.

{
  "refs": {
    "foo": { "id": "ct123534", "store": { ... } }
  },
  "instructions": [ ... ],
  "time_constraints": [
    {
      "from": { "ref_start": "foo" },
      "to": { "instruction_end": 1 },
      "ideal": {
        "value": "5:minute",
        "optimization_cost": "linear"
      }
    },
    {
      "from": { "ref_start": "foo" },
      "to": { "instruction_end": 1 },
      "less_than": "7:minute"
    }
  ]
}

Execution

Existing “more_than” and “less_than” time constraints will remain respected, i.e. time constraints will still be violated if the execution time is above the “more_than” or below the “less_than” time constraints. If “more_than” and/or “less_than” time constraints are not present, there will be no hard upper and/or lower bounds respectively.

If applicable, a vendor shall ensure that the time difference between the two timing points and the “ideal” time “value” is minimized across all time constraints for the entire execution according to the “optimization_cost” function. This difference will be calculated according to the vendor’s smallest quantized time unit, which could be in seconds.

The “optimization_cost” strings will follow the following penalty system:

• “linear”: \(|x - value|\)
• “squared”: \((x - value)^2\)
• “exponential”: \(e^{(|x - value|)}\)

See the Mathematical Primer on Ideal Time Constraint Implementation section below for a more detailed primer on how the different time constraints may be interpreted mathematically.

Compatibility

This change is backwards compatible. Users should ensure vendor support of this field.

Mathematical Primer on Ideal Time Constraint Implementation

Generally, if we were to assume the same cost function g is applied to all constraints, the overall cost function to minimize for m total constraints will be: \[ min_{x \epsilon \mathbb{R}} (\sum^m_{i=1} g_i (x_i, d_i, lb_i, ub_i) ) \]

Notation:

• Constraint i
• variable to be minimized x
• “optimization_cost” function g
• “ideal” value d
• “lower_bound” value lb (if present)
• “upper_bound” value ub (if present)

Note that if a “lower_bound” or “upper_bound” is present, we can effectively think of any values beyond those boundaries as mathematically infinite for a minimization problem.

For a “optimization_cost” function which is “linear”, we can think of this mathematically as a piecewise function:

\[ g(x, d, lb, ub) = \left\{ \begin{array}{lr} | x - d| &: lb < x < ub\\ \infty & : x \le lb \\ \infty & : x \ge ub \end{array} \right. \]

Similarly, for an “optimization_cost” function which is “squared”:

\[ g(x, d, lb, ub) = \left\{ \begin{array}{lr} (x - d)^2 &: lb < x < ub\\ \infty & : x \le lb \\ \infty & : x \ge ub \end{array} \right. \]

For an “optimization_cost” function which is “exponential”:

\[ g(x, d, lb, ub) = \left\{ \begin{array}{lr} e^{(|x - d|)} &: lb < x < ub\\ \infty & : x \le lb \\ \infty & : x \ge ub \end{array} \right. \]

Title

Add flowrate and shape to Dispense; modify nozzle_position

Authorship

Rhys Ormond rhys@transcriptic.com

Motivation

When handling liquids of different viscosities, flowrate is an important variable to control for. For example, more viscous liquids must be dispensed at slower speeds to achieve consistent and accurate dispense volumes.

As reagent dispensers have different dispensing nozzle configurations; a shape can be used to enforce a nozzle layout. This has an impact on source container volumes as pre_dispense is specified per-nozzle. A pre_dispense with shape {“rows”: 16, “columns”: 1} will consume twice as much volume as one that has the same pre_dispense volume but half as many nozzles.

When specifying nozzle_position it’s common to want to specify offsets along a single axis rather than all of them. position_z is also commonly specified by devices themselves as the height offset from the holder.

Proposal

We propose adding optional flowrate and shape parameters to dispense. flowrate is intended as a more device-agnostic replacement for dispense_speed, deprecating it. If specified, shape consists of required row and column count fields in addition to an optional format field that specifies the spacing and offsets for the individual nozzles.

We also propose making each of the position_x, position_y, and position_z parameters optional when specifying a nozzle_position.

Finally, we propose that position_z specifies the nozzle offset from the holder rather than the well bottom.

{
  "op": "dispense",
  /* Volume speed, optional */
  "flowrate": flowrate,
  /* 
   * Shape of dispense operation, optional, default:
   *    {
   *      "rows": 8,
   *      "columns": 1,
   *      “format”: “SBS96”
   *    }
   */
  "shape": {
    "rows": integer,
    "columns": integer,
    “format”: string  // optional
  },
  /* 
   * Nozzle position from the center of the well bottom, optional.
   */
  "nozzle_position": {
    "position_x": length,  // optional
    "position_y": length,  // optional
    “position_z”: length  //optional
  }
}

Execution

flowrate, in conjunction with step_size, determines the movement frequency of the dispenser’s peristaltic pump. If not specified then it will default to the middle of range of valid dispensing speeds for the step_size.

shape determines what dispensing devices can execute this instruction in addition to providing context for per-nozzle-specified volumes.

For each component of the nozzle_position if no value is specified then dispense position_x and position_y will default to 0:millimeter; position_z will be default to a vendor-optimized safe offset.

Compatibility

This change is not backwards compatible as it deprecates dispense_speed in favor of flowrate in addition to changing the definition ofnozzle_position.position_z. Vendors should indicate if they are unable to respect any of the new parameters.

Title

Add lid_temperature parameter to thermocycle

Authorship

Yang Choo yang@transcriptic.com

Motivation

Specifying the lid_temperature is a pretty common operation in thermocycling for reducing condensation.

Proposal

This ASC proposes adding lid_temperature as an optional field of a thermocycle instruction e.g.

{
  "op": "thermocycle",
  …,
  "lid_temperature": temperature //optional
}

Execution

If the lid_temperature is not specified, this will be up to the vendor/device to select the right temperature.

The range of accepted lid_temperatures may be dependent on vendor/device support.

Compatibility

This ASC is backwards compatible as it adds a new parameter.

Title

Add mode, temperature and duration fields to seal instruction

Authorship

Yang Choo yang@transcriptic.com

Motivation

There are different mechanisms for sealing plates including thermal and adhesive. For thermal sealing, temperature and duration are critical parameters for ensuring a reproducible plate seal.

Proposal

We propose adding an optional mode field to the seal instruction, where mode describes the different ways of sealing a plate.

For the “thermal” sealing mode, we propose adding the optional temperature and duration fields to the mode_params field.

{
  "op": "seal",
  "object": container,
  "type": "foil",
  /** optional */
  "mode": Enum("thermal", "adhesive"),
  /** The mode params below are specific to the `thermal` mode */
  "mode_params": {
    "temperature": temperature,
    "duration": time
  }
}

Execution

The sealing “mode” key can accept different values depending on the type of sealing methods which the vendor supports.

The “mode_params” key should only accept values which are relevant for the selected “mode”.

Compatibility

This change is fully backwards compatible. Vendors should indicate if they are unable to respect these parameters.

Title

Add a new instruction to count cells in an aliquot

Authorship

Jim Culver jim@transcriptic.com

Motivation

When thawing and/or passaging cells, it is important to plate the cells at a defined density. This requires an accurate count of viable cells in the starting sample, based on presence or absence of some label. This new instruction adds the ability to count cells in an aliquot and will enable new cell-based applications.

Proposal

{
  "op": "count_cells",
  "wells": [well],
  "volume": volume,
  /* optional */
  "labels": [Enum("trypan_blue")],
  "dataref": string
}

Execution

To execute this instruction, one must count the number of cells in each of the specified aliquots, and score each cell for presence or absence of the specified labels (if any). This will consume the specified volume from each aliquot. The returned dataset will report the number of cells per milliliter that were positive for each label, and the number of cells per milliliter that were negative for each label. Currently “trypan_blue” is the only option for label, but future ASCs may add additional labels.

Compatibility

This ASC specifies a new instruction, so there are no issues with reverse compatibility.

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.

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.

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.

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.

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:

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

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.

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.

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.

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 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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"
  }
}

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.