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.Protocol(refs=None, instructions=None)¶

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

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

absorbance(ref, wells, wavelength, dataref, flashes=25, incubate_before=None, temperature=None, settle_time=None)¶

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

Example Usage:

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

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

Autoprotocol Output:

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

Parameters:	ref (str or Ref) – 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) – incubation prior to reading if desired { "shaking": { "amplitude": str or Unit "orbital": bool }, "duration": str or Unit }
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

acoustic_transfer(source, dest, volume, one_source=False, droplet_size='25:nanoliter')¶

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

Example Usage:

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

Autoprotocol Output:

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

Parameters:	source (Well or WellGroup or list(Well)) – Well or wells to transfer liquid from. If multiple source wells are supplied and one_source is set to True, liquid will be transferred from each source well specified as long as it contains sufficient volume. Otherwise, the number of source wells specified must match the number of destination wells specified and liquid will be transferred from each source well to its corresponding destination well. dest (Well or WellGroup or list(Well)) – Well or WellGroup to which to transfer liquid. The number of destination wells must match the number of source wells specified unless one_source is set to True. volume (str or Unit or list) – The volume(s) of liquid to be transferred from source wells to destination wells. Volume can be specified as a single string or Unit, or can be given as a list of volumes. The length of a list of volumes must match the number of destination wells given unless the same volume is to be transferred to each destination well. one_source (bool, optional) – Specify whether liquid is to be transferred to destination wells from a group of wells all containing the same substance. droplet_size (str or Unit, optional) – Volume representing a droplet_size. The volume of each transfer group should be a multiple of this volume.
Returns:	Returns the `autoprotocol.instruction.AcousticTransfer` instruction created from the specified parameters
Return type:	AcousticTransfer
Raises:	`TypeError` – Incorrect input types, e.g. source/dest are not Well or WellGroup or list of Well `RuntimeError` – Incorrect length for source and destination `RuntimeError` – Transfer volume not being a multiple of droplet size `RuntimeError` – Insufficient volume in source wells

add_time_constraint(from_dict, to_dict, less_than=None, more_than=None, mirror=False, ideal=None, optimization_cost=None)¶

Constraint the time between two instructions

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

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

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

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

Example Usage:

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

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

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

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

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

Autoprotocol Output:

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

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

Parameters:

from_dict (dict) –
Dictionary defining the initial time constraint condition. Composed of keys: “mark” and “state”

mark: int or Container

instruction index of container

state: “start” or “end”

specifies either the start or end of the “mark” point
to_dict (dict) – Dictionary defining the end time constraint condition. Specified in the same format as from_dict
less_than (str or Unit, optional) – max time between from_dict and to_dict
more_than (str or Unit, optional) – min time between from_dict and to_dict
mirror (bool, optional) – choice to mirror the from and to positions when time constraints should be added in both directions (only applies to the less_than constraint)
ideal (str or Unit, optional) – ideal time between from_dict and to_dict
optimization_cost (Enum({"linear", "squared", "exponential"}), optional) – cost function used for calculating the penalty for missing the ideal timing

Raises:

ValueError – If an instruction mark is less than 0
TypeError – If mark is not container or integer
TypeError – If state not in [‘start’, ‘end’]
TypeError – If any of ideal, more_than, less_than is not a Unit of the ‘time’ dimension
KeyError – If to_dict or from_dict does not contain ‘mark’
KeyError – If to_dict or from_dict does not contain ‘state’
ValueError – If time is less than ‘0:second’
ValueError – If optimization_cost is specified but ideal is not
ValueError – If more_than is greater than less_than
ValueError – If ideal is smaller than more_than or greater than less_than
RuntimeError – If from_dict and to_dict are equal
RuntimeError – If from_dict[“marker”] and to_dict[“marker”] are equal and from_dict[“state”] = “end”

as_dict()¶

Return the entire protocol as a dictionary.

Example Usage:

from autoprotocol.protocol import Protocol
import json

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

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

Autoprotocol Output:

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

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

autopick(sources, dests, min_abort=0, criteria=None, dataref='autopick')¶

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

Example Usage:

Autoprotocol Output:

Parameters:	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

batch_containers(containers, batch_in=True, batch_out=False)¶

Batch containers such that they all enter or exit together.

Example Usage:

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

protocol.batch_containers([plate_1, plate_2])

Autoprotocol Output:

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

Parameters:	containers (list(Container)) – Containers to batch batch_in (bool, optional) – Batch the entry of containers, default True batch_out (bool, optional) – Batch the exit of containers, default False
Raises:	`TypeError` – If containers is not a list `TypeError` – If containers is not a list of Container object

container_type(shortname)¶

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.

count_cells(wells, volume, dataref, labels=None)¶

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

Example Usage:

p = Protocol()

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

Autoprotocol Output:

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

Parameters:	wells (Well or list(Well) or WellGroup) – List of wells that will be used for cell counting. volume (Unit) – Volume that should be consumed from each well for the purpose of cell counting. dataref (str) – Name of dataset that will be returned. labels (list(string), optional) – Cells will be scored for presence or absence of each label in this list. If staining is required to visualize these labels, they must be added before execution of this instruction.
Returns:	Returns the `autoprotocol.instruction.CountCells` instruction created from the specified parameters
Return type:	CountCells
Raises:	`TypeError` – wells specified is not of a valid input type

cover(ref, lid=None, retrieve_lid=None)¶

Place specified lid type on specified container

Example Usage:

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

Autoprotocol Output:

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

Parameters:	ref (Container) – Container to be convered. lid (str, optional) – Type of lid to cover the container. Must be a valid lid type for the container type. retrieve_lid (bool, optional) – Flag to retrieve lid from previously stored location (see uncover).
Returns:	Returns the `autoprotocol.instruction.Cover` instruction created from the specified parameters
Return type:	Cover
Raises:	`TypeError` – If ref is not of type Container. `RuntimeError` – If container type does not have cover capability. `RuntimeError` – If lid is not a valid lid type. `RuntimeError` – If container is already sealed with a seal. `TypeError` – If retrieve_lid is not a boolean.

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)¶

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)¶

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

flash_freeze(container, duration)¶

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

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

Perform flow cytometry. The instruction will be executed within the voltage range specified for each channel, optimized for the best sample separation/distribution that can be achieved within these limits. The vendor will specify the device that this instruction is executed on and which excitation and emission spectra are available. At least one negative control is required, which will be used to define data acquisition parameters as well as to determine any autofluorescent properties for the sample set. Additional negative positive control samples are optional. Positive control samples will be used to optimize single color signals and, if desired, to minimize bleed into other channels.

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

Example Usage:

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

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

Autoprotocol Output:

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

Parameters:	dataref (str) – Name of flow analysis dataset generated. FSC (dict) – Dictionary containing FSC channel parameters in the form of: { "voltage_range": { "low": "230:volt", "high": "280:volt" }, "area": true, //default: true "height": true, //default: true "weight": false //default: false } SSC (dict) – Dictionary of SSC channel parameters in the form of: { "voltage_range": { "low": <voltage>, "high": <voltage>" }, "area": true, //default: true "height": true, //default: false "weight": false //default: false } neg_controls (list(dict)) – List of negative control wells in the form of: { "well": well, "volume": volume, "captured_events": integer, // optional, default infinity "channel": [channel_name] } at least one negative control is required. samples (list(dict)) – List of samples in the form of: { "well": well, "volume": volume, "captured_events": integer // optional, default infinity } at least one sample is required colors (list(dict), optional) – Optional list of colors in the form of: [ { "name": "FitC", "emission_wavelength": "495:nanometer", "excitation_wavelength": "519:nanometer", "voltage_range": { "low": <voltage>, "high": <voltage> }, "area": true, //default: true "height": false, //default: false "weight": false //default: false }, ... ] pos_controls (list(dict), optional) – Optional list of positive control wells in the form of: [ { "well": well, "volume": volume, "captured_events": integer, // default: infinity "channel": [channel_name], "minimize_bleed": [{ // optional "from": color, "to": [color] }, ... ]
Returns:	Returns the `autoprotocol.instruction.FlowAnalyze` instruction created from the specified parameters
Return type:	FlowAnalyze
Raises:	`TypeError` – If inputs are not of the correct type. `UnitError` – If unit inputs are not properly formatted. `AssertionError` – If required parameters are missing. `ValueError` – If volumes are not correctly formatted or present.

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)¶

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) – incubation prior to reading if desired 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 incubate_before example: { "shaking": { "amplitude": str or Unit "orbital": bool }, "duration": str or Unit } position_z examples: 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

gel_purify(extracts, volume, matrix, ladder, dataref)¶

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)) – Dictionary containing parameters for gel extraction, must be in the form of: [ { "band_list": [ { "band_size_range": { "max_bp": int, "min_bp": int }, "destination": Well, "elution_buffer": str, "elution_volume": Volume } ], "gel": int or None, "lane": int or None, "source": Well } ] util.make_gel_extract_params() and util.make_band_param() can be used to create these dictionaries band_list: list(dict) List of bands to be extracted from the lane band_size_range: dict Dictionary for the size range of the band to be extracted max_bp: int Maximum size for the band min_bp: int Minimum size for the band destination: Well Well to place the extracted material elution_buffer: str Buffer to use to extract the band, commonly “water” elution_volume: str or Unit Volume of elution_buffer to extract the band into gel: int Integer identifier for the gel if using multiple gels lane: int Integer identifier for the lane of a gel to run the source source: Well Well from which to purify the material 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.

gel_separate(wells, volume, matrix, ladder, duration, dataref)¶

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

get_instruction_index()¶

Get index of the last appended instruction

Example Usage:

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

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

Raises:	`ValueError` – If an instruction index is less than 0
Returns:	Index of the preceding instruction
Return type:	int

illuminaseq(flowcell, lanes, sequencer, mode, index, library_size, dataref, cycles=None)¶

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

Example Usage:

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

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

Autoprotocol Output:

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

Parameters:	flowcell (str) – Flowcell designation: “SR” or ” “PE” lanes (list(dict)) – "lanes": [ { "object": aliquot, Well, "library_concentration": decimal, // ng/uL }, {...}] sequencer (str) – Sequencer designation: “miseq”, “hiseq” or “nextseq” mode (str) – Mode designation: “rapid”, “mid” or “high” index (str) – Index designation: “single”, “dual” or “none” library_size (int) – Library size expressed as an integer of basepairs dataref (str) – Name of sequencing dataset that will be returned. cycles (Enum({"read_1", "read_2", "index_1", "index_2"})) – Parameter specific to Illuminaseq read-length or number of sequenced bases. Refer to the ASC for more details
Returns:	Returns the `autoprotocol.instruction.IlluminaSeq` instruction created from the specified parameters
Return type:	IlluminaSeq
Raises:	`TypeError` – If index and dataref are not of type str. `TypeError` – If library_concentration is not a number. `TypeError` – If library_size is not an integer. `ValueError` – If flowcell, sequencer, mode, index are not of type a valid option. `ValueError` – If number of lanes specified is more than the maximum lanes of the specified type of sequencer. `KeyError` – Invalid keys specified for cycles parameter

image_plate(ref, mode, dataref)¶

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

incubate(ref, where, duration, shaking=False, co2=0, uncovered=False, target_temperature=None, shaking_params=None)¶

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

Example Usage:

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

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

Autoprotocol Output:

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

Parameters:	ref (Ref or str) – The container to be incubated where (Enum({"ambient", "warm_37", "cold_4", "cold_20", "cold_80"})) – Temperature at which to incubate specified container duration (Unit or str) – Length of time to incubate container shaking (bool, optional) – Specify whether or not to shake container if available at the specified temperature co2 (int, 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

luminescence(ref, wells, dataref, incubate_before=None, temperature=None, settle_time=None, integration_time=None)¶

Read luminescence of indicated wells.

Example Usage:

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

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

Autoprotocol Output:

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

Parameters:	ref (str or Container) – Container to plate read. wells (list(Well) or WellGroup or Well) – WellGroup of wells to be measured or a list of well references in the form of [“A1”, “B1”, “C5”, …] dataref (str) – Name of this dataset of measured luminescence readings. temperature (str or Unit, optional) – set temperature to heat plate reading chamber settle_time (Unit, optional) – the time before the start of the measurement, defaults to vendor specifications incubate_before (dict, optional) – incubation prior to reading if desired integration_time (Unit, optional) – duration of the signal recording, per Well, defaults to vendor specifications { "shaking": { "amplitude": str or Unit "orbital": bool }, "duration": str or Unit }
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

mag_collect(head, container, cycles, pause_duration, bottom_position=0.0, temperature=None, new_tip=False, new_instruction=False)¶

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

Example Usage:

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

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

Autoprotocol Output:

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

Parameters:	head (str) – Magnetic head to use for the magnetic bead transfers container (Container) – Container to incubate beads cycles (int) – Number of cycles to raise and lower tips pause_duration (str or Unit) – Time tips are paused in bottom position each cycle bottom_position (float) – Position relative to well height that tips are held during pause temperature (str or Unit) – Temperature heat block is set at new_tip (bool) – Specify whether to use a new tip to complete the step new_instruction (bool) – Specify whether to create a new magnetic_transfer instruction
Returns:	Returns the `autoprotocol.instruction.MagneticTransfer` instruction created from the specified parameters
Return type:	MagneticTransfer

mag_dry(head, container, duration, new_tip=False, new_instruction=False)¶

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

Example Usage:

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

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

Autoprotocol Output:

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

Parameters:	head (str) – Magnetic head to use for the magnetic bead transfers container (Container) – Container to dry beads above duration (str or Unit) – Time for drying new_tip (bool) – Specify whether to use a new tip to complete the step new_instruction (bool) – Specify whether to create a new magnetic_transfer instruction
Returns:	Returns the `autoprotocol.instruction.MagneticTransfer` instruction created from the specified parameters
Return type:	MagneticTransfer

mag_incubate(head, container, duration, magnetize=False, tip_position=1.5, temperature=None, new_tip=False, new_instruction=False)¶

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

Example Usage:

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

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

Autoprotocol Output:

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

Parameters:	head (str) – Magnetic head to use for the magnetic bead transfers container (Container) – Container to incubate beads duration (str or Unit) – Time for incubation magnetize (bool) – Specify whether to magnetize the tips tip_position (float) – Position relative to well height that tips are held temperature (str or Unit) – 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)¶

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

mag_release(head, container, duration, frequency, center=0.5, amplitude=0.5, temperature=None, new_tip=False, new_instruction=False)¶

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

Example Usage:

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

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

Autoprotocol Output:

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

Parameters:	head (str) – Magnetic head to use for the magnetic bead transfers container (Container) – Container to incubate beads duration (str or Unit) – Total time for this sub-operation frequency (str or Unit) – Cycles per second (hertz) that tips are raised and lowered center (float) – Position relative to well height where oscillation is centered amplitude (float) – Distance relative to well height to oscillate around “center” temperature (str or Unit) – Temperature heat block is set at new_tip (bool) – Specify whether to use a new tip to complete the step new_instruction (bool) – Specify whether to create a new magnetic_transfer instruction
Returns:	Returns the `autoprotocol.instruction.MagneticTransfer` instruction created from the specified parameters
Return type:	MagneticTransfer

measure_concentration(wells, dataref, measurement, volume='2:microliter')¶

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

Example Usage:

p = Protocol()

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

Autoprotocol Output:

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

Parameters:	wells (list(Well) or WellGroup or Well) – WellGroup of wells to be measured volume (str or Unit) – Volume of sample required for analysis dataref (str) – Name of this specific dataset of measurements measurement (str) – Class of material to be measured. One of [“DNA”, “ssDNA”, “RNA”, “protein”].
Returns:	Returns the `autoprotocol.instruction.MeasureConcentration` instruction created from the specified parameters
Return type:	MeasureConcentration
Raises:	`TypeError` – wells specified is not of a valid input type

measure_mass(container, dataref)¶

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)¶

Measure the volume of each well in wells.

Example Usage:

p = Protocol()

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

Autoprotocol Output:

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

Parameters:	wells (list(Well) or WellGroup or Well) – list of wells to be measured dataref (str) – Name of this specific dataset of measurements
Returns:	Returns the `autoprotocol.instruction.MeasureVolume` instruction created from the specified parameters
Return type:	MeasureVolume
Raises:	`TypeError` – wells specified is not of a valid input type

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)¶

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

oligosynthesize(oligos)¶

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

provision(resource_id, dests, volumes)¶

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

ref(name, id=None, cont_type=None, storage=None, discard=None, cover=None)¶

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

Example Usage:

p = Protocol()

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

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

Autoprotocol Output:

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

Parameters:	name (str) – name of the container/ref being created. id (str) – 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 (existant 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.

sangerseq(cont, wells, dataref, type='standard', primer=None)¶

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

Example Usage:

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

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

Autoprotocol Output:

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

Parameters:	cont (Container or str) – Container with well(s) that contain material to be sequenced. wells (list(Well) or WellGroup or Well) – WellGroup of wells to be measured or a list of well references in the form of [“A1”, “B1”, “C5”, …] dataref (str) – Name of sequencing dataset that will be returned. type (Enum({"standard", "rca"})) – Sanger sequencing type primer (Container, optional) – Tube containing sufficient primer for all RCA reactions. This field will be ignored if you specify the sequencing type as “standard”. Tube containing sufficient primer for all RCA reactions
Returns:	Returns the `autoprotocol.instruction.SangerSeq` instruction created from the specified parameters
Return type:	SangerSeq
Raises:	`RuntimeError` – No primer location specified for rca sequencing type `ValueError` – Wells belong to more than one container `TypeError` – Invalid input type for wells

seal(ref, type=None, mode=None, temperature=None, duration=None)¶

Seal indicated container using the automated plate sealer.

Example Usage:

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

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

Autoprotocol Output:

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

Parameters:	ref (Container) – Container to be sealed type (str, optional) – Seal type to be used, such as “ultra-clear” or “foil”. mode (str, optional) – Sealing method to be used, such as “thermal” or “adhesive”. Defaults to None, which is interpreted sensibly based on the execution environment. temperature (Unit or str, optional) – Temperature at which to melt the sealing film onto the ref. Only applicable to thermal sealing; not respected if the sealing mode is adhesive. If unspecified, thermal sealing temperature defaults correspond with manufacturer-recommended or internally-optimized values for the target container type. Applies only to thermal sealing. duration (Unit or str, optional) – Duration for which to press the (heated, if thermal) seal down on the ref. Defaults to manufacturer-recommended or internally- optimized seal times for the target container type. Currently applies only to thermal sealing.
Returns:	Returns the `autoprotocol.instruction.Seal` instruction created from the specified parameters
Return type:	Seal
Raises:	`TypeError` – If ref is not of type Container. `RuntimeError` – If container type does not have seal capability. `RuntimeError` – If seal is not a valid seal type. `RuntimeError` – If the sealing mode is invalid, or incompatible with the given ref `RuntimeError` – If thermal sealing params (temperature and/or duration) are specified alongside an adhesive sealing mode. `RuntimeError` – If specified thermal sealing parameters are invalid `RuntimeError` – If container is already covered with a lid.

spectrophotometry(dataref, obj, groups, interval=None, num_intervals=None, temperature=None, shake_before=None)¶

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

Example Usage:

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

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

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

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

Autoprotocol Output:

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

Parameters:	dataref (str) – Name of the resultant dataset to be returned. obj (Container or str) – Container to be read. groups (list) – A list of groups generated by SpectrophotometryBuilders groups builders, any of absorbance_mode_params, fluorescence_mode_params, luminescence_mode_params, or shake_mode_params. interval (Unit or str, optional) – The time between each of the read intervals. num_intervals (int, optional) – The number of times that the groups should be executed. temperature (Unit or str, optional) – The temperature that the entire instruction should be executed at. shake_before (dict, optional) – A dict of params generated by SpectrophotometryBuilders.shake_before that dictates how the obj should be incubated with shaking before any of the groups are executed.
Returns:	Returns the `autoprotocol.instruction.Spectrophotometry` instruction created from the specified parameters
Return type:	Spectrophotometry
Raises:	`TypeError` – Invalid num_intervals specified, must be an int `ValueError` – No interval specified but shake groups specified with no duration

spin(ref, acceleration, duration, flow_direction=None, spin_direction=None)¶

Apply acceleration to a container.

Example Usage:

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

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

Autoprotocol Output:

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

Parameters:	ref (Container) – The container to be centrifuged. acceleration (str) – Acceleration to be applied to the plate, in units of g or meter/second^2. duration (str or Unit) – Length of time that acceleration should be applied. flow_direction (str) – Specifies the direction contents will tend toward with respect to the container. Valid directions are “inward” and “outward”, default value is “inward”. spin_direction (list(str)) – A list of “cw” (clockwise), “cww” (counterclockwise). For each element in the list, the container will be spun in the stated direction for the set “acceleration” and “duration”. Default values are derived from the “flow_direction” parameter. If “flow_direction” is “outward”, then “spin_direction” defaults to [“cw”, “ccw”]. If “flow_direction” is “inward”, then “spin_direction” defaults to [“cw”].
Returns:	Returns the `autoprotocol.instruction.Spin` instruction created from the specified parameters
Return type:	Spin
Raises:	`TypeError` – If ref to spin is not of type Container. `TypeError` – If spin_direction or flow_direction are not properly formatted. `ValueError` – If spin_direction or flow_direction do not have appropriate values.

spread(source, dest, volume='50:microliter', dispense_speed='20:microliter/second')¶

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

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

Example Usage: .. code-block:: python

p = Protocol()

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

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

Parameters:	source (Well) – Source of material to spread on agar dest (Well) – Reference to destination location (plate containing agar) volume (str or Unit, optional) – Volume of source material to spread on agar dispense_speed (str or Unit, optional) – Speed at which to dispense source aliquot across agar surface
Returns:	Returns a `autoprotocol.instruction.LiquidHandle` instruction created from the specified parameters
Return type:	LiquidHandle
Raises:	`TypeError` – If specified source is not of type Well `TypeError` – If specified destination is not of type Well

store(container, condition)¶

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

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)¶

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

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)¶

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.