autoprotocol.protocol module

Module containing the main Protocol object and associated functions

copyright

2021 by The Autoprotocol Development Team, see AUTHORS for more details.

license

BSD, see LICENSE for more details

class autoprotocol.protocol.Protocol(refs: Union[Dict[str, autoprotocol.types.ref.Ref], NoneType] = None, instructions: List[autoprotocol.instruction.Instruction] = <factory>, propagate_properties: bool = False, time_constraints: List[autoprotocol.types.protocol.TimeConstraint] = <factory>)

time_constraints: List[autoprotocol.types.protocol.TimeConstraint]

A Protocol is a sequence of instructions to be executed, and a set of containers on which those instructions act.

Parameters

• refs (list(Ref)) – Pre-existing refs that the protocol should be populated with.

• instructions (list(Instruction)) – Pre-existing instructions that the protocol should be populated with.

• propagate_properties (bool, optional) – Whether liquid handling operations should propagate aliquot properties from source to destination wells.

• time_constraints (List(time_constraints)) – Pre-existing time_constraints that the protocol should be populated with.

Examples

Initially, a Protocol has an empty sequence of instructions and no referenced containers. To add a reference to a container, use the ref() method, which returns a Container.

p = Protocol()
my_plate = p.ref("my_plate", id="ct1xae8jabbe6",
                        cont_type="96-pcr", storage="cold_4")

To add instructions to the protocol, use the helper methods in this class

p.transfer(source=my_plate.well("A1"),
           dest=my_plate.well("B4"),
           volume="50:microliter")
p.thermocycle(my_plate, groups=[
              { "cycles": 1,
                "steps": [
                  { "temperature": "95:celsius",
                    "duration": "1:hour"
                  }]
              }])

Autoprotocol Output:

{
  "refs": {
    "my_plate": {
      "id": "ct1xae8jabbe6",
      "store": {
        "where": "cold_4"
      }
    }
  },
  "instructions": [
    {
      "groups": [
        {
          "transfer": [
            {
              "volume": "50.0:microliter",
              "to": "my_plate/15",
              "from": "my_plate/0"
            }
          ]
        }
      ],
      "op": "pipette"
    },
    {
      "volume": "10:microliter",
      "dataref": null,
      "object": "my_plate",
      "groups": [
        {
          "cycles": 1,
          "steps": [
            {
              "duration": "1:hour",
              "temperature": "95:celsius"
            }
          ]
        }
      ],
      "op": "thermocycle"
    }
  ]
}

container_type(shortname: str)

Convert a ContainerType shortname into a ContainerType object.

Parameters

shortname (str) – String representing one of the ContainerTypes in the _CONTAINER_TYPES dictionary.

Returns

Returns a Container type object corresponding to the shortname passed to the function. If a ContainerType object is passed, that same ContainerType is returned.

Return type

ContainerType

Raises

ValueError – If an unknown ContainerType shortname is passed as a parameter.

ref(name: str, id: Optional[str] = None, cont_type: Optional[Union[str, autoprotocol.container_type.ContainerType]] = None, storage: Optional[str] = None, discard: Optional[bool] = None, cover: Optional[str] = None, properties: Optional[Dict[str, str]] = None, ctx_properties: Optional[Dict[str, str]] = None)

Add a Ref object to the dictionary of Refs associated with this protocol and return a Container with the id, container type and storage or discard conditions specified.

Example Usage:

p = Protocol()

# ref a new container (no id specified)
sample_ref_1 = p.ref("sample_plate_1",
                     cont_type="96-pcr",
                     discard=True)

# ref an existing container with a known id
sample_ref_2 = p.ref("sample_plate_2",
                     id="ct1cxae33lkj",
                     cont_type="96-pcr",
                     storage="ambient")

Autoprotocol Output:

{
  "refs": {
    "sample_plate_1": {
      "new": "96-pcr",
      "discard": true
    },
    "sample_plate_2": {
      "id": "ct1cxae33lkj",
      "store": {
        "where": "ambient"
      }
    }
  },
  "instructions": []
}

Parameters

• name (str) – name of the container/ref being created.

• id (str, optional) – id of the container being created, from your organization’s inventory on http://secure.transcriptic.com. Strings representing ids begin with “ct”.

• cont_type (str or ContainerType) – container type of the Container object that will be generated.

• storage (Enum({"ambient", "cold_20", "cold_4", "warm_37"}), optional) – temperature the container being referenced should be stored at after a run is completed. Either a storage condition must be specified or discard must be set to True.

• discard (bool, optional) – if no storage condition is specified and discard is set to True, the container being referenced will be discarded after a run.

• cover (str, optional) – name of the cover which will be on the container/ref

• properties (dict, optional) – mapping of key value properties associated to the Container

• ctx_properties (dict, optional) – mapping of key value properties associated to the Container

Returns

Container object generated from the id and container type provided

Return type

Container

Raises

• RuntimeError – If a container previously referenced in this protocol (existent in refs section) has the same name as the one specified.

• RuntimeError – If no container type is specified.

• RuntimeError – If no valid storage or discard condition is specified.

add_time_constraint(from_dict: autoprotocol.types.protocol.TimeConstraintFromToDict, to_dict: autoprotocol.types.protocol.TimeConstraintFromToDict, less_than: Optional[Union[str, autoprotocol.unit.Unit]] = None, more_than: Optional[Union[str, autoprotocol.unit.Unit]] = None, mirror: bool = False, ideal: Optional[Union[str, autoprotocol.unit.Unit]] = None, optimization_cost: Optional[str] = None)

Constraint the time between two instructions

Add time constraints from from_dict to to_dict. Time constraints guarantee that the time from the from_dict to the to_dict is less than or greater than some specified duration. Care should be taken when applying time constraints as constraints may make some protocols impossible to schedule or run.

Though autoprotocol orders instructions in a list, instructions do not need to be run in the order they are listed and instead depend on the preceding dependencies. Time constraints should be added with such limitations in mind.

Constraints are directional; use mirror=True if the time constraint should be added in both directions. Note that mirroring is only applied to the less_than constraint, as the more_than constraint implies both a minimum delay betweeen two timing points and also an explicit ordering between the two timing points.

Ideal time constraints are sometimes helpful for ensuring that a certain set of operations happen within some specified time. This can be specified by using the ideal parameter. There is an optional optimization_cost parameter associated with ideal time constraints for specifying the penalization system used for calculating deviations from the ideal time. When left unspecified, the optimization_cost function defaults to linear. Please refer to the ASC for more details on how this is implemented.

Example Usage:

plate_1 = protocol.ref("plate_1", id=None, cont_type="96-flat",
                       discard=True)
plate_2 = protocol.ref("plate_2", id=None, cont_type="96-flat",
                       discard=True)

protocol.cover(plate_1)
time_point_1 = protocol.get_instruction_index()

protocol.cover(plate_2)
time_point_2 = protocol.get_instruction_index()

protocol.add_time_constraint(
    {"mark": plate_1, "state": "start"},
    {"mark": time_point_1, "state": "end"},
    less_than = "1:minute")
protocol.add_time_constraint(
    {"mark": time_point_2, "state": "start"},
    {"mark": time_point_1, "state": "start"},
    less_than = "1:minute", mirror=True)

# Ideal time constraint
protocol.add_time_constraint(
    {"mark": time_point_1, "state": "start"},
    {"mark": time_point_2, "state": "end"},
    ideal = "30:second",
    optimization_cost = "squared")

Autoprotocol Output:

{
    "refs": {
        "plate_1": {
            "new": "96-flat",
            "discard": true
        },
        "plate_2": {
            "new": "96-flat",
            "discard": true
        }
    },
    "time_constraints": [
        {
            "to": {
                "instruction_end": 0
            },
            "less_than": "1.0:minute",
            "from": {
                "ref_start": "plate_1"
            }
        },
        {
            "to": {
                "instruction_start": 0
            },
            "less_than": "1.0:minute",
            "from": {
                "instruction_start": 1
            }
        },
        {
            "to": {
                "instruction_start": 1
            },
            "less_than": "1.0:minute",
            "from": {
                "instruction_start": 0
            }
        },
        {
            "from": {
                "instruction_start": 0
            },
            "to": {
                "instruction_end": 1
            },
            "ideal": {
                "value": "5:minute",
                "optimization_cost": "squared"
            }
        }

    ],
    "instructions": [
        {
            "lid": "standard",
            "object": "plate_1",
            "op": "cover"
        },
        {
            "lid": "standard",
            "object": "plate_2",
            "op": "cover"
        }
    ]
}

Parameters

• from_dict (dict) –

  Dictionary defining the initial time constraint condition. Composed of keys: “mark” and “state”

  mark: int or Container

  instruction index of container

  state: “start” or “end”

  specifies either the start or end of the “mark” point

• to_dict (dict) – Dictionary defining the end time constraint condition. Specified in the same format as from_dict

• less_than (str or Unit, optional) – max time between from_dict and to_dict

• more_than (str or Unit, optional) – min time between from_dict and to_dict

• mirror (bool, optional) – choice to mirror the from and to positions when time constraints should be added in both directions (only applies to the less_than constraint)

• ideal (str or Unit, optional) – ideal time between from_dict and to_dict

• optimization_cost (Enum({"linear", "squared", "exponential"}), optional) – cost function used for calculating the penalty for missing the ideal timing

Raises

• ValueError – If an instruction mark is less than 0

• TypeError – If mark is not container or integer

• TypeError – If state not in [‘start’, ‘end’]

• TypeError – If any of ideal, more_than, less_than is not a Unit of the ‘time’ dimension

• KeyError – If to_dict or from_dict does not contain ‘mark’

• KeyError – If to_dict or from_dict does not contain ‘state’

• ValueError – If time is less than ‘0:second’

• ValueError – If optimization_cost is specified but ideal is not

• ValueError – If more_than is greater than less_than

• ValueError – If ideal is smaller than more_than or greater than less_than

• RuntimeError – If from_dict and to_dict are equal

• RuntimeError – If from_dict[“marker”] and to_dict[“marker”] are equal and from_dict[“state”] = “end”

get_instruction_index()

Get index of the last appended instruction

Example Usage:

p = Protocol()
plate_1 = p.ref("plate_1", id=None, cont_type="96-flat",
                discard=True)

p.cover(plate_1)
time_point_1 = p.get_instruction_index()  # time_point_1 = 0

Raises

ValueError – If an instruction index is less than 0

Returns

Index of the preceding instruction

Return type

int

batch_containers(containers: List[autoprotocol.container.Container], batch_in: bool = True, batch_out: bool = False)

Batch containers such that they all enter or exit together.

Example Usage:

plate_1 = protocol.ref("p1", None, "96-pcr", storage="cold_4")
plate_2 = protocol.ref("p2", None, "96-pcr", storage="cold_4")

protocol.batch_containers([plate_1, plate_2])

Autoprotocol Output:

{
  "refs": {
    "p1": {
      "new": "96-pcr",
      "store": {
        "where": "cold_4"
      }
    },
    "p2": {
      "new": "96-pcr",
      "store": {
        "where": "cold_4"
      }
    }
  },
  "time_constraints": [
    {
      "from": {
        "ref_start": "p1"
      },
      "less_than": "0:second",
      "to": {
        "ref_start": "p2"
      }
    },
    {
      "from": {
        "ref_start": "p1"
      },
      "more_than": "0:second",
      "to": {
        "ref_start": "p2"
      }
    }
  ]
}

Parameters

• containers (list(Container)) – Containers to batch

• batch_in (bool, optional) – Batch the entry of containers, default True

• batch_out (bool, optional) – Batch the exit of containers, default False

Raises

• TypeError – If containers is not a list

• TypeError – If containers is not a list of Container object

as_dict()

Return the entire protocol as a dictionary.

Example Usage:

from autoprotocol.protocol import Protocol
import json

p = Protocol()
sample_ref_2 = p.ref("sample_plate_2",
                      id="ct1cxae33lkj",
                      cont_type="96-pcr",
                      storage="ambient")
p.seal(sample_ref_2)
p.incubate(sample_ref_2, "warm_37", "20:minute")

print json.dumps(p.as_dict(), indent=2)

Autoprotocol Output:

{
  "refs": {
    "sample_plate_2": {
      "id": "ct1cxae33lkj",
      "store": {
        "where": "ambient"
      }
    }
  },
  "instructions": [
    {
      "object": "sample_plate_2",
      "op": "seal"
    },
    {
      "duration": "20:minute",
      "where": "warm_37",
      "object": "sample_plate_2",
      "shaking": false,
      "op": "incubate"
    }
  ]
}

Returns

dict with keys “refs” and “instructions” and optionally “time_constraints” and “outs”, each of which contain the “refified” contents of their corresponding Protocol attribute.

Return type

dict

Raises

RuntimeError – If either refs or instructions attribute is empty

liquid_handle_dispense(source: Union[autoprotocol.container.Well, List[autoprotocol.container.Well], List[Tuple[autoprotocol.container.Well, int]]], destination: Union[autoprotocol.container.Well, List[autoprotocol.container.Well], autoprotocol.container.WellGroup, List[autoprotocol.container.WellGroup]], volume: Union[str, autoprotocol.unit.Unit, List[Union[str, autoprotocol.unit.Unit]]], rows: int = 8, columns: int = 1, method: autoprotocol.liquid_handle.dispense.Dispense = <class 'autoprotocol.liquid_handle.dispense.Dispense'>, liquid: autoprotocol.liquid_handle.liquid_class.LiquidClass = <class 'autoprotocol.liquid_handle.liquid_class.LiquidClass'>, model: Optional[str] = None, chip_material: Optional[str] = None, nozzle: Optional[str] = None)

Generates a liquid_handle dispense

Dispenses liquid from a source well to a group of destination wells.

Notes

Some liquidClass parameters including volume calibration and flowrate are not yet supported. There are currently no plans to support liquid level detection and its corresponding thresholds for this mode.

Parameters

• source (Well or list(Well) or list(tuple(Well, int))) – Well(s) to transfer liquid from. If the source is given as a list of (Well, int) tuples (ie: source=[(Well, 2), (Well, 5)]) the Well is the source well and the int is the number of dispense chips to use from the specified source.

• destination (Well or WellGroup or list(Well) or list(WellGroup)) – Well(s) to transfer liquid to. If specifying more than a Well or WellGroup the list of destinations must match the number of chips specified in the source tuple.

• volume (str or Unit or list(str) or list(Unit)) – Volume(s) of liquid to be transferred from source well to destination wells. The number of volumes specified must correspond to the number of destination wells. If specifying more than one volume to be used for all dispenses, the list of volumes must match the length of destinations.

• rows (int, optional) – Number of rows to be concurrently transferred

• columns (int, optional) – Number of columns to be concurrently transferred

• liquid (LiquidClass or list(LiquidClass), optional) – Type(s) of liquid to be dispensed. This affects aspirate and dispense behavior including flowrates and physical movements. If the number of Dispense classes specified is more than one then number specified must match the length of sources.

• method (Dispense or list(Dispense), optional) – Integrates with the specified liquid to define a set of physical movements. If the number of Dispense classes specified is more than one then number specified must match the length of sources.

• model (str, optional) – Tempest chip model, currently only support “high_volume”.

• chip_material (str, optional) – Tempest chip material, support “silicone” and “pfe”, default is “silicon”.

• nozzle (str, optional) – Tempest nozzle type, currently only support “standard”. The three chip parameters: model, chip_material, and nozzle will be used in liquid handle mode_params to allow tempest chip specification.

Returns

Returns a autoprotocol.instruction.LiquidHandle instruction created from the specified parameters.

Return type

LiquidHandle

Raises

• ValueError – if source is not a Well or list((Well, int))

• ValueError – if destination and volumes are not of the same length

• ValueError – if model is not high_volume

• ValueError – if nozzle is not standard

• ValueError – if chip_material is not in silicone or pfe

• TypeError – if volume is not one of the defined allowable types

Examples

A single volume dispense to a single column

from autoprotocol import Protocol

p = Protocol()
source = p.ref("source", cont_type="conical-50", discard=True)
destination = p.ref("destination", cont_type="96-flat", discard=True)
p.liquid_handle_dispense(
    source=source.well(0),
    destination=destination.well(0),
    volume="5:ul"
)

A single volume dispense to a whole 384 well plate

from autoprotocol import Protocol

p = Protocol()
source = p.ref("source", cont_type="conical-50", discard=True)
destination = p.ref("destination", cont_type="384-flat", discard=True)
p.liquid_handle_dispense(
    source=source.well(0),
    destination=destination.wells_from(0, 48),
    volume="5:ul"
)

Dispensing a volume gradient across a plate

from autoprotocol import Unit
from autoprotocol import Protocol

p = Protocol()
source = p.ref("source", cont_type="conical-50", discard=True)
destination = p.ref("destination", cont_type="96-flat", discard=True)
p.liquid_handle_dispense(
    source=source.well(0),
    destination=destination.wells_from(0, 12),
    volume=[Unit(_, "uL") for _ in range(1, 13)]
)

Using multiple chips in a single source tube. The following example will dispense 100:microliters to the first 3 columns of the destination plate.

from autoprotocol import Unit
from autoprotocol import Protocol

p = Protocol()
source = p.ref("source", cont_type="micro-2.0", discard=True).well(0)
destination = p.ref("destination", cont_type="96-flat", discard=True)

intake_hoses = 3
number_dispense_columns = 5
source: List[Tuple[Well, int]] = [(source, intake_hoses)]

destination = [destination.wells_from(0, num_dispense_columns)]
self.protocol.liquid_handle_dispense(
    source=source,
    destination=destination,
    volume='100:microliter',
)

See also

autoprotocol.liquid_handle.Dispense

Base liquid handling method for dispense operations

store(container: autoprotocol.container.Container, condition: str)

Manually adjust the storage destiny for a container used within this protocol.

Parameters

• container (Container) – Container used within this protocol

• condition (str) – New storage destiny for the specified Container

Raises

• TypeError – If container argument is not a Container object

• RuntimeError – If the container passed is not already present in self.refs

acoustic_transfer(source: Union[autoprotocol.container.Well, List[autoprotocol.container.Well], autoprotocol.container.WellGroup], dest: Union[autoprotocol.container.Well, List[autoprotocol.container.Well], autoprotocol.container.WellGroup], volume: Union[str, autoprotocol.unit.Unit], one_source: bool = False, droplet_size: Union[str, autoprotocol.unit.Unit] = '25:nanoliter')

Specify source and destination wells for transferring liquid via an acoustic liquid handler. Droplet size is usually device-specific.

Example Usage:

p.acoustic_transfer(
    echo.wells(0,1).set_volume("12:nanoliter"),
    plate.wells_from(0,5), "4:nanoliter", one_source=True)

Autoprotocol Output:

"instructions": [
    {
        "groups": [
            {
                "transfer": [
                    {
                        "volume": "0.004:microliter",
                        "to": "plate/0",
                        "from": "echo_plate/0"
                    },
                    {
                        "volume": "0.004:microliter",
                        "to": "plate/1",
                        "from": "echo_plate/0"
                    },
                    {
                        "volume": "0.004:microliter",
                        "to": "plate/2",
                        "from": "echo_plate/0"
                    },
                    {
                        "volume": "0.004:microliter",
                        "to": "plate/3",
                        "from": "echo_plate/1"
                    },
                    {
                        "volume": "0.004:microliter",
                        "to": "plate/4",
                        "from": "echo_plate/1"
                    }
                ]
            }
        ],
        "droplet_size": "25:microliter",
        "op": "acoustic_transfer"
    }
]

Parameters

• source (Well or WellGroup or list(Well)) – Well or wells to transfer liquid from. If multiple source wells are supplied and one_source is set to True, liquid will be transferred from each source well specified as long as it contains sufficient volume. Otherwise, the number of source wells specified must match the number of destination wells specified and liquid will be transferred from each source well to its corresponding destination well.

• dest (Well or WellGroup or list(Well)) – Well or WellGroup to which to transfer liquid. The number of destination wells must match the number of source wells specified unless one_source is set to True.

• volume (str or Unit or list) – The volume(s) of liquid to be transferred from source wells to destination wells. Volume can be specified as a single string or Unit, or can be given as a list of volumes. The length of a list of volumes must match the number of destination wells given unless the same volume is to be transferred to each destination well.

• one_source (bool, optional) – Specify whether liquid is to be transferred to destination wells from a group of wells all containing the same substance.

• droplet_size (str or Unit, optional) – Volume representing a droplet_size. The volume of each transfer group should be a multiple of this volume.

Returns

Returns the autoprotocol.instruction.AcousticTransfer instruction created from the specified parameters

Return type

AcousticTransfer

Raises

• TypeError – Incorrect input types, e.g. source/dest are not Well or WellGroup or list of Well; or container_type does not have ‘acoustic_transfer’ capability.

• RuntimeError – Incorrect length for source and destination

• RuntimeError – Transfer volume not being a multiple of droplet size

• RuntimeError – Insufficient volume in source wells

illuminaseq(flowcell: str, lanes: List[autoprotocol.types.protocol.IlluminaSeqLane], sequencer: str, mode: str, index: str, library_size: int, dataref: str, cycles: Optional[str] = None)

Load aliquots into specified lanes for Illumina sequencing. The specified aliquots should already contain the appropriate mix for sequencing and require a library concentration reported in ng/uL.

Example Usage:

p = Protocol()
sample_wells = p.ref(
    "test_plate", None, "96-pcr", discard=True).wells_from(0, 8)

p.illuminaseq(
    "PE",
    [
        {"object": sample_wells[0], "library_concentration": 1.0},
        {"object": sample_wells[1], "library_concentration": 5.32},
        {"object": sample_wells[2], "library_concentration": 54},
        {"object": sample_wells[3], "library_concentration": 20},
        {"object": sample_wells[4], "library_concentration": 23},
        {"object": sample_wells[5], "library_concentration": 23},
        {"object": sample_wells[6], "library_concentration": 21},
        {"object": sample_wells[7], "library_concentration": 62}
    ],
    "hiseq", "rapid", 'none', 250, "my_illumina")

Autoprotocol Output:

"instructions": [
    {
        "dataref": "my_illumina",
        "index": "none",
        "lanes": [
            {
                "object": "test_plate/0",
                "library_concentration": 1
            },
            {
                "object": "test_plate/1",
                "library_concentration": 5.32
            },
            {
                "object": "test_plate/2",
                "library_concentration": 54
            },
            {
                "object": "test_plate/3",
                "library_concentration": 20
            },
            {
                "object": "test_plate/4",
                "library_concentration": 23
            },
            {
                "object": "test_plate/5",
                "library_concentration": 23
            },
            {
                "object": "test_plate/6",
                "library_concentration": 21
            },
            {
                "object": "test_plate/7",
                "library_concentration": 62
            }
        ],
        "flowcell": "PE",
        "mode": "mid",
        "sequencer": "hiseq",
        "library_size": 250,
        "op": "illumina_sequence"
    }
]

Parameters

• flowcell (str) – Flowcell designation: “SR” or ” “PE”

• lanes (list(dict)) –

  "lanes": [
  {
      "object": aliquot, Well,
      "library_concentration": decimal, // ng/uL
  },
  {...}]
  

• sequencer (str) – Sequencer designation: “miseq”, “hiseq” or “nextseq”

• mode (str) – Mode designation: “rapid”, “mid” or “high”

• index (str) – Index designation: “single”, “dual” or “none”

• library_size (int) – Library size expressed as an integer of basepairs

• dataref (str) – Name of sequencing dataset that will be returned.

• cycles (Enum({"read_1", "read_2", "index_1", "index_2"})) – Parameter specific to Illuminaseq read-length or number of sequenced bases. Refer to the ASC for more details

Returns

Returns the autoprotocol.instruction.IlluminaSeq instruction created from the specified parameters

Return type

IlluminaSeq

Raises

• TypeError – If index and dataref are not of type str.

• TypeError – If library_concentration is not a number.

• TypeError – If library_size is not an integer.

• ValueError – If flowcell, sequencer, mode, index are not of type a valid option.

• ValueError – If number of lanes specified is more than the maximum lanes of the specified type of sequencer.

• KeyError – Invalid keys specified for cycles parameter

sangerseq(cont: Union[autoprotocol.container.Container, str], wells: Union[autoprotocol.container.Well, List[autoprotocol.container.Well], autoprotocol.container.WellGroup], dataref: str, type: str = 'standard', primer: Optional[autoprotocol.container.Container] = None)

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

Example Usage:

p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-flat",
                     storage="warm_37")

p.sangerseq(sample_plate,
            sample_plate.wells_from(0,5).indices(),
            "seq_data_022415")

Autoprotocol Output:

"instructions": [
    {
        "dataref": "seq_data_022415",
        "object": "sample_plate",
        "wells": [
            "A1",
            "A2",
            "A3",
            "A4",
            "A5"
        ],
        "op": "sanger_sequence"
    }
]

Parameters

• cont (Container or str) – Container with well(s) that contain material to be sequenced.

• wells (list(Well) or WellGroup or Well) – WellGroup of wells to be measured or a list of well references in the form of [“A1”, “B1”, “C5”, …]

• dataref (str) – Name of sequencing dataset that will be returned.

• type (Enum({"standard", "rca"})) – Sanger sequencing type

• primer (Container, optional) – Tube containing sufficient primer for all RCA reactions. This field will be ignored if you specify the sequencing type as “standard”. Tube containing sufficient primer for all RCA reactions

Returns

Returns the autoprotocol.instruction.SangerSeq instruction created from the specified parameters

Return type

SangerSeq

Raises

• RuntimeError – No primer location specified for rca sequencing type

• ValueError – Wells belong to more than one container

• TypeError – Invalid input type for wells

dispense(ref: autoprotocol.container.Container, reagent: Union[str, autoprotocol.container.Well], columns: List[autoprotocol.types.protocol.DispenseColumn], is_resource_id: bool = False, step_size: Union[str, autoprotocol.unit.Unit] = '5:uL', flowrate: Optional[Union[str, autoprotocol.unit.Unit]] = None, nozzle_position: Optional[autoprotocol.types.protocol.DispenseNozzlePosition] = None, pre_dispense: Optional[Union[str, autoprotocol.unit.Unit]] = None, shape: Optional[autoprotocol.types.protocol.DispenseShape] = None, shake_after: Optional[autoprotocol.types.protocol.DispenseShakeAfter] = None)

Dispense specified reagent to specified columns.

Example Usage:

from autoprotocol.liquid_handle.liquid_handle_builders import *
from autoprotocol.instructions import Dispense
from autoprotocol import Protocol

p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-flat",
                     storage="warm_37")

p.dispense(sample_plate,
           "water",
           Dispense.builders.columns(
               [Dispense.builders.column(0, "10:uL"),
                Dispense.builders.column(1, "20:uL"),
                Dispense.builders.column(2, "30:uL"),
                Dispense.builders.column(3, "40:uL"),
                Dispense.builders.column(4, "50:uL")
               ])
           )

p.dispense(
    sample_plate,
    "water",
    Dispense.builders.columns(
        [Dispense.builders.column(0, "10:uL")]
    ),
    Dispense.builders.nozzle_position(
        position_x=Unit("1:mm"),
        position_y=Unit("2:mm"),
        position_z=Unit("20:mm")
    ),
    shape_builder(
        rows=8, columns=1, format="SBS96"
    )
)

Autoprotocol Output:

"instructions": [
    {
        "reagent": "water",
        "object": "sample_plate",
        "columns": [
            {
                "column": 0,
                "volume": "10:microliter"
            },
            {
                "column": 1,
                "volume": "20:microliter"
            },
            {
                "column": 2,
                "volume": "30:microliter"
            },
            {
                "column": 3,
                "volume": "40:microliter"
            },
            {
                "column": 4,
                "volume": "50:microliter"
            }
        ],
        "op": "dispense"
    },
    {
        "reagent": "water",
        "object": "sample_plate",
        "columns": [
            {
                "column": 0,
                "volume": "10:microliter"
            }
        ],
        "nozzle_position" : {
            "position_x" : "1:millimeter",
            "position_y" : "2:millimeter",
            "position_z" : "20:millimeter"
        },
        "shape" : {
            "rows" : 8,
            "columns" : 1,
            "format" : "SBS96"
        }
        "op": "dispense"
    },
]

Parameters

• ref (Container) – Container for reagent to be dispensed to.

• reagent (str or well) – Reagent to be dispensed. Use a string to specify the name or resource_id (see below) of the reagent to be dispensed. Alternatively, use a well to specify that the dispense operation must be executed using a specific aliquot as the dispense source.

• columns (list(dict("column": int, "volume": str/Unit))) – Columns to be dispensed to, in the form of a list(dict) specifying the column number and the volume to be dispensed to that column. Columns are expressed as integers indexed from 0. [{“column”: <column num>, “volume”: <volume>}, …]

• is_resource_id (bool, optional) – If true, interprets reagent as a resource ID

• step_size (str or Unit, optional) – Specifies that the dispense operation must be executed using a peristaltic pump with the given step size. Note that the volume dispensed in each column must be an integer multiple of the step_size. Currently, step_size must be one of 5 uL, 0.5 uL, 0.05 uL. If set to None, will use vendor specified defaults.

• flowrate (str or Unit, optional) – The rate at which liquid is dispensed into the ref in units of volume/time.

• nozzle_position (dict, optional) – A dict represent nozzle offsets from the bottom middle of the plate’s wells. see Dispense.builders.nozzle_position; specified as {“position_x”: Unit, “position_y”: Unit, “position_z”: Unit}.

• pre_dispense (str or Unit, optional) – The volume of reagent to be dispensed per-nozzle into waste immediately prior to dispensing into the ref.

• shape (dict, optional) – The shape of the dispensing head to be used for the dispense. See liquid_handle_builders.shape_builder; specified as {“rows”: int, “columns”: int, “format”: str} with format being a valid SBS format.

• shake_after (dict, optional) – Parameters that specify how a plate should be shaken at the very end of the instruction execution. See Dispense.builders.shake_after.

Returns

Returns the autoprotocol.instruction.Dispense instruction created from the specified parameters

Return type

Dispense

Raises

• TypeError – Invalid input types, e.g. ref is not of type Container

• ValueError – Columns specified is invalid for this container type

• ValueError – Invalid step-size given

• ValueError – Invalid pre-dispense volume

dispense_full_plate(ref: autoprotocol.container.Container, reagent: Union[str, autoprotocol.container.Well], volume: Union[str, autoprotocol.unit.Unit], is_resource_id: bool = False, step_size: Union[str, autoprotocol.unit.Unit] = '5:uL', flowrate: Optional[Union[str, autoprotocol.unit.Unit]] = None, nozzle_position: Optional[autoprotocol.types.protocol.DispenseNozzlePosition] = None, pre_dispense: Optional[Union[str, autoprotocol.unit.Unit]] = None, shape: Optional[autoprotocol.types.protocol.DispenseShape] = None, shake_after: Optional[autoprotocol.types.protocol.DispenseShakeAfter] = None)

Dispense the specified amount of the specified reagent to every well of a container using a reagent dispenser.

Example Usage:

p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-flat",
                     storage="warm_37")

p.dispense_full_plate(sample_plate,
                      "water",
                      "100:microliter")

Autoprotocol Output:

"instructions": [
    {
        "reagent": "water",
        "object": "sample_plate",
        "columns": [
            {
                "column": 0,
                "volume": "100:microliter"
            },
            {
                "column": 1,
                "volume": "100:microliter"
            },
            {
                "column": 2,
                "volume": "100:microliter"
            },
            {
                "column": 3,
                "volume": "100:microliter"
            },
            {
                "column": 4,
                "volume": "100:microliter"
            },
            {
                "column": 5,
                "volume": "100:microliter"
            },
            {
                "column": 6,
                "volume": "100:microliter"
            },
            {
                "column": 7,
                "volume": "100:microliter"
            },
            {
                "column": 8,
                "volume": "100:microliter"
            },
            {
                "column": 9,
                "volume": "100:microliter"
            },
            {
                "column": 10,
                "volume": "100:microliter"
            },
            {
                "column": 11,
                "volume": "100:microliter"
            }
        ],
        "op": "dispense"
    }
]

Parameters

• ref (Container) – Container for reagent to be dispensed to.

• reagent (str or Well) – Reagent to be dispensed. Use a string to specify the name or resource_id (see below) of the reagent to be dispensed. Alternatively, use a well to specify that the dispense operation must be executed using a specific aliquot as the dispense source.

• volume (Unit or str) – Volume of reagent to be dispensed to each well

• is_resource_id (bool, optional) – If true, interprets reagent as a resource ID

• step_size (str or Unit, optional) – Specifies that the dispense operation must be executed using a peristaltic pump with the given step size. Note that the volume dispensed in each column must be an integer multiple of the step_size. Currently, step_size must one of 5 uL, 0.5 uL, 0.05 uL. If set to None, will use vendor specified defaults.

• flowrate (str or Unit, optional) – The rate at which liquid is dispensed into the ref in units of volume/time.

• nozzle_position (dict, optional) – A dict represent nozzle offsets from the bottom middle of the plate’s wells. see Dispense.builders.nozzle_position; specified as {“position_x”: Unit, “position_y”: Unit, “position_z”: Unit}.

• pre_dispense (str or Unit, optional) – The volume of reagent to be dispensed per-nozzle into waste immediately prior to dispensing into the ref.

• shape (dict, optional) – The shape of the dispensing head to be used for the dispense. See liquid_handle_builders.shape_builder; specified as {“rows”: int, “columns”: int, “format”: str} with format being a valid SBS format.

• shake_after (dict, optional) – Parameters that specify how a plate should be shaken at the very end of the instruction execution. See Dispense.builders.shake_after.

Returns

Returns the autoprotocol.instruction.Dispense instruction created from the specified parameters

Return type

Dispense

spin(ref: autoprotocol.container.Container, acceleration: str, duration: Union[str, autoprotocol.unit.Unit], flow_direction: Optional[str] = None, spin_direction: Optional[List[str]] = None)

Apply acceleration to a container.

Example Usage:

p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-flat",
                     storage="warm_37")

p.spin(sample_plate, "1000:g", "20:minute", flow_direction="outward")

Autoprotocol Output:

"instructions": [
    {
        "acceleration": "1000:g",
        "duration": "20:minute",
        "flow_direction": "outward",
        "spin_direction": [
            "cw",
            "ccw"
        ]
        "object": "sample_plate",
        "op": "spin"
    }
]

Parameters

• ref (Container) – The container to be centrifuged.

• acceleration (str) – Acceleration to be applied to the plate, in units of g or meter/second^2.

• duration (str or Unit) – Length of time that acceleration should be applied.

• flow_direction (str) – Specifies the direction contents will tend toward with respect to the container. Valid directions are “inward” and “outward”, default value is “inward”.

• spin_direction (list(str)) – A list of “cw” (clockwise), “cww” (counterclockwise). For each element in the list, the container will be spun in the stated direction for the set “acceleration” and “duration”. Default values are derived from the “flow_direction” parameter. If “flow_direction” is “outward”, then “spin_direction” defaults to [“cw”, “ccw”]. If “flow_direction” is “inward”, then “spin_direction” defaults to [“cw”].

Returns

Returns the autoprotocol.instruction.Spin instruction created from the specified parameters

Return type

Spin

Raises

• TypeError – If ref to spin is not of type Container.

• TypeError – If spin_direction or flow_direction are not properly formatted.

• ValueError – If spin_direction or flow_direction do not have appropriate values.

agitate(ref: autoprotocol.container.Container, mode: autoprotocol.types.protocol.AgitateMode, speed: Union[str, autoprotocol.unit.Unit], duration: Union[str, autoprotocol.unit.Unit], temperature: Optional[Union[str, autoprotocol.unit.Unit]] = None, mode_params: Optional[autoprotocol.types.protocol.AgitateModeParams] = None)

Agitate a container in a specific condition for a given duration. If temperature is not specified, container is agitated at ambient temperature by default.

Example Usage:

p = Protocol()
plate = p.ref("test pcr plate", id=None, cont_type="96-pcr",
              storage="cold_4")
p.agitate(
    ref = plate,
    mode="vortex",
    speed="1000:rpm",
    duration="5:minute",
    temperature="25:celsius"
)

Autoprotocol Output:

"instructions" : [
    {
        "object": "test pcr plate",
        "mode": "vortex",
        "speed": "1000:rpm",
        "duration": "5:minute",
        "temperature": "25:celsius",
        "op": "agitate"
    }
]

Parameters

• ref (Container) – Container to be agitated

• mode (str) – Mode by which to agitate container

• speed (str or Unit) – Speed at which to agitate container

• duration (str or Unit) – Specify the duration to agitate for

• temperature (Unit or str, optional) – Specify target temperature to agitate container at. Defaults to ambient

• mode_params (dict, optional) – Dictionary containing mode params for agitation modes

Returns

returns a autoprotocol.instruction.Agitate instruction created from the specified parameters

Return type

Agitate

Raises

• ValueError – If ref provided is not of type Container

• ValueError – If speed is less than 0 rpm

• ValueError – if duration is less than 0 minutes

• ValueError – If mode_params not specified for mode stir_bar

• ValueError – If valid keys for mode_params used for stir_bar are not included

• ValueError – If wells specified in mode_params are not in the same container

• ValueError – If bar_shape is not valid

• ValueError – If bar_length is less than 0 millimeter

• ValueError – If mode used does not require mode_params

• TypeError – If ref cannot be undergo agitate mode roll or invert

thermocycle(ref: autoprotocol.container.Container, groups: List[Union[autoprotocol.types.protocol.ThermocycleTemperature, autoprotocol.types.protocol.ThermocycleTemperatureGradient]], volume: Optional[Union[str, autoprotocol.unit.Unit]] = '10:microliter', dataref: Optional[str] = None, dyes: Optional[Dict[str, str]] = None, melting_start: Optional[Union[str, autoprotocol.unit.Unit]] = None, melting_end: Optional[Union[str, autoprotocol.unit.Unit]] = None, melting_increment: Optional[Union[str, autoprotocol.unit.Unit]] = None, melting_rate: Optional[Union[str, autoprotocol.unit.Unit]] = None, lid_temperature: Optional[Union[str, autoprotocol.unit.Unit]] = None)

Append a Thermocycle instruction to the list of instructions, with groups is a list(dict) in the form of:

"groups": [{
    "cycles": integer,
    "steps": [
        {
            "duration": duration,
            "temperature": temperature,
            "read": boolean // optional (default false)
        },
        {
            "duration": duration,
            "gradient": {
                "top": temperature,
                "bottom": temperature
            },
            "read": boolean // optional (default false)
        }
    ]
}],

Thermocycle can also be used for either conventional or row-wise gradient PCR as well as qPCR. Refer to the examples below for details.

Example Usage:

To thermocycle a container according to the protocol:

• 1 cycle:

  • 95 degrees for 5 minutes

• 30 cycles:

  • 95 degrees for 30 seconds

  • 56 degrees for 20 seconds

  • 72 degrees for 30 seconds

• 1 cycle:

  • 72 degrees for 10 minutes

• 1 cycle:

  • 4 degrees for 30 seconds

• all cycles: Lid temperature at 97 degrees

from instruction import Thermocycle

p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-pcr",
                     storage="warm_37")

# a plate must be sealed before it can be thermocycled
p.seal(sample_plate)

p.thermocycle(
    sample_plate,
    [
        Thermocycle.builders.group(
            steps=[
                Thermocycle.builders.step("95:celsius", "5:minute")
            ]
        ),
        Thermocycle.builders.group(
            steps=[
                Thermocycle.builders.step("95:celsius", "30:s"),
                Thermocycle.builders.step("56:celsius", "20:s"),
                Thermocycle.builders.step("72:celsius", "20:s"),
            ],
            cycles=30
        ),
        Thermocycle.builders.group(
            steps=[
                Thermocycle.builders.step("72:celsius", "10:minute")
            ]
        ),
        Thermocycle.builders.group(
            steps=[
                Thermocycle.builders.step("4:celsius", "30:s")
            ]
        )
    ],
    lid_temperature="97:celsius"
)

Autoprotocol Output:

"instructions": [
    {
        "object": "sample_plate",
        "op": "seal"
    },
    {
        "volume": "10:microliter",
        "dataref": null,
        "object": "sample_plate",
        "groups": [
            {
                "cycles": 1,
                "steps": [
                    {
                        "duration": "5:minute",
                        "temperature": "95:celsius"
                    }
                ]
            },
            {
                "cycles": 30,
                "steps": [
                    {
                        "duration": "30:second",
                        "temperature": "95:celsius"
                    },
                    {
                        "duration": "20:second",
                        "temperature": "56:celsius"
                    },
                    {
                        "duration": "20:second",
                        "temperature": "72:celsius"
                    }
                ]
            },
            {
                "cycles": 1,
                "steps": [
                    {
                        "duration": "10:minute",
                        "temperature": "72:celsius"
                    }
                ]
            },
            {
                "cycles": 1,
                "steps": [
                    {
                        "duration": "30:second",
                        "temperature": "4:celsius"
                    }
                ]
            }
        ],
        "op": "thermocycle"
    }
]

To gradient thermocycle a container according to the protocol:

• 1 cycle:

  • 95 degrees for 5 minutes

• 30 cycles:

  • 95 degrees for 30 seconds

  Top Row: * 65 degrees for 20 seconds Bottom Row: * 55 degrees for 20 seconds

  • 72 degrees for 30 seconds

• 1 cycle:

  • 72 degrees for 10 minutes

p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-pcr",
                     storage="warm_37")

# a plate must be sealed before it can be thermocycled
p.seal(sample_plate)

p.thermocycle(
    sample_plate,
    [
        Thermocycle.builders.group(
            steps=[
                Thermocycle.builders.step("95:celsius", "5:minute")
            ]
        ),
        Thermocycle.builders.group(
            steps=[
                Thermocycle.builders.step("95:celsius", "30:s"),
                Thermocycle.builders.step(
                    {"top": "65:celsius", "bottom": "55:celsius"},
                    "20:s"
                ),
                Thermocycle.builders.step("72:celsius", "20:s"),
            ],
            cycles=30
        ),
        Thermocycle.builders.group(
            steps=[
                Thermocycle.builders.step("72:celsius", "10:minute")
            ]
        )
    ]
)

To conduct a qPCR, at least one dye type and the dataref field has to be specified. The example below uses SYBR dye and the following temperature profile:

• 1 cycle:

  • 95 degrees for 3 minutes

• 40 cycles:

  • 95 degrees for 10 seconds

  • 60 degrees for 30 seconds (Read during extension)

p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-pcr",
                     storage="warm_37")

# a plate must be sealed before it can be thermocycled
p.seal(sample_plate)

p.thermocycle(
    sample_plate,
    [
        Thermocycle.builders.group(
            steps=[
                Thermocycle.builders.step("95:celsius", "3:minute")
            ]
        ),
        Thermocycle.builders.group(
            steps=[
                Thermocycle.builders.step(
                    "95:celsius",
                    "10:second",
                    read=False
                ),
                Thermocycle.builders.step(
                    "95:celsius",
                    "10:second",
                    read=True
                )
            ],
            cycles=40
        )
    ],
    dataref = "my_qpcr_data",
    dyes = {"SYBR": sample_plate.all_wells().indices()}
)

Parameters

• ref (Container) – Container to be thermocycled.

• groups (list(dict)) – List of thermocycling instructions formatted as above

• volume (str or Unit, optional) – Volume contained in wells being thermocycled

• dataref (str, optional) – Name of dataref representing read data if performing qPCR

• dyes (dict, optional) – Dictionary mapping dye types to the wells they’re used in

• melting_start (str or Unit, optional) – Temperature at which to start the melting curve.

• melting_end (str or Unit, optional) – Temperature at which to end the melting curve.

• melting_increment (str or Unit, optional) – Temperature by which to increment the melting curve. Accepted increment values are between 0.1 and 9.9 degrees celsius.

• melting_rate (str or Unit, optional) – Specifies the duration of each temperature step in the melting curve.

• lid_temperature (str or Unit, optional) – Specifies the lid temperature throughout the duration of the thermocycling instruction

Returns

Returns the autoprotocol.instruction.Thermocycle instruction created from the specified parameters

Return type

Thermocycle

Raises

• AttributeError – If groups are not properly formatted

• TypeError – If ref to thermocycle is not of type Container.

• ValueError – Container specified cannot be thermocycled

• ValueError – Lid temperature is not within bounds

incubate(ref: Union[autoprotocol.container.Container, str], where: str, duration: Union[str, autoprotocol.unit.Unit], shaking: bool = False, co2: float = 0, uncovered: bool = False, target_temperature: Optional[Union[str, autoprotocol.unit.Unit]] = None, shaking_params: Optional[autoprotocol.types.protocol.IncubateShakingParams] = None)

Move plate to designated thermoisolater or ambient area for incubation for specified duration.

Example Usage:

p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-pcr",
                     storage="warm_37")

# a plate must be sealed/covered before it can be incubated
p.seal(sample_plate)
p.incubate(sample_plate, "warm_37", "1:hour", shaking=True)

Autoprotocol Output:

"instructions": [
    {
       "object": "sample_plate",
       "op": "seal"
    },
    {
        "duration": "1:hour",
        "where": "warm_37",
        "object": "sample_plate",
        "shaking": true,
        "op": "incubate",
        "co2_percent": 0
    }
  ]

Parameters

• ref (Ref or str) – The container to be incubated

• where (Enum({"ambient", "warm_37", "cold_4", "cold_20", "cold_80"})) – Temperature at which to incubate specified container

• duration (Unit or str) – Length of time to incubate container

• shaking (bool, optional) – Specify whether or not to shake container if available at the specified temperature

• co2 (Number, optional) – Carbon dioxide percentage

• uncovered (bool, optional) – Specify whether the container should be uncovered during incubation

• target_temperature (Unit or str, optional) – Specify a target temperature for a device (eg. an incubating block) to reach during the specified duration.

• shaking_params (dict, optional) – Specify “path” and “frequency” of shaking parameters to be used with compatible devices (eg. thermoshakes)

Returns

Returns the autoprotocol.instruction.Incubate instruction created from the specified parameters

Return type

Incubate

Raises

• TypeError – Invalid input types given, e.g. ref is not of type Container

• RuntimeError – Incubating uncovered in a location which is shaking

absorbance(ref: Union[str, autoprotocol.container.Container], wells: Union[autoprotocol.container.Well, List[autoprotocol.container.Well], autoprotocol.container.WellGroup], wavelength: Union[str, autoprotocol.unit.Unit], dataref: str, flashes: int = 25, incubate_before: Optional[autoprotocol.types.protocol.PlateReaderIncubateBefore] = None, temperature: Optional[Union[str, autoprotocol.unit.Unit]] = None, settle_time: Optional[Union[str, autoprotocol.unit.Unit]] = None)

Read the absorbance for the indicated wavelength for the indicated wells. Append an Absorbance instruction to the list of instructions for this Protocol object.

Example Usage:

p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-flat",
                     storage="warm_37")

p.absorbance(sample_plate, sample_plate.wells_from(0,12),
             "600:nanometer", "test_reading", flashes=50)

Autoprotocol Output:

"instructions": [
    {
        "dataref": "test_reading",
        "object": "sample_plate",
        "wells": [
            "A1",
            "A2",
            "A3",
            "A4",
            "A5",
            "A6",
            "A7",
            "A8",
            "A9",
            "A10",
            "A11",
            "A12"
        ],
        "num_flashes": 50,
        "wavelength": "600:nanometer",
        "op": "absorbance"
    }
]

Parameters

• ref (str or Container) – Object to execute the absorbance read on

• wells (list(Well) or WellGroup or Well) – WellGroup of wells to be measured or a list of well references in the form of [“A1”, “B1”, “C5”, …]

• wavelength (str or Unit) – wavelength of light absorbance to be read for the indicated wells

• dataref (str) – name of this specific dataset of measured absorbances

• flashes (int, optional) – number of flashes for the read

• temperature (str or Unit, optional) – set temperature to heat plate reading chamber

• settle_time (Unit, optional) – the time before the start of the measurement, defaults to vendor specifications

• incubate_before (dict, optional) – parameters for incubation before executing the plate read See Also Absorbance.builders.incubate_params()

Returns

Returns the autoprotocol.instruction.Absorbance instruction created from the specified parameters

Return type

Absorbance

Raises

• TypeError – Invalid input types, e.g. wells given is of type Well, WellGroup or list of wells

• ValueError – Wells specified are not from the same container

• ValueError – Settle time has to be greater than 0

• UnitError – Settle time is not of type Unit

fluorescence(ref: Union[str, autoprotocol.container.Container], wells: Union[autoprotocol.container.Well, List[autoprotocol.container.Well], autoprotocol.container.WellGroup], excitation: Union[str, autoprotocol.unit.Unit], emission: Union[str, autoprotocol.unit.Unit], dataref: str, flashes: Optional[int] = 25, temperature: Optional[Union[str, autoprotocol.unit.Unit]] = None, gain: Optional[float] = None, incubate_before: Optional[autoprotocol.types.protocol.PlateReaderIncubateBefore] = None, detection_mode: Optional[str] = None, position_z: Optional[Union[autoprotocol.types.protocol.PlateReaderPositionZCalculated, autoprotocol.types.protocol.PlateReaderPositionZManual]] = None, settle_time: Optional[Union[str, autoprotocol.unit.Unit]] = None, lag_time: Optional[Union[str, autoprotocol.unit.Unit]] = None, integration_time: Optional[str] = None)

Read the fluoresence for the indicated wavelength for the indicated wells. Append a Fluorescence instruction to the list of instructions for this Protocol object.

Example Usage:

p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-flat",
                     storage="warm_37")

p.fluorescence(sample_plate, sample_plate.wells_from(0,12),
               excitation="587:nanometer", emission="610:nanometer",
               dataref="test_reading")

Autoprotocol Output:

"instructions": [
    {
        "dataref": "test_reading",
        "excitation": "587:nanometer",
        "object": "sample_plate",
        "emission": "610:nanometer",
        "wells": [
            "A1",
            "A2",
            "A3",
            "A4",
            "A5",
            "A6",
            "A7",
            "A8",
            "A9",
            "A10",
            "A11",
            "A12"
        ],
        "num_flashes": 25,
        "op": "fluorescence"
    }
]

Parameters

• ref (str or Container) – Container to plate read.

• wells (list(Well) or WellGroup or Well) – WellGroup of wells to be measured or a list of well references in the form of [“A1”, “B1”, “C5”, …]

• excitation (str or Unit) – Wavelength of light used to excite the wells indicated

• emission (str or Unit) – Wavelength of light to be measured for the indicated wells

• dataref (str) – Name of this specific dataset of measured fluoresence

• flashes (int, optional) – Number of flashes.

• temperature (str or Unit, optional) – set temperature to heat plate reading chamber

• gain (float, optional) – float between 0 and 1, multiplier, gain=0.2 of maximum signal amplification

• incubate_before (dict, optional) – parameters for incubation before executing the plate read See Also Fluorescence.builders.incubate_params()

• detection_mode (str, optional) – set the detection mode of the optics, [“top”, “bottom”], defaults to vendor specified defaults.

• position_z (dict, optional) –

  distance from the optics to the surface of the plate transport, only valid for “top” detection_mode and vendor capabilities. Specified as either a set distance - “manual”, OR calculated from a WellGroup - “calculated_from_wells”. Only one position_z determination may be specified

  position_z = {
      "manual": Unit
      - OR -
      "calculated_from_wells": []
  }
  

• settle_time (Unit, optional) – the time before the start of the measurement, defaults to vendor specifications

• lag_time (Unit, optional) – time between flashes and the start of the signal integration, defaults to vendor specifications

• integration_time (Unit, optional) – duration of the signal recording, per Well, defaults to vendor specifications

Examples

position_z:

position_z = {
    "calculated_from_wells": ["plate/A1", "plate/A2"]
}

-OR-

position_z = {
    "manual": "20:micrometer"
}

Returns

Returns the autoprotocol.instruction.Fluorescence instruction created from the specified parameters

Return type

Fluorescence

Raises

• TypeError – Invalid input types, e.g. wells given is of type Well, WellGroup or list of wells

• ValueError – Wells specified are not from the same container

• ValueError – Settle time, integration time or lag time has to be greater than 0

• UnitError – Settle time, integration time, lag time or position z is not of type Unit

• ValueError – Unknown value given for detection_mode

• ValueError – Position z specified for non-top detection mode

• KeyError – For position_z, only manual and calculated_from_wells is allowed

• NotImplementedError – Specifying calculated_from_wells as that has not been implemented yet

luminescence(ref: Union[str, autoprotocol.container.Container], wells: Union[autoprotocol.container.Well, List[autoprotocol.container.Well], autoprotocol.container.WellGroup], dataref: str, incubate_before: Optional[autoprotocol.types.protocol.PlateReaderIncubateBefore] = None, temperature: Optional[Union[str, autoprotocol.unit.Unit]] = None, settle_time: Optional[Union[str, autoprotocol.unit.Unit]] = None, integration_time: Optional[Union[str, autoprotocol.unit.Unit]] = None)

Read luminescence of indicated wells.

Example Usage:

p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-flat",
                     storage="warm_37")

p.luminescence(sample_plate, sample_plate.wells_from(0,12),
               "test_reading")

Autoprotocol Output:

"instructions": [
    {
        "dataref": "test_reading",
        "object": "sample_plate",
        "wells": [
            "A1",
            "A2",
            "A3",
            "A4",
            "A5",
            "A6",
            "A7",
            "A8",
            "A9",
            "A10",
            "A11",
            "A12"
        ],
        "op": "luminescence"
    }
]

Parameters

• ref (str or Container) – Container to plate read.

• wells (list(Well) or WellGroup or Well) – WellGroup of wells to be measured or a list of well references in the form of [“A1”, “B1”, “C5”, …]

• dataref (str) – Name of this dataset of measured luminescence readings.

• temperature (str or Unit, optional) – set temperature to heat plate reading chamber

• settle_time (Unit, optional) – the time before the start of the measurement, defaults to vendor specifications

• incubate_before (dict, optional) – parameters for incubation before executing the plate read See Also Absorbance.builders.incubate_params()

• integration_time (Unit, optional) – duration of the signal recording, per Well, defaults to vendor specifications

Returns

Returns the autoprotocol.instruction.Luminescence instruction created from the specified parameters

Return type

Luminescence

Raises

• TypeError – Invalid input types, e.g. wells given is of type Well, WellGroup or list of wells

• ValueError – Wells specified are not from the same container

• ValueError – Settle time or integration time has to be greater than 0

• UnitError – Settle time or integration time is not of type Unit

gel_separate(wells: Union[autoprotocol.container.Well, List[autoprotocol.container.Well], autoprotocol.container.WellGroup], volume: Union[str, autoprotocol.unit.Unit], matrix: str, ladder: str, duration: Union[str, autoprotocol.unit.Unit], dataref: str)

Separate nucleic acids on an agarose gel.

Example Usage:

p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-flat",
                     storage="warm_37")

p.gel_separate(sample_plate.wells_from(0,12), "10:microliter",
               "agarose(8,0.8%)", "ladder1", "11:minute",
               "genotyping_030214")

Autoprotocol Output:

"instructions": [
    {
        "dataref": "genotyping_030214",
        "matrix": "agarose(8,0.8%)",
        "volume": "10:microliter",
        "ladder": "ladder1",
        "objects": [
            "sample_plate/0",
            "sample_plate/1",
            "sample_plate/2",
            "sample_plate/3",
            "sample_plate/4",
            "sample_plate/5",
            "sample_plate/6",
            "sample_plate/7",
            "sample_plate/8",
            "sample_plate/9",
            "sample_plate/10",
            "sample_plate/11"
        ],
        "duration": "11:minute",
        "op": "gel_separate"
    }
]

Parameters

• wells (list(Well) or WellGroup or Well) – List of wells or WellGroup containing wells to be separated on gel.

• volume (str or Unit) – Volume of liquid to be transferred from each well specified to a lane of the gel.

• matrix (str) – Matrix (gel) in which to gel separate samples

• ladder (str) – Ladder by which to measure separated fragment size

• duration (str or Unit) – Length of time to run current through gel.

• dataref (str) – Name of this set of gel separation results.

Returns

Returns the autoprotocol.instruction.GelSeparate instruction created from the specified parameters

Return type

GelSeparate

Raises

• TypeError – Invalid input types, e.g. wells given is of type Well, WellGroup or list of wells

• ValueError – Specifying more wells than the number of available lanes in the selected matrix

gel_purify(extracts: List[autoprotocol.types.protocol.GelPurifyExtract], volume: Union[str, autoprotocol.unit.Unit], matrix: str, ladder: str, dataref: str)

Separate nucleic acids on an agarose gel and purify according to parameters. If gel extract lanes are not specified, they will be sequentially ordered and purified on as many gels as necessary.

Each element in extracts specifies a source loaded in a single lane of gel with a list of bands that will be purified from that lane. If the same source is to be run on separate lanes, a new dictionary must be added to extracts. It is also possible to add an element to extract with a source but without a list of bands. In that case, the source will be run in a lane without extraction.

Example Usage:

p = Protocol()
sample_wells = p.ref("test_plate", None, "96-pcr",
                     discard=True).wells_from(0, 8)
extract_wells = [p.ref("extract_" + str(i.index), None,
                       "micro-1.5", storage="cold_4").well(0)
                 for i in sample_wells]


extracts = [make_gel_extract_params(
                w,
                make_band_param(
                    "TE",
                    "5:microliter",
                    80,
                    79,
                    extract_wells[i]))
                for i, w in enumerate(sample_wells)]

p.gel_purify(extracts, "10:microliter",
             "size_select(8,0.8%)", "ladder1",
             "gel_purify_example")

Autoprotocol Output:

For extracts[0]

{
    "band_list": [
        {
            "band_size_range": {
                "max_bp": 80,
                "min_bp": 79
            },
            "destination": Well(Container(extract_0), 0, None),
            "elution_buffer": "TE",
            "elution_volume": "Unit(5.0, 'microliter')"
        }
    ],
    "gel": None,
    "lane": None,
    "source": Well(Container(test_plate), 0, None)
}

Parameters

• extracts (list(dict)) – List of gel extraction parameters See Also GelPurify.builders.extract()

• volume (str or Unit) – Volume of liquid to be transferred from each well specified to a lane of the gel.

• matrix (str) – Matrix (gel) in which to gel separate samples

• ladder (str) – Ladder by which to measure separated fragment size

• dataref (str) – Name of this set of gel separation results.

Returns

Returns the autoprotocol.instruction.GelPurify instruction created from the specified parameters

Return type

GelPurify

Raises

• RuntimeError – If matrix is not properly formatted.

• AttributeError – If extract parameters are not a list of dictionaries.

• KeyError – If extract parameters do not contain the specified parameter keys.

• ValueError – If min_bp is greater than max_bp.

• ValueError – If extract destination is not of type Well.

• ValueError – If extract elution volume is not of type Unit

• ValueError – if extract elution volume is not greater than 0.

• RuntimeError – If gel extract lanes are set for some but not all extract wells.

• RuntimeError – If all samples do not fit on single gel type.

• TypeError – If lane designated for gel extracts is not an integer.

• RuntimeError – If designated lane index is outside lanes within the gel.

• RuntimeError – If lanes not designated and number of extracts not equal to number of samples.

seal(ref: autoprotocol.container.Container, type: Optional[str] = None, mode: Optional[str] = None, temperature: Optional[Union[str, autoprotocol.unit.Unit]] = None, duration: Optional[Union[str, autoprotocol.unit.Unit]] = None)

Seal indicated container using the automated plate sealer.

Example Usage:

p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-pcr",
                     storage="warm_37")

p.seal(sample_plate, mode="thermal", temperature="160:celsius")

Autoprotocol Output:

"instructions": [
    {
        "object": "sample_plate",
        "type": "ultra-clear",
        "mode": "thermal",
        "mode_params": {
            "temperature": "160:celsius"
        }
        "op": "seal"
    }
]

Parameters

• ref (Container) – Container to be sealed

• type (str, optional) – Seal type to be used, such as “ultra-clear” or “foil”.

• mode (str, optional) – Sealing method to be used, such as “thermal” or “adhesive”. Defaults to None, which is interpreted sensibly based on the execution environment.

• temperature (Unit or str, optional) – Temperature at which to melt the sealing film onto the ref. Only applicable to thermal sealing; not respected if the sealing mode is adhesive. If unspecified, thermal sealing temperature defaults correspond with manufacturer-recommended or internally-optimized values for the target container type. Applies only to thermal sealing.

• duration (Unit or str, optional) – Duration for which to press the (heated, if thermal) seal down on the ref. Defaults to manufacturer-recommended or internally- optimized seal times for the target container type. Currently applies only to thermal sealing.

Returns

Returns the autoprotocol.instruction.Seal instruction created from the specified parameters

Return type

Seal

Raises

• TypeError – If ref is not of type Container.

• RuntimeError – If container type does not have seal capability.

• RuntimeError – If seal is not a valid seal type.

• RuntimeError – If the sealing mode is invalid, or incompatible with the given ref

• RuntimeError – If thermal sealing params (temperature and/or duration) are specified alongside an adhesive sealing mode.

• RuntimeError – If specified thermal sealing parameters are invalid

• RuntimeError – If container is already covered with a lid.

unseal(ref: autoprotocol.container.Container)

Remove seal from indicated container using the automated plate unsealer.

Example Usage:

p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-pcr",
                     storage="warm_37")
# a plate must be sealed to be unsealed
p.seal(sample_plate)

p.unseal(sample_plate)

Autoprotocol Output:

"instructions": [
    {
      "object": "sample_plate",
      "op": "seal",
      "type": "ultra-clear"
    },
    {
      "object": "sample_plate",
      "op": "unseal"
    }
  ]

Parameters

ref (Container) – Container to be unsealed.

Returns

Returns the autoprotocol.instruction.Unseal instruction created from the specified parameters

Return type

Unseal

Raises

• TypeError – If ref is not of type Container.

• RuntimeError – If container is covered with a lid not a seal.

cover(ref: autoprotocol.container.Container, lid: Optional[str] = None, retrieve_lid: Optional[bool] = None)

Place specified lid type on specified container

Example Usage:

p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-flat",
                     storage="warm_37")
p.cover(sample_plate, lid="universal")

Autoprotocol Output:

"instructions": [
    {
        "lid": "universal",
        "object": "sample_plate",
        "op": "cover"
    }
]

Parameters

• ref (Container) – Container to be convered.

• lid (str, optional) – Type of lid to cover the container. Must be a valid lid type for the container type.

• retrieve_lid (bool, optional) – Flag to retrieve lid from previously stored location (see uncover).

Returns

Returns the autoprotocol.instruction.Cover instruction created from the specified parameters

Return type

Cover

Raises

• TypeError – If ref is not of type Container.

• RuntimeError – If container type does not have cover capability.

• RuntimeError – If lid is not a valid lid type.

• RuntimeError – If container is already sealed with a seal.

• TypeError – If retrieve_lid is not a boolean.

uncover(ref: autoprotocol.container.Container, store_lid: Optional[bool] = None)

Remove lid from specified container

Example Usage:

p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-flat",
                     storage="warm_37")
# a plate must have a cover to be uncovered
p.cover(sample_plate, lid="universal")

p.uncover(sample_plate)

Autoprotocol Output:

"instructions": [
    {
        "lid": "universal",
        "object": "sample_plate",
        "op": "cover"
    },
    {
        "object": "sample_plate",
        "op": "uncover"
    }
  ]

Parameters

• ref (Container) – Container to remove lid.

• store_lid (bool, optional) – Flag to store the uncovered lid.

Returns

Returns the autoprotocol.instruction.Uncover instruction created from the specified parameters

Return type

Uncover

Raises

• TypeError – If ref is not of type Container.

• RuntimeError – If container is sealed with a seal not covered with a lid.

• TypeError – If store_lid is not a boolean.

flow_cytometry(dataref: str, samples: Union[autoprotocol.container.Well, List[autoprotocol.container.Well], autoprotocol.container.WellGroup], lasers: List[autoprotocol.types.protocol.FlowCytometryLaser], collection_conditions: autoprotocol.types.protocol.FlowCytometryCollectionCondition, width_threshold: Optional[Union[int, float]] = None, window_extension: Optional[Union[int, float]] = None, remove_coincident_events: Optional[bool] = None)

A non-ambiguous set of parameters for performing flow cytometry.

Parameters

• dataref (str) – Name of dataset that will be returned.

• samples (list(Well) or Well or WellGroup) – Wells to be analyzed

• lasers (list(dict)) – See FlowCytometryBuilders.laser.

• collection_conditions (dict) – See FlowCytometryBuilders.collection_conditions.

• width_threshold (int or float, optional) – Threshold to determine width measurement.

• window_extension (int or float, optional) – Front and rear window extension.

• remove_coincident_events (bool, optional) – Remove coincident events.

Returns

Returns a autoprotocol.instruction.FlowCytometry instruction created from the specified parameters.

Return type

FlowCytometry

Raises

• TypeError – If lasers is not of type list.

• TypeError – If samples is not of type Well, list of Well, or WellGroup.

• TypeError – If width_threshold is not a number.

• TypeError – If window_extension is not a number.

• TypeError – If remove_coincident_events is not of type bool.

Examples

Example flow cytometry protocol

p = Protocol()
plate = p.ref("sample-plate", cont_type="384-flat", discard=True)

lasers = [FlowCytometry.builders.laser(
    excitation="405:nanometers",
    channels=[
        FlowCytometry.builders.channel(
            emission_filter=FlowCytometry.builders.emission_filter(
                channel_name="VL1",
                shortpass="415:nanometers",
                longpass="465:nanometers"
            ),
            detector_gain="10:millivolts"
        )
    ]
)]

collection_conds = FlowCytometry.builders.collection_conditions(
    acquisition_volume="5.0:ul",
    flowrate="12.5:ul/min",
    wait_time="10:seconds",
    mix_cycles=10,
    mix_volume="10:ul",
    rinse_cycles=10
)

p.flow_cytometry("flow-1234", plate.wells_from(0, 3), lasers,
                 collection_conds)

Autoprotocol Output:

{
  "op": "flow_cytometry",
  "dataref": "flow-1234",
  "samples": [
    "sample-plate/0",
    "sample-plate/1",
    "sample-plate/2"
  ],
  "lasers": [
    {
      "excitation": "405:nanometer",
      "channels": [
        {
          "emission_filter": {
            "channel_name": "VL1",
            "shortpass": "415:nanometer",
            "longpass": "465:nanometer"
          },
          "detector_gain": "10:millivolt"
        }
      ]
    }
  ],
  "collection_conditions": {
    "acquisition_volume": "5:microliter",
    "flowrate": "12.5:microliter/minute",
    "stop_criteria": {
      "volume": "5:microliter"
    },
    "wait_time": "10:second",
    "mix_cycles": 10,
    "mix_volume": "10:microliter",
    "rinse_cycles": 10
  }
}

flow_analyze(dataref: str, FSC: autoprotocol.types.protocol.FlowAnalyzeChannel, SSC: autoprotocol.types.protocol.FlowAnalyzeChannel, neg_controls: List[autoprotocol.types.protocol.FlowAnalyzeNegControls], samples: List[autoprotocol.types.protocol.FlowAnalyzeSample], colors: Optional[List[autoprotocol.types.protocol.FlowAnalyzeColors]] = None, pos_controls: Optional[List[autoprotocol.types.protocol.FlowAnalyzePosControls]] = None)

Perform flow cytometry. 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. At least one negative control is required, 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.

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.

Example Usage:

p = Protocol()
dataref = "test_ref"
FSC = {"voltage_range": {"low": "230:volt", "high": "280:volt"},
       "area": True, "height": True, "weight": False}
SSC = {"voltage_range": {"low": "230:volt", "high": "280:volt"},
       "area": True, "height": True, "weight": False}
neg_controls = {"well": "well0", "volume": "100:microliter",
                "captured_events": 5, "channel": "channel0"}
samples = [
    {
        "well": "well0",
        "volume": "100:microliter",
        "captured_events": 9
    }
]

p.flow_analyze(dataref, FSC, SSC, neg_controls,
               samples, colors=None, pos_controls=None)

Autoprotocol Output:

{
    "channels": {
        "FSC": {
            "voltage_range": {
                "high": "280:volt",
                "low": "230:volt"
            },
            "area": true,
            "height": true,
            "weight": false
        },
        "SSC": {
            "voltage_range": {
                "high": "280:volt",
                "low": "230:volt"
            },
            "area": true,
            "height": true,
            "weight": false
        }
    },
    "op": "flow_analyze",
    "negative_controls": {
        "channel": "channel0",
        "well": "well0",
        "volume": "100:microliter",
        "captured_events": 5
    },
    "dataref": "test_ref",
    "samples": [
        {
            "well": "well0",
            "volume": "100:microliter",
            "captured_events": 9
        }
    ]
}

Parameters

• dataref (str) – Name of flow analysis dataset generated.

• FSC (dict) –

  Dictionary containing FSC channel parameters in the form of:

  {
      "voltage_range": {
          "low": "230:volt",
          "high": "280:volt"
      },
      "area": true,             //default: true
      "height": true,           //default: true
      "weight": false           //default: false
  }
  

• SSC (dict) –

  Dictionary of SSC channel parameters in the form of:

  {
      "voltage_range": {
          "low": <voltage>,
          "high": <voltage>"
      },
      "area": true,             //default: true
      "height": true,           //default: false
      "weight": false           //default: false
  }
  

• neg_controls (list(dict)) –

  List of negative control wells in the form of:

  {
      "well": well,
      "volume": volume,
      "captured_events": integer,    // optional, default infinity
      "channel": [channel_name]
  }
  

  at least one negative control is required.

• samples (list(dict)) –

  List of samples in the form of:

  {
      "well": well,
      "volume": volume,
      "captured_events": integer     // optional, default infinity
  }
  

  at least one sample is required

• colors (list(dict), optional) –

  Optional list of colors in the form of:

  [
      {
          "name": "FitC",
          "emission_wavelength": "495:nanometer",
          "excitation_wavelength": "519:nanometer",
          "voltage_range": {
              "low": <voltage>,
              "high": <voltage>
          },
          "area": true,             //default: true
          "height": false,          //default: false
          "weight": false           //default: false
      }, ...
  ]
  

• pos_controls (list(dict), optional) –

  Optional list of positive control wells in the form of:

  [
      {
          "well": well,
          "volume": volume,
          "captured_events": integer,      // default: infinity
          "channel": [channel_name],
          "minimize_bleed": [{             // optional
            "from": color,
            "to": [color]
      }, ...
  ]
  

Returns

Returns the autoprotocol.instruction.FlowAnalyze instruction created from the specified parameters

Return type

FlowAnalyze

Raises

• TypeError – If inputs are not of the correct type.

• UnitError – If unit inputs are not properly formatted.

• AssertionError – If required parameters are missing.

• ValueError – If volumes are not correctly formatted or present.

oligosynthesize(oligos: List[autoprotocol.types.protocol.OligosynthesizeOligo])

Specify a list of oligonucleotides to be synthesized and a destination for each product.

Example Usage:

oligo_1 = p.ref("oligo_1", None, "micro-1.5", discard=True)

p.oligosynthesize([{"sequence": "CATGGTCCCCTGCACAGG",
                    "destination": oligo_1.well(0),
                    "scale": "25nm",
                    "purification": "standard"}])

Autoprotocol Output:

"instructions": [
    {
        "oligos": [
            {
                "destination": "oligo_1/0",
                "sequence": "CATGGTCCCCTGCACAGG",
                "scale": "25nm",
                "purification": "standard"
            }
        ],
        "op": "oligosynthesize"
    }
]

Parameters

oligos (list(dict)) –

List of oligonucleotides to synthesize. Each dictionary should contain the oligo’s sequence, destination, scale and purification

[
    {
        "destination": "my_plate/A1",
        "sequence": "GATCRYMKSWHBVDN",
        // - standard IUPAC base codes
        // - IDT also allows rX (RNA), mX (2' O-methyl RNA), and
        //   X*/rX*/mX* (phosphorothioated)
        // - they also allow inline annotations for
        //   modifications,
        //   e.g. "GCGACTC/3Phos/" for a 3' phosphorylation
        //   e.g. "aggg/iAzideN/cgcgc" for an
        //   internal modification
        "scale": "25nm" | "100nm" | "250nm" | "1um",
        "purification": "standard" | "page" | "hplc",
        // default: standard
    }, ...
]

Returns

Returns the autoprotocol.instruction.Oligosynthesize instruction created from the specified parameters

Return type

Oligosynthesize

autopick(pick_groups: List[autoprotocol.types.protocol.AutopickGroup], criteria: Optional[Dict[str, Any]] = None, dataref: str = 'autopick')

Pick colonies from the agar-containing location(s) specified in sources to the location(s) specified in dests in highest to lowest rank order until there are no more colonies available. If fewer than min_abort pickable colonies have been identified from the location(s) specified in sources, the run will stop and no further instructions will be executed.

Example Usage:

Autoprotocol Output:

Parameters

• pick_groups (List of AutopickGroups) –

  sourcesWell or WellGroup or list(Well) or list(WellGroup) or list(list(Well))

  Reference wells containing agar and colonies to pick

  destinationsWell or WellGroup or list(Well) or list(WellGroup) or list(list(Well))

  List of destination(s) for picked colonies

  min_abortint

  Total number of colonies that must be detected in the aggregate list of from wells to avoid aborting the entire run. Value of 0 prevents aborting regardless of amount detected.

• criteria (dict) – Dictionary of autopicking criteria.

• dataref (str) – Name of dataset to save the picked colonies to

Returns

Returns the autoprotocol.instruction.Autopick instruction created from the specified parameters

Return type

Autopick

Raises

• TypeError – Invalid input types for sources and dests

• ValueError – Source wells are not all from the same container

mag_dry(head: str, container: autoprotocol.container.Container, duration: Union[str, autoprotocol.unit.Unit], new_tip: bool = False, new_instruction: bool = False)

Dry beads with magnetized tips above and outside a container for a set time.

Example Usage:

p = Protocol()
plate = p.ref("plate_0", None, "96-pcr", storage="cold_20")

p.mag_dry("96-pcr", plate, "30:minute", new_tip=False,
          new_instruction=False)

Autoprotocol Output:

"instructions": [
    {
      "groups": [
        [
          {
            "dry": {
              "duration": "30:minute",
              "object": "plate_0"
            }
          }
        ]
      ],
      "magnetic_head": "96-pcr",
      "op": "magnetic_transfer"
    }
  ]

Parameters

• head (str) – Magnetic head to use for the magnetic bead transfers

• container (Container) – Container to dry beads above

• duration (str or Unit) – Time for drying

• new_tip (bool) – Specify whether to use a new tip to complete the step

• new_instruction (bool) – Specify whether to create a new magnetic_transfer instruction

Returns

Returns the autoprotocol.instruction.MagneticTransfer instruction created from the specified parameters

Return type

MagneticTransfer

mag_incubate(head: str, container: autoprotocol.container.Container, duration: Union[str, autoprotocol.unit.Unit], magnetize: bool = False, tip_position: float = 1.5, temperature: Optional[Union[str, autoprotocol.unit.Unit]] = None, new_tip: bool = False, new_instruction: bool = False)

Incubate the container for a set time with tips set at tip_position.

Example Usage:

p = Protocol()
plate = p.ref("plate_0", None, "96-pcr", storage="cold_20")

p.mag_incubate("96-pcr", plate, "30:minute", magnetize=False,
               tip_position=1.5, temperature=None, new_tip=False)

Autoprotocol Output:

"instructions": [
    {
        "groups": [
            [
                {
                    "incubate": {
                        "duration": "30:minute",
                        "tip_position": 1.5,
                        "object": "plate_0",
                        "magnetize": false,
                        "temperature": null
                    }
                }
            ]
        ],
        "magnetic_head": "96-pcr",
        "op": "magnetic_transfer"
    }
]

Parameters

• head (str) – Magnetic head to use for the magnetic bead transfers

• container (Container) – Container to incubate beads

• duration (str or Unit) – Time for incubation

• magnetize (bool) – Specify whether to magnetize the tips

• tip_position (float) – Position relative to well height that tips are held

• temperature (str or Unit, optional) – Temperature heat block is set at

• new_tip (bool) – Specify whether to use a new tip to complete the step

• new_instruction (bool) – Specify whether to create a new magnetic_transfer instruction

Returns

Returns the autoprotocol.instruction.MagneticTransfer instruction created from the specified parameters

Return type

MagneticTransfer

mag_collect(head: str, container: autoprotocol.container.Container, cycles: int, pause_duration: Union[str, autoprotocol.unit.Unit], bottom_position: float = 0.0, temperature: Optional[Union[str, autoprotocol.unit.Unit]] = None, new_tip: bool = False, new_instruction: bool = False)

Collect beads from a container by cycling magnetized tips in and out of the container with an optional pause at the bottom of the insertion.

Example Usage:

p = Protocol()
plate = p.ref("plate_0", None, "96-pcr", storage="cold_20")

p.mag_collect("96-pcr", plate, 5, "30:second", bottom_position=
              0.0, temperature=None, new_tip=False,
              new_instruction=False)

Autoprotocol Output:

"instructions": [
    {
        "groups": [
            [
                {
                    "collect": {
                        "bottom_position": 0,
                        "object": "plate_0",
                        "temperature": null,
                        "cycles": 5,
                        "pause_duration": "30:second"
                    }
                }
            ]
        ],
        "magnetic_head": "96-pcr",
        "op": "magnetic_transfer"
    }
]

Parameters

• head (str) – Magnetic head to use for the magnetic bead transfers

• container (Container) – Container to incubate beads

• cycles (int) – Number of cycles to raise and lower tips

• pause_duration (str or Unit) – Time tips are paused in bottom position each cycle

• bottom_position (float) – Position relative to well height that tips are held during pause

• temperature (str or Unit) – Temperature heat block is set at

• new_tip (bool) – Specify whether to use a new tip to complete the step

• new_instruction (bool) – Specify whether to create a new magnetic_transfer instruction

Returns

Returns the autoprotocol.instruction.MagneticTransfer instruction created from the specified parameters

Return type

MagneticTransfer

mag_release(head: str, container: autoprotocol.container.Container, duration: Union[str, autoprotocol.unit.Unit], frequency: Union[str, autoprotocol.unit.Unit], center: float = 0.5, amplitude: float = 0.5, temperature: Optional[Union[str, autoprotocol.unit.Unit]] = None, new_tip: bool = False, new_instruction: bool = False)

Release beads into a container by cycling tips in and out of the container with tips unmagnetized.

Example Usage:

p = Protocol()
plate = p.ref("plate_0", None, "96-pcr", storage="cold_20")

p.mag_release("96-pcr", plate, "30:second", "60:hertz", center=0.75,
              amplitude=0.25, temperature=None, new_tip=False,
              new_instruction=False)

Autoprotocol Output:

"instructions": [
    {
        "groups": [
            [
                {
                    "release": {
                        "center": 0.75,
                        "object": "plate_0",
                        "frequency": "2:hertz",
                        "amplitude": 0.25,
                        "duration": "30:second",
                        "temperature": null
                    }
                }
            ]
        ],
        "magnetic_head": "96-pcr",
        "op": "magnetic_transfer"
    }
]

Parameters

• head (str) – Magnetic head to use for the magnetic bead transfers

• container (Container) – Container to incubate beads

• duration (str or Unit) – Total time for this sub-operation

• frequency (str or Unit) – Cycles per second (hertz) that tips are raised and lowered

• center (float) – Position relative to well height where oscillation is centered

• amplitude (float) – Distance relative to well height to oscillate around “center”

• temperature (str or Unit) – Temperature heat block is set at

• new_tip (bool) – Specify whether to use a new tip to complete the step

• new_instruction (bool) – Specify whether to create a new magnetic_transfer instruction

Returns

Returns the autoprotocol.instruction.MagneticTransfer instruction created from the specified parameters

Return type

MagneticTransfer

mag_mix(head: str, container: autoprotocol.container.Container, duration: Union[str, autoprotocol.unit.Unit], frequency: Union[str, autoprotocol.unit.Unit], center: float = 0.5, amplitude: float = 0.5, magnetize: bool = False, temperature: Optional[Union[str, autoprotocol.unit.Unit]] = None, new_tip: bool = False, new_instruction: bool = False)

Mix beads in a container by cycling tips in and out of the container.

Example Usage:

p = Protocol()
plate = p.ref("plate_0", None, "96-pcr", storage="cold_20")

p.mag_mix("96-pcr", plate, "30:second", "60:hertz", center=0.75,
          amplitude=0.25, magnetize=True, temperature=None,
          new_tip=False, new_instruction=False)

Autoprotocol Output:

"instructions": [
    {
        "groups": [
            [
                {
                    "mix": {
                        "center": 0.75,
                        "object": "plate_0",
                        "frequency": "2:hertz",
                        "amplitude": 0.25,
                        "duration": "30:second",
                        "magnetize": true,
                        "temperature": null
                    }
                }
            ]
        ],
        "magnetic_head": "96-pcr",
        "op": "magnetic_transfer"
    }
]

Parameters

• head (str) – Magnetic head to use for the magnetic bead transfers

• container (Container) – Container to incubate beads

• duration (str or Unit) – Total time for this sub-operation

• frequency (str or Unit) – Cycles per second (hertz) that tips are raised and lowered

• center (float) – Position relative to well height where oscillation is centered

• amplitude (float) – Distance relative to well height to oscillate around “center”

• magnetize (bool) – Specify whether to magnetize the tips

• temperature (str or Unit) – Temperature heat block is set at

• new_tip (bool) – Specify whether to use a new tip to complete the step

• new_instruction (bool) – Specify whether to create a new magnetic_transfer instruction

Returns

Returns the autoprotocol.instruction.MagneticTransfer instruction created from the specified parameters

Return type

MagneticTransfer

image_plate(ref: Union[str, autoprotocol.container.Container], mode: str, dataref: str)

Capture an image of the specified container.

Example Usage:

p = Protocol()

agar_plate = p.ref("agar_plate", None, "1-flat", discard=True)
bact = p.ref("bacteria", None, "micro-1.5", discard=True)

p.spread(bact.well(0), agar_plate.well(0), "55:microliter")
p.incubate(agar_plate, "warm_37", "18:hour")
p.image_plate(agar_plate, mode="top", dataref="my_plate_image_1")

Autoprotocol Output:

{
  "refs": {
    "bacteria": {
      "new": "micro-1.5",
      "discard": true
    },
    "agar_plate": {
      "new": "1-flat",
      "discard": true
    }
  },
  "instructions": [
    {
      "volume": "55.0:microliter",
      "to": "agar_plate/0",
      "from": "bacteria/0",
      "op": "spread"
    },
    {
      "where": "warm_37",
      "object": "agar_plate",
      "co2_percent": 0,
      "duration": "18:hour",
      "shaking": false,
      "op": "incubate"
    },
    {
      "dataref": "my_plate_image_1",
      "object": "agar_plate",
      "mode": "top",
      "op": "image_plate"
    }
  ]
}

Parameters

• ref (str or Container) – Container to take image of

• mode (str) – Imaging mode (currently supported: “top”)

• dataref (str) – Name of data reference of resulting image

Returns

Returns the autoprotocol.instruction.ImagePlate instruction created from the specified parameters

Return type

ImagePlate

provision(resource_id: str, dests: Union[autoprotocol.container.Well, List[autoprotocol.container.Well], autoprotocol.container.WellGroup], amounts: Optional[Union[str, autoprotocol.unit.Unit, List[Union[str, autoprotocol.unit.Unit]]]] = None, volumes: Optional[Union[str, autoprotocol.unit.Unit, List[Union[str, autoprotocol.unit.Unit]]]] = None, informatics: Optional[List[autoprotocol.informatics.Informatics]] = None)

Provision a commercial resource from a catalog into the specified destination well(s). A new tip is used for each destination well specified to avoid contamination.

Parameters

• resource_id (str) – Resource ID from catalog.

• dests (Well or WellGroup or list(Well)) – Destination(s) for specified resource.

• amounts (str or Unit or list(str) or list(Unit)) – Volume(s) or Mass(es) to transfer of the resource to each destination well. If one volume or mass is specified, each destination well receive that volume or mass of the resource. If destinations should receive different volume or mass, each one should be specified explicitly in a list matching the order of the specified destinations. Note: Volumes and amounts arguments are mutually exclusive. Only one is required

• volumes (str or Unit or list(str) or list(Unit)) – Volume to transfer of the resource to each destination well. If one volume is specified, each destination well receive that volume of the resource. If destinations should receive different volumes, each one should be specified explicitly in a list matching the order of the specified destinations. Note: Volumes and amounts arguments are mutually exclusive. Only one is required

• informatics (list(Informatics)) – List of Informatics detailing aliquot effects intended from this instruction.

Raises

• TypeError – If resource_id is not a string.

• TypeError – If the unit provided is not supported

• TypeError – If volume or mass is not specified as a string or Unit (or a list of either)

• RuntimeError – If length of the list of volumes or masses specified does not match the number of destination wells specified.

• ValueError – If the resource measurement mode is volume and the provision exceeds max capacity of well.

• ValueError – If the provisioning of volumes or amounts are not supported.

Returns

autoprotocol.instruction.Provision instruction object(s) to be appended and returned

Return type

list(Provision)

flash_freeze(container: Union[str, autoprotocol.container.Container], duration: Union[str, autoprotocol.unit.Unit])

Flash freeze the contents of the specified container by submerging it in liquid nitrogen for the specified amount of time.

Example Usage:

p = Protocol()

sample = p.ref("liquid_sample", None, "micro-1.5", discard=True)
p.flash_freeze(sample, "25:second")

Autoprotocol Output:

{
  "refs": {
    "liquid_sample": {
      "new": "micro-1.5",
      "discard": true
    }
  },
  "instructions": [
    {
      "duration": "25:second",
      "object": "liquid_sample",
      "op": "flash_freeze"
    }
  ]
}

Parameters

• container (Container or str) – Container to be flash frozen.

• duration (str or Unit) – Duration to submerge specified container in liquid nitrogen.

Returns

Returns the autoprotocol.instruction.FlashFreeze instruction created from the specified parameters

Return type

FlashFreeze

sonicate(wells: Union[autoprotocol.container.Well, List[autoprotocol.container.Well], autoprotocol.container.WellGroup], duration: Union[str, autoprotocol.unit.Unit], mode: autoprotocol.types.protocol.SonicateMode, mode_params: Union[autoprotocol.types.protocol.SonicateModeParamsBath, autoprotocol.types.protocol.SonicateModeParamsHorn], frequency: Optional[Union[str, autoprotocol.unit.Unit]] = None, temperature: Optional[Union[str, autoprotocol.unit.Unit]] = None)

Sonicate wells using high intensity ultrasonic vibrations.

Example Usage:

p = Protocol()
sample_wells = p.ref("sample_plate",
                     None,
                     "96-pcr",
                     storage="warm_37").wells_from(0,2)

p.sonicate(sample_wells, duration="1:minute",
           mode="bath",
           mode_params={"sample_holder": "suspender"})

Autoprotocol Output:

{
    "op": "sonicate",
    "wells": ["sample_plate/0", "sample_plate/1"],
    "mode": "bath",
    "duration": "1:minute",
    "temperature": "ambient",
    "frequency": "40:kilohertz"
    "mode_params": {
        "sample_holder": "suspender"
    }
}

Parameters

• wells (Well or WellGroup or list(Well)) – Wells to be sonicated

• duration (Unit or str) – Duration for which to sonicate wells

• mode (Enum({"bath", "horn"})) – Sonicating method to be used, must be “horn” or “bath”. Sonicate mode “horn” uses metal probe to create a localized shear force directly in the sample media; “bath” mode applies ultrasound to wells held inside a bath.

• temperature (Unit or str, optional) – Temperature at which the sample is kept during sonication. Optional, defaults to ambient

• frequency (Unit or str, optional) – Frequency of the ultrasonic wave, usually indicated in kHz. Optional; defaults to the most commonly used frequency for each mode: 20 kHz for horn, and 40 kHz for bath mode

• mode_params (Dict) –

  Dictionary containing mode parameters for the specified mode.

  {
      "mode": "bath",
      "mode_params":
          {
              "sample_holder": Enum({"suspender",
                                     "perforated_container",
                                     "solid_container"})
              "power": Unit or str, optional
          }
  }
  - or -
  {
      "mode": "horn",
      "mode_params":
          {
              "duty_cycle": Float, 0 < value <=1
              "amplitude": Unit or str
          }
  }
  

Returns

Returns the autoprotocol.instruction.Sonicate instruction created from the specified parameters

Return type

Sonicate

Raises

• RuntimeError – If valid mode is not specified.

• TypeError – If wells not of type WellGroup or List of Wells.

• ValueError – If invalid mode_params for specified mode.

• TypeError – If invalid mode_params type for specified mode.

spe(well: autoprotocol.container.Well, cartridge: str, pressure_mode: str, load_sample: autoprotocol.types.protocol.SpeLoadSample, elute: List[autoprotocol.types.protocol.SpeElute], condition: Optional[List[autoprotocol.types.protocol.SpeParams]] = None, equilibrate: Optional[List[autoprotocol.types.protocol.SpeParams]] = None, rinse: Optional[List[autoprotocol.types.protocol.SpeParams]] = None)

Apply a solid phase extraction (spe) technique to a sample.

Example Usage:

p = Protocol()

elute_params = [
    SPE.builders.mobile_phase_params(
        is_elute=True,
        volume="2:microliter",
        loading_flowrate="100:ul/second",
        settle_time="2:minute",
        processing_time="3:minute",
        flow_pressure="2:bar",
        resource_id="solvent_a",
        destination_well=p.ref("Elute %s" % i, None,
                               "micro-1.5",
                               discard=True).well(0))
    for i in range(3)
]

sample_loading_params = SPE.builders.mobile_phase_params(
    volume="10:microliter", loading_flowrate="1:ul/second",
    settle_time="2:minute", processing_time="3:minute",
    flow_pressure="2:bar", is_sample=True)

cartridge = "spe_cartridge"
sample = p.ref("Sample", None, "micro-1.5", discard=True).well(0)

p.spe(sample, cartridge, "positive",
      load_sample=sample_loading_params, elute=elute_params)

Autoprotocol Output:

"instructions": [
      {
        "op": "spe",
        "elute": [
          {
            "loading_flowrate": "100:microliter/second",
            "resource_id": "solvent_a",
            "settle_time": "2:minute",
            "volume": "2:microliter",
            "flow_pressure": "2:bar",
            "destination_well": "Elute 0/0",
            "processing_time": "3:minute"
          },
          {
            "loading_flowrate": "100:microliter/second",
            "resource_id": "solvent_a",
            "settle_time": "2:minute",
            "volume": "2:microliter",
            "flow_pressure": "2:bar",
            "destination_well": "Elute 1/0",
            "processing_time": "3:minute"
          },
          {
            "loading_flowrate": "100:microliter/second",
            "resource_id": "solvent_a",
            "settle_time": "2:minute",
            "volume": "2:microliter",
            "flow_pressure": "2:bar",
            "destination_well": "Elute 2/0",
            "processing_time": "3:minute"
          }
        ],
        "cartridge": "spe_cartridge",
        "well": "Sample/0",
        "load_sample": {
          "flow_pressure": "2:bar",
          "loading_flowrate": "1:microliter/second",
          "settle_time": "2:minute",
          "processing_time": "3:minute",
          "volume": "10:microliter"
        },
        "pressure_mode": "positive"
      }
    ]

Parameters

• well (Well) – Well to solid phase extract.

• cartridge (str) – Cartridge to use for solid phase extraction.

• pressure_mode (str) – The direction of pressure applied to the cartridge to force liquid flow. One of “positive”, “negative”.

• load_sample (dict) – Parameters for applying the sample to the cartridge. Single ‘mobile_phase_param’.

• elute (list(dict)) – Parameters for applying a mobile phase to the cartridge with one or more solvents. List of ‘mobile_phase_params’. Requires destination_well.

• condition (list(dict), optional) – Parameters for applying a mobile phase to the cartridge with one or more solvents. List of ‘mobile_phase_params’.

• equilibrate (list(dict), optional) – Parameters for applying a mobile phase to the cartridge with one or more solvents. List of ‘mobile_phase_params’.

• rinse (list(dict), optional) –

  Parameters for applying a mobile phase to the cartridge with one or more solvents. List of ‘mobile_phase_params’.

  mobile_phase_params:

  resource_id: str

  Resource ID of desired solvent.

  volume: volume

  Volume added to the cartridge.

  loading_flowrate: Unit

  Speed at which volume is added to cartridge.

  settle_time: Unit

  Duration for which the solvent remains on the cartridge before a pressure mode is applied.

  processing_time: Unit

  Duration for which pressure is applied to the cartridge after settle_time has elapsed.

  flow_pressure: Unit

  Pressure applied to the column.

  destination_well: Well

  Destination well for eluate. Required parameter for each elute mobile phase parameter

Returns

Returns the autoprotocol.instruction.SPE instruction created from the specified parameters

Return type

SPE

Raises

• TypeError – Invalid input types, e.g. well given is not of type Well

• ValueError – Wells specified are not from the same container

• ValueError – Invalid pressure_mode

• ValueError – settle_time, processing_time, flow_pressure not greater than 0

• ValueError – If not exactly one elution parameter for each elution container

• UnitError – Improperly formatted units for mobile phase parameters

image(ref: autoprotocol.container.Container, mode: Union[str, autoprotocol.types.protocol.ImageMode], num_images: int, dataref: str, backlighting: Optional[bool] = None, magnification: float = 1.0, exposure: Optional[autoprotocol.types.protocol.ImageExposure] = None)

Capture an image of the specified container.

Example Usage:

p = Protocol()

sample = p.ref("Sample", None, "micro-1.5", discard=True)
p.image(sample, "top", "image_1", num_images=3,
        backlighting=False, exposure={"iso": 4},
        magnification=1.0)

Autoprotocol Output:

{
  "refs": {
    "Sample": {
      "new": "micro-1.5",
      "discard": true
    }
  },
  "instructions": [
    {
      "magnification": 1.0,
      "backlighting": false,
      "mode": "top",
      "dataref": "image_1",
      "object": "Sample",
      "num_images": 3,
      "op": "image",
      "exposure": {
        "iso": 4
      }
    }
  ]
}

Parameters

• ref (Container) – Container of which to take image.

• mode (Enum("top", "bottom", "side")) – Angle of image.

• num_images (int) – Number of images taken of the container. Defaults to 1.

• dataref (str) – Name of data reference of resulting image

• backlighting (Bool, optional) – Whether back-lighting is desired.

• magnification (float) – Ratio of sizes of the image projected on the camera sensor compared to the actual size of the object captured. Defaults to 1.0.

• exposure (dict, optional) –

  Parameters to control exposure: “aperture”, “iso”, and “shutter_speed”.

  shutter_speed: Unit, optional

  Duration that the imaging sensor is exposed.

  isoFloat, optional

  Light sensitivity of the imaging sensor.

  aperture: Float, optional

  Diameter of the lens opening.

Returns

Returns the autoprotocol.instruction.Image instruction created from the specified parameters

Return type

Image

Raises

• TypeError – Invalid input types, e.g. num_images is not a positive integer

• ValueError – Invalid exposure parameter supplied

measure_concentration(wells: Union[autoprotocol.container.Well, List[autoprotocol.container.Well], autoprotocol.container.WellGroup], dataref: str, measurement: str, volume: str = '2:microliter')

Measure the concentration of DNA, ssDNA, RNA or protein in the specified volume of the source aliquots.

Example Usage:

p = Protocol()

test_plate = p.ref("test_plate", id=None, cont_type="96-flat",
    storage=None, discard=True)
p.measure_concentration(test_plate.wells_from(0, 3), "mc_test",
    "DNA")
p.measure_concentration(test_plate.wells_from(3, 3),
    dataref="mc_test2", measurement="protein",
    volume="4:microliter")

Autoprotocol Output:

{
    "refs": {
        "test_plate": {
            "new": "96-flat",
            "discard": true
        }
    },
    "instructions": [
        {
            "volume": "2.0:microliter",
            "dataref": "mc_test",
            "object": [
                "test_plate/0",
                "test_plate/1",
                "test_plate/2"
            ],
            "op": "measure_concentration",
            "measurement": "DNA"
        }, ...
    ]
}

Parameters

• wells (list(Well) or WellGroup or Well) – WellGroup of wells to be measured

• volume (str or Unit) – Volume of sample required for analysis

• dataref (str) – Name of this specific dataset of measurements

• measurement (str) – Class of material to be measured. One of [“DNA”, “ssDNA”, “RNA”, “protein”].

Returns

Returns the autoprotocol.instruction.MeasureConcentration instruction created from the specified parameters

Return type

MeasureConcentration

Raises

TypeError – wells specified is not of a valid input type

measure_mass(container: autoprotocol.container.Container, dataref: str)

Measure the mass of a container.

Example Usage:

p = Protocol()

test_plate = p.ref("test_plate", id=None, cont_type="96-flat",
    storage=None, discard=True)
p.measure_mass(test_plate, "test_data")

Autoprotocol Output:

{
    "refs": {
        "test_plate": {
            "new": "96-flat",
            "discard": true
        }
    },
    "instructions": [
        {
            "dataref": "test_data",
            "object": [
                "test_plate"
            ],
            "op": "measure_mass"
        }
    ]
}

Parameters

• container (Container) – container to be measured

• dataref (str) – Name of this specific dataset of measurements

Returns

Returns the autoprotocol.instruction.MeasureMass instruction created from the specified parameters

Return type

MeasureMass

Raises

TypeError – Input given is not of type Container

measure_volume(wells: Union[autoprotocol.container.Well, List[autoprotocol.container.Well], autoprotocol.container.WellGroup], dataref: str)

Measure the volume of each well in wells.

Example Usage:

p = Protocol()

test_plate = p.ref("test_plate", id=None, cont_type="96-flat",
    storage=None, discard=True)
p.measure_volume(test_plate.from_wells(0,2), "test_data")

Autoprotocol Output:

{
    "refs": {
        "test_plate": {
            "new": "96-flat",
            "discard": true
        }
    },
    "instructions": [
        {
            "dataref": "test_data",
            "object": [
                "test_plate/0",
                "test_plate/1"
            ],
            "op": "measure_volume"
        }
    ]
}

Parameters

• wells (list(Well) or WellGroup or Well) – list of wells to be measured

• dataref (str) – Name of this specific dataset of measurements

Returns

Returns the autoprotocol.instruction.MeasureVolume instruction created from the specified parameters

Return type

MeasureVolume

Raises

TypeError – wells specified is not of a valid input type

count_cells(wells: Union[autoprotocol.container.Well, List[autoprotocol.container.Well], autoprotocol.container.WellGroup], volume: Union[str, autoprotocol.unit.Unit], dataref: str, labels: Optional[List[str]] = None)

Count the number of cells in a sample that are positive/negative for a given set of labels.

Example Usage:

p = Protocol()

cell_suspension = p.ref(
    "cells_with_trypan_blue",
    id=None,
    cont_type="micro-1.5",
    discard=True
)
p.count_cells(
    cell_suspension.well(0),
    "10:microliter",
    "my_cell_count",
    ["trypan_blue"]
)

Autoprotocol Output:

{
    "refs": {
        "cells_with_trypan_blue": {
            "new": "micro-1.5",
            "discard": true
        }
    },
    "instructions": [
        {
            "dataref": "my_cell_count",
            "volume": "10:microliter",
            "wells": [
                "cells_with_trypan_blue/0"
            ],
            "labels": [
                "trypan_blue"
            ],
            "op": "count_cells"
        }
    ]
}

Parameters

• wells (Well or list(Well) or WellGroup) – List of wells that will be used for cell counting.

• volume (Unit) – Volume that should be consumed from each well for the purpose of cell counting.

• dataref (str) – Name of dataset that will be returned.

• labels (list(string), optional) – Cells will be scored for presence or absence of each label in this list. If staining is required to visualize these labels, they must be added before execution of this instruction.

Returns

Returns the autoprotocol.instruction.CountCells instruction created from the specified parameters

Return type

CountCells

Raises

TypeError – wells specified is not of a valid input type

spectrophotometry(dataref: str, obj: Union[autoprotocol.container.Container, str], groups: List, interval: Optional[Union[str, autoprotocol.unit.Unit]] = None, num_intervals: Optional[int] = None, temperature: Optional[Union[str, autoprotocol.unit.Unit]] = None, shake_before: Optional[autoprotocol.types.protocol.SpectrophotometryShakeBefore] = None)

Generates an instruction with one or more 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.

Example Usage:

p = Protocol()
read_plate = p.ref("read plate", cont_type="96-flat", discard=True)

groups = Spectrophotometry.builders.groups(
    [
        Spectrophotometry.builders.group(
            "absorbance",
            Spectrophotometry.builders.absorbance_mode_params(
                wells=read_plate.wells(0, 1),
                wavelength=["100:nanometer", "200:nanometer"],
                num_flashes=15,
                settle_time="1:second"
            )
        ),
        Spectrophotometry.builders.group(
            "fluorescence",
            Spectrophotometry.builders.fluorescence_mode_params(
                wells=read_plate.wells(0, 1),
                excitation=[
                    Spectrophotometry.builders.wavelength_selection(
                        ideal="650:nanometer"
                    )
                ],
                emission=[
                    Spectrophotometry.builders.wavelength_selection(
                        shortpass="600:nanometer",
                        longpass="700:nanometer"
                    )
                ],
                num_flashes=15,
                settle_time="1:second",
                lag_time="9:second",
                integration_time="2:second",
                gain=0.3,
                read_position="top"
            )
        ),
        Spectrophotometry.builders.group(
            "luminescence",
            Spectrophotometry.builders.luminescence_mode_params(
                wells=read_plate.wells(0, 1),
                num_flashes=15,
                settle_time="1:second",
                integration_time="2:second",
                gain=0.3
            )
        ),
        Spectrophotometry.builders.group(
            "shake",
            Spectrophotometry.builders.shake_mode_params(
                duration="1:second",
                frequency="9:hertz",
                path="ccw_orbital",
                amplitude="1:mm"
            )
        ),
    ]
)

shake_before = Spectrophotometry.builders.shake_before(
    duration="10:minute",
    frequency="5:hertz",
    path="ccw_orbital",
    amplitude="1:mm"
)

p.spectrophotometry(
    dataref="test data",
    obj=read_plate,
    groups=groups,
    interval="10:minute",
    num_intervals=2,
    temperature="37:celsius",
    shake_before=shake_before
)

Autoprotocol Output:

{
  "op": "spectrophotometry",
  "dataref": "test data",
  "object": "read plate",
  "groups": [
    {
      "mode": "absorbance",
      "mode_params": {
        "wells": [
          "read plate/0",
          "read plate/1"
        ],
        "wavelength": [
          "100:nanometer",
          "200:nanometer"
        ],
        "num_flashes": 15,
        "settle_time": "1:second"
      }
    },
    {
      "mode": "fluorescence",
      "mode_params": {
        "wells": [
          "read plate/0",
          "read plate/1"
        ],
        "excitation": [
          {
            "ideal": "650:nanometer"
          }
        ],
        "emission": [
          {
            "shortpass": "600:nanometer",
            "longpass": "700:nanometer"
          }
        ],
        "num_flashes": 15,
        "settle_time": "1:second",
        "lag_time": "9:second",
        "integration_time": "2:second",
        "gain": 0.3,
        "read_position": "top"
      }
    },
    {
      "mode": "luminescence",
      "mode_params": {
        "wells": [
          "read plate/0",
          "read plate/1"
        ],
        "num_flashes": 15,
        "settle_time": "1:second",
        "integration_time": "2:second",
        "gain": 0.3
      }
    },
    {
      "mode": "shake",
      "mode_params": {
        "duration": "1:second",
        "frequency": "9:hertz",
        "path": "ccw_orbital",
        "amplitude": "1:millimeter"
      }
    }
  ],
  "interval": "10:minute",
  "num_intervals": 2,
  "temperature": "37:celsius",
  "shake_before": {
    "duration": "10:minute",
    "frequency": "5:hertz",
    "path": "ccw_orbital",
    "amplitude": "1:millimeter"
  }
}

Parameters

• dataref (str) – Name of the resultant dataset to be returned.

• obj (Container or str) – Container to be read.

• groups (list) – A list of groups generated by SpectrophotometryBuilders groups builders, any of absorbance_mode_params, fluorescence_mode_params, luminescence_mode_params, or shake_mode_params.

• interval (Unit or str, optional) – The time between each of the read intervals.

• num_intervals (int, optional) – The number of times that the groups should be executed.

• temperature (Unit or str, optional) – The temperature that the entire instruction should be executed at.

• shake_before (dict, optional) – A dict of params generated by SpectrophotometryBuilders.shake_before that dictates how the obj should be incubated with shaking before any of the groups are executed.

Returns

Returns the autoprotocol.instruction.Spectrophotometry instruction created from the specified parameters

Return type

Spectrophotometry

Raises

• TypeError – Invalid num_intervals specified, must be an int

• ValueError – No interval specified but shake groups specified with no duration

transfer(source: Union[autoprotocol.container.Well, List[autoprotocol.container.Well], autoprotocol.container.WellGroup], destination: Union[autoprotocol.container.Well, List[autoprotocol.container.Well], autoprotocol.container.WellGroup], volume: Union[str, autoprotocol.unit.Unit, List[Union[str, autoprotocol.unit.Unit]]], rows: int = 1, columns: int = 1, source_liquid: autoprotocol.liquid_handle.liquid_class.LiquidClass = <class 'autoprotocol.liquid_handle.liquid_class.LiquidClass'>, destination_liquid: autoprotocol.liquid_handle.liquid_class.LiquidClass = <class 'autoprotocol.liquid_handle.liquid_class.LiquidClass'>, method: autoprotocol.liquid_handle.transfer.Transfer = <class 'autoprotocol.liquid_handle.transfer.Transfer'>, one_tip: bool = False, density: Optional[Union[str, autoprotocol.unit.Unit]] = None, mode: Optional[str] = None, informatics: Optional[List[autoprotocol.informatics.Informatics]] = None)

Generates LiquidHandle instructions between wells

Transfer liquid between specified pairs of source & destination wells.

Parameters

• source (Well or WellGroup or list(Well)) – Well(s) to transfer liquid from.

• destination (Well or WellGroup or list(Well)) – Well(s) to transfer liquid to.

• volume (str or Unit or list(str) or list(Unit)) – Volume(s) of liquid to be transferred from source wells to destination wells. The number of volumes specified must correspond to the number of destination wells.

• rows (int, optional) – Number of rows to be concurrently transferred

• columns (int, optional) – Number of columns to be concurrently transferred

• source_liquid (LiquidClass or list(LiquidClass), optional) – Type(s) of liquid contained in the source Well. This affects the aspirate and dispense behavior including the flowrates, liquid level detection thresholds, and physical movements.

• destination_liquid (LiquidClass or list(LiquidClass), optional) – Type(s) of liquid contained in the destination Well. This affects liquid level detection thresholds.

• method (Transfer or list(Transfer), optional) – Integrates with the specified source_liquid and destination_liquid to define a set of physical movements.

• one_tip (bool, optional) – If True then a single tip will be used for all operations

• density (Unit or str, optional) – Density of the liquid to be aspirated/dispensed

• mode (str, optional) – The liquid handling mode

• informatics (list(Informatics), optional) – List of Informatics describing the intended aliquot effects upon completion of this instruction.

Returns

Returns a list of autoprotocol.instruction.LiquidHandle instructions created from the specified parameters

Return type

list(LiquidHandle)

Raises

• ValueError – if the specified parameters can’t be interpreted as lists of equal length

• ValueError – if one_tip is true, but not all transfer methods have a tip_type

Examples

Transfer between two single wells

from autoprotocol import Protocol, Unit

p = Protocol()
source = p.ref("source", cont_type="384-flat", discard=True)
destination = p.ref(
    "destination", cont_type="394-pcr", discard=True
)
p.transfer(source.well(0), destination.well(1), "5:ul")

Sequential transfers between two groups of wells

sources = source.wells_from(0, 8, columnwise=True)
dests = destination.wells_from(1, 8, columnwise=True)
volumes = [Unit(x, "ul") for x in range(1, 9)]
p.transfer(sources, dests, volumes)

Concurrent transfers between two groups of wells

# single-column concurrent transfer
p.transfer(
    source.well(0), destination.well(1), "5:ul", rows=8
)

# 96-well concurrent transfer from the A1 to B2 quadrants
p.transfer(
    source.well(0), destination.well(13), "5:ul", rows=8, columns=12
)

# 384-well concurrent transfer
p.transfer(
    source.well(0), destination.well(0), "5:ul", rows=16, columns=24
)

Transfer with extra parameters

from autoprotocol.liquid_handle import Transfer
from autoprotocol.instruction import LiquidHandle

p.transfer(
    source.well(0), destination.well(0), "5:ul",
    method=Transfer(
        mix_before=True,
        dispense_z=LiquidHandle.builders.position_z(
           reference="well_top"
        )
    )
)

Transfer using other built in Transfer methods

from autoprotocol.liquid_handle import DryWellTransfer

p.transfer(
    source.well(0), destination.well(1), "5:ul",
    method=DryWellTransfer
)

For examples of other more complicated behavior, see the documentation for LiquidHandleMethod.

See also

Transfer

base LiquidHandleMethod for transfer operations

mix(well: Union[autoprotocol.container.Well, List[autoprotocol.container.Well], autoprotocol.container.WellGroup], volume: Union[str, autoprotocol.unit.Unit, List[Union[str, autoprotocol.unit.Unit]]], rows: int = 1, columns: int = 1, liquid: autoprotocol.liquid_handle.liquid_class.LiquidClass = <class 'autoprotocol.liquid_handle.liquid_class.LiquidClass'>, method: autoprotocol.liquid_handle.mix.Mix = <class 'autoprotocol.liquid_handle.mix.Mix'>, one_tip: bool = False, mode: Optional[str] = None)

Generates LiquidHandle instructions within wells

Mix liquid in specified wells.

Parameters

• well (Well or WellGroup or list(Well)) – Well(s) to be mixed.

• volume (str or Unit or list(str) or list(Unit)) – Volume(s) of liquid to be mixed within the specified well(s). The number of volume(s) specified must correspond with the number of well(s).

• rows (int, optional) – Number of rows to be concurrently mixed

• columns (int, optional) – Number of columns to be concurrently mixed

• liquid (LiquidClass or list(LiquidClass), optional) – Type(s) of liquid contained in the Well(s). This affects the aspirate and dispense behavior including the flowrates, liquid level detection thresholds, and physical movements.

• method (Mix or list(Mix), optional) – Method(s) with which Integrates with the specified liquid to define a set of physical movements.

• one_tip (bool, optional) – If True then a single tip will be used for all operations

• mode (str, optional) – The liquid handling mode

Returns

Returns a list of autoprotocol.instruction.LiquidHandle instructions created from the specified parameters

Return type

list(LiquidHandle)

Raises

• ValueError – if the specified parameters can’t be interpreted as lists of equal length

• ValueError – if one_tip is true, but not all mix methods have a tip_type

• ValueError – if the specified volume is larger than the maximum tip capacity of the available liquid_handling devices for a given mix

Examples

Mix within a single well

from autoprotocol import Protocol, Unit

p = Protocol()
plate = p.ref("example_plate", cont_type="384-flat", discard=True)

p.mix(plate.well(0), "5:ul")

Sequential mixes within multiple wells

wells = plate.wells_from(0, 8, columnwise=True)
volumes = [Unit(x, "ul") for x in range(1, 9)]
p.mix(wells, volumes)

Concurrent mixes within multiple wells

# single-column concurrent mix
p.mix(plate.well(0), "5:ul", rows=8)

# 96-well concurrent mix in the A1 quadrant
p.mix(plate.well(0), "5:ul", rows=8, columns=12)

# 96-well concurrent mix in the A2 quadrant
p.mix(plate.well(1), "5:ul", rows=8, columns=12)

# 384-well concurrent mix
p.mix(plate.well(0), "5:ul", rows=16, columns=24)

Mix with extra parameters

from autoprotocol.liquid_handle import Mix
from autoprotocol.instruction import LiquidHandle

p.mix(
    plate.well(0), "5:ul", rows=8,
    method=Mix(
        mix_params=LiquidHandle.builders.mix(

        )
    )
)

See also

Mix

base LiquidHandleMethod for mix operations

spread(source: autoprotocol.container.Well, dest: autoprotocol.container.Well, volume: Union[str, autoprotocol.unit.Unit] = '50:microliter', dispense_speed: Union[str, autoprotocol.unit.Unit] = '20:microliter/second')

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

Uses a spiral pattern generated by a set of liquid_handle instructions.

Example Usage: .. code-block:: python

p = Protocol()

agar_plate = p.ref(“agar_plate”, None, “1-flat”, discard=True) bact = p.ref(“bacteria”, None, “micro-1.5”, discard=True)

p.spread(bact.well(0), agar_plate.well(0), “55:microliter”)

Parameters

• source (Well) – Source of material to spread on agar

• dest (Well) – Reference to destination location (plate containing agar)

• volume (str or Unit, optional) – Volume of source material to spread on agar

• dispense_speed (str or Unit, optional) – Speed at which to dispense source aliquot across agar surface

Returns

Returns a autoprotocol.instruction.LiquidHandle instruction created from the specified parameters

Return type

LiquidHandle

Raises

• TypeError – If specified source is not of type Well

• TypeError – If specified destination is not of type Well

evaporate(ref: autoprotocol.container.Container, mode: autoprotocol.types.protocol.EvaporateMode, duration: Union[str, autoprotocol.unit.Unit], evaporator_temperature: Union[str, autoprotocol.unit.Unit], mode_params: Optional[autoprotocol.types.protocol.EvaporateModeParams] = None)

Removes liquid or moisture from a container using the mode specified.

Example Usage:

p = Protocol()
c = p.ref("container", id=None,
          cont_type="micro-1.5", storage="cold_20")
blowdown_params = Evaporate.builders.get_mode_params(
                      mode="blowdown", mode_params={
                          "gas":"nitrogen",
                          "vortex_speed":Unit("200:rpm"),
                          "blow_rate": "200:uL/sec"
                      }
                  )
p.evaporate(
    c,
    mode="blowdown",
    duration="10:minute",
    evaporator_temperature="22:degC",
    mode_params = blowdown_params
)

{
    "op": "evaporate",
    "ref": "container",
    "mode": "blowdown",
    "duration": "10:minute",
    "evaporator_temperature": "22:degC",
    "mode_params": {
        "gas": "ntirogen",
        "vortex_speed": "200:rpm",
        "blow_rate": "200:uL/sec"
    }
}

Parameters

• ref (Container) – Sample container

• mode (Str) – The mode of evaporation method

• duration (Unit or Str) – The length of time the sample is evaporated for

• evaporator_temperature (Unit or str) – The incubation temperature of the sample being evaporated

• mode_params (Dict) – Dictionary of parameters for evaporation mode

Returns

Returns a autoprotocol.instruction.Evaporate instruction created from the specified parameters

Return type

Evaporate

Raises

• TypeError – If the provided object is not a Container type.

• ValueError – If the duration is less than 0 minute

• TypeError – If evaporator_temperature is not provided in Unit or str

• ValueError – If the evaporation_temperature is lower than or equal to condenser_temperature