autoprotocol.protocol module

Module containing the main Protocol object and associated functions

copyright:2018 by The Autoprotocol Development Team, see AUTHORS for more details.
license:BSD, see LICENSE for more details
class autoprotocol.protocol.Ref(name, opts, container)[source]

Link a ref name (string) to a Container instance.

class autoprotocol.protocol.Protocol(refs=None, instructions=None, propagate_properties=False)[source]

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.

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)[source]

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, id=None, cont_type=None, storage=None, discard=None, cover=None)[source]

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
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, to_dict, less_than=None, more_than=None, mirror=False, ideal=None, optimization_cost=None)[source]

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()[source]

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, batch_in=True, batch_out=False)[source]

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()[source]

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
store(container, condition)[source]

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, dest, volume, one_source=False, droplet_size='25:nanoliter')[source]

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
  • 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, lanes, sequencer, mode, index, library_size, dataref, cycles=None)[source]

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, wells, dataref, type='standard', primer=None)[source]

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, reagent, columns, is_resource_id=False, step_size='5:uL', flowrate=None, nozzle_position=None, pre_dispense=None, shape=None, shake_after=None)[source]

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 either 5 uL or 0.5 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, reagent, volume, is_resource_id=False, step_size='5:uL', flowrate=None, nozzle_position=None, pre_dispense=None, shape=None, shake_after=None)[source]

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 be either 5 uL or 0.5 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, acceleration, duration, flow_direction=None, spin_direction=None)[source]

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.
thermocycle(ref, groups, volume='10:microliter', dataref=None, dyes=None, melting_start=None, melting_end=None, melting_increment=None, melting_rate=None, lid_temperature=None)[source]

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, where, duration, shaking=False, co2=0, uncovered=False, target_temperature=None, shaking_params=None)[source]

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, wells, wavelength, dataref, flashes=25, incubate_before=None, temperature=None, settle_time=None)[source]

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, wells, excitation, emission, dataref, flashes=25, temperature=None, gain=None, incubate_before=None, detection_mode=None, position_z=None, settle_time=None, lag_time=None, integration_time=None)[source]

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, wells, dataref, incubate_before=None, temperature=None, settle_time=None, integration_time=None)[source]

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, volume, matrix, ladder, duration, dataref)[source]

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, volume, matrix, ladder, dataref)[source]

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, type=None, mode=None, temperature=None, duration=None)[source]

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)[source]

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, lid=None, retrieve_lid=None)[source]

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, store_lid=None)[source]

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, samples, lasers, collection_conditions, width_threshold=None, window_extension=None, remove_coincident_events=None)[source]

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, FSC, SSC, neg_controls, samples, colors=None, pos_controls=None)[source]

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)[source]

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(sources, dests, min_abort=0, criteria=None, dataref='autopick')[source]

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:
  • sources (Well or WellGroup or list(Well)) – Reference wells containing agar and colonies to pick
  • dests (Well or WellGroup or list(Well)) – List of destination(s) for picked colonies
  • criteria (dict) – Dictionary of autopicking criteria.
  • min_abort (int, optional) – Total number of colonies that must be detected in the aggregate list of from wells to avoid aborting the entire run.
  • 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, container, duration, new_tip=False, new_instruction=False)[source]

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, container, duration, magnetize=False, tip_position=1.5, temperature=None, new_tip=False, new_instruction=False)[source]

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, container, cycles, pause_duration, bottom_position=0.0, temperature=None, new_tip=False, new_instruction=False)[source]

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, container, duration, frequency, center=0.5, amplitude=0.5, temperature=None, new_tip=False, new_instruction=False)[source]

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, container, duration, frequency, center=0.5, amplitude=0.5, magnetize=False, temperature=None, new_tip=False, new_instruction=False)[source]

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, mode, dataref)[source]

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, dests, volumes)[source]

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.
  • volumes (str or Unit or list(str) or list(Unit)) – Volume(s) to transfer of the resource to each destination well. If one volume of specified, each destination well recieve that volume of the resource. If destinations should recieve different volumes, each one should be specified explicitly in a list matching the order of the specified destinations.
Raises:
  • TypeError – If resource_id is not a string.
  • RuntimeError – If length of the list of volumes specified does not match the number of destination wells specified.
  • TypeError – If volume is not specified as a string or Unit (or a list of either)
  • ValueError – Volume to provision exceeds max capacity of well
Returns:

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

Return type:

Provision

flash_freeze(container, duration)[source]

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

measure_concentration(wells, dataref, measurement, volume='2:microliter')[source]

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:

TypeErrorwells specified is not of a valid input type

measure_mass(container, dataref)[source]

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, dataref)[source]

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:

TypeErrorwells specified is not of a valid input type

count_cells(wells, volume, dataref, labels=None)[source]

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:

TypeErrorwells specified is not of a valid input type

spectrophotometry(dataref, obj, groups, interval=None, num_intervals=None, temperature=None, shake_before=None)[source]

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, destination, volume, rows=1, columns=1, source_liquid=<class 'autoprotocol.liquid_handle.liquid_class.LiquidClass'>, destination_liquid=<class 'autoprotocol.liquid_handle.liquid_class.LiquidClass'>, method=<class 'autoprotocol.liquid_handle.transfer.Transfer'>, one_tip=False)[source]

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
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, volume, rows=1, columns=1, liquid=<class 'autoprotocol.liquid_handle.liquid_class.LiquidClass'>, method=<class 'autoprotocol.liquid_handle.mix.Mix'>, one_tip=False)[source]

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
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, dest, volume='50:microliter', dispense_speed='20:microliter/second')[source]

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