autoprotocol.builders

Builders Module containing builders, which help build inputs for Instruction parameters

copyright:2018 by The Autoprotocol Development Team, see AUTHORS for more details.
license:BSD, see LICENSE for more details

Summary

These builder methods are used to generate and validate complex data structures used in Autoprotocol specification. Each of them is capable of using their own output as input. Therefore these builders are also used as inline checks in Protocol methods.

Notes

Generally these builders should not be called from this file directly. They’re more easily accessible by referencing a specific Instruction’s builders attribute (e.g. Spectrophotometry.Builders.mode_params).

See also

Instruction
Instructions corresponding to each of the builders
class autoprotocol.builders.DispenseBuilders

These builders are meant for helping to construct arguments in the Protocol.dispense method.

__delattr__

x.__delattr__(‘name’) <==> del x.name

__format__()

default object formatter

__getattribute__

x.__getattribute__(‘name’) <==> x.name

__hash__
__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__repr__
__setattr__

x.__setattr__(‘name’, value) <==> x.name = value

__sizeof__() → int

size of object in memory, in bytes

__str__
static column(column, volume)

Generates a validated column parameter.

Parameters:
  • column (int) –
  • volume (str, Unit) –
Returns:

Column parameter of type {“column”: int, “volume”: Unit}
Return type:

dict
columns(columns)

Generates a validated columns parameter.

Parameters:

columns (list({"column": int, "volume": str, Unit})) –

Returns:

List of columns of type ({“column”: int, “volume”: str, Unit})
Return type:

list
Raises:
  • ValueError – No column specified for columns
  • ValueError – Non-unique column indices
static nozzle_position(position_x=None, position_y=None, position_z=None)

Generates a validated nozzle_position parameter.

Parameters:
  • position_x (Unit, optional) –
  • position_y (Unit, optional) –
  • position_z (Unit, optional) –
Returns:

Dictionary of nozzle position parameters
Return type:

dict
shake_after(duration, frequency=None, path=None, amplitude=None)

Generates a validated shake_after parameter.

Parameters:
  • duration (Unit, str) –
  • frequency (Unit, str, optional) –
  • path (str, optional) –
  • amplitude (Unit, str, optional) –
Returns:

Shake after dictionary of type {“duration”: Unit, “frequency”: Unit, “path”: str, “amplitude”: Unit}
Return type:

dict
Raises:

ValueError – Invalid shake path specified
shape(rows=1, columns=1, format=None)

Helper function for building a shape dictionary

Parameters:
  • rows (int, optional) – Number of rows to be concurrently transferred
  • columns (int, optional) – Number of columns to be concurrently transferred
  • format (str, optional) – Plate format in String form. e.g. “SBS96” or “SBS384”
Returns:

shape parameters
Return type:

dict
Raises:
  • TypeError – If rows/columns aren’t ints
  • ValueError – If an invalid row/column count is given
  • ValueError – If an invalid shape is given
  • ValueError – If rows/columns are greater than what is allowed for the format
class autoprotocol.builders.InstructionBuilders

General builders that apply to multiple instructions

__delattr__

x.__delattr__(‘name’) <==> del x.name

__format__()

default object formatter

__getattribute__

x.__getattribute__(‘name’) <==> x.name

__hash__
__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__repr__
__setattr__

x.__setattr__(‘name’, value) <==> x.name = value

__sizeof__() → int

size of object in memory, in bytes

__str__
shape(rows=1, columns=1, format=None)

Helper function for building a shape dictionary

Parameters:
  • rows (int, optional) – Number of rows to be concurrently transferred
  • columns (int, optional) – Number of columns to be concurrently transferred
  • format (str, optional) – Plate format in String form. e.g. “SBS96” or “SBS384”
Returns:

shape parameters
Return type:

dict
Raises:
  • TypeError – If rows/columns aren’t ints
  • ValueError – If an invalid row/column count is given
  • ValueError – If an invalid shape is given
  • ValueError – If rows/columns are greater than what is allowed for the format
class autoprotocol.builders.LiquidHandleBuilders

Builders for LiquidHandle Instructions

__delattr__

x.__delattr__(‘name’) <==> del x.name

__format__()

default object formatter

__getattribute__

x.__getattribute__(‘name’) <==> x.name

__hash__
__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__repr__
__setattr__

x.__setattr__(‘name’, value) <==> x.name = value

__sizeof__() → int

size of object in memory, in bytes

__str__
blowout(volume, initial_z, flowrate=None)

Helper for building blowout params for LiquidHandleMethods

Parameters:
  • volume (Unit or str) – the volume of the blowout step
  • initial_z (dict) – the position that the tip should move to prior to blowing out See Also LiquidHandle.builders.position_z
  • flowrate (dict, optional) – the flowrate of the blowout See Also LiquidHandle.builders.flowrate
Returns:

blowout params for a LiquidHandleMethod
Return type:

dict
static flowrate(target, initial=None, cutoff=None, acceleration=None, deceleration=None)

Helper for building flowrates

Parameters:
  • target (Unit or str) – Target flowrate
  • initial (Unit or str, optional) – Initial flowrate
  • cutoff (Unit or str, optional) – Cutoff flowrate
  • acceleration (Unit or str, optional) – Volumetric acceleration for initial to target (in ul/s^2)
  • deceleration (Unit or str, optional) – Volumetric deceleration for target to cutoff (in ul/s^2)
Returns:

flowrate parameters for a LiquidHandle instruction
Return type:

dict
static instruction_mode_params(tip_type=None)

Helper for building instruction mode_params

Parameters:tip_type (str, optional) – the string representation ofa tip_type See Also tip_type.py
Returns:mode_params for a LiquidHandle instruction
Return type:dict
location(location=None, transports=None)

Helper for building locations

Parameters:
  • location (Well or str, optional) – Location refers to the well location where the transports will be carried out
  • transports (list(dict), optional) – Transports refer to the list of transports that will be carried out in the specified location See Also LiquidHandle.builders.transport
Returns:

location parameters for a LiquidHandle instruction
Return type:

dict
Raises:
  • TypeError – If locations aren’t str/well
  • ValueError – If transports are specified, but empty
mix(volume, repetitions, initial_z, asp_flowrate=None, dsp_flowrate=None)

Helper for building mix params for Transfer LiquidHandleMethods

Parameters:
  • volume (Unit or str) – the volume of the mix step
  • repetitions (int) – the number of times that the mix should be repeated
  • initial_z (dict) – the position that the tip should move to prior to mixing See Also LiquidHandle.builders.position_z
  • asp_flowrate (dict, optional) – the flowrate of the aspiration portions of the mix See Also LiquidHandle.builders.flowrate
  • dsp_flowrate (dict, optional) – the flowrate of the dispense portions of the mix See Also LiquidHandle.builders.flowrate
Returns:

mix parameters for a LiquidHandleMethod
Return type:

dict
Raises:

TypeError – If repetitions is not an int
mode_params(liquid_class=None, position_x=None, position_y=None, position_z=None, tip_position=None)

Helper for building transport mode_params

Mode params contain information about tip positioning and the liquid being manipulated

Parameters:
  • liquid_class (Enum({"default", "air"}), optional) – The name of the liquid class to be handled. This affects how vendors handle populating liquid handling defaults.
  • position_x (dict, optional) – Target relative x-position of tip in well. See Also LiquidHandle.builders.position_xy
  • position_y (dict, optional) – Target relative y-position of tip in well. See Also LiquidHandle.builders.position_xy
  • position_z (dict, optional) – Target relative z-position of tip in well. See Also LiquidHandle.builders.position_z
  • tip_position (dict, optional) – A dict of positions x, y, and z. Should only be specified if none of the other tip position parameters have been specified.
Returns:

mode_params for a LiquidHandle instruction
Return type:

dict
Raises:
  • ValueError – If liquid_class is not in the allowed list
  • ValueError – If both position_x|y|z and tip_position are specified
static move_rate(target=None, acceleration=None)

Helper for building move_rates

Parameters:
  • target (Unit or str, optional) – Target velocity. Must be in units of
  • acceleration (Unit or str, optional) – Acceleration. Must be in units of
Returns:

move_rate parameters for a LiquidHandle instruction
Return type:

dict
position_xy(position=None, move_rate=None)

Helper for building position_x and position_y parameters

Parameters:
  • position (Numeric, optional) – Target relative x/y-position of tip in well in unit square coordinates.
  • move_rate (dict, optional) – The rate at which the tip moves in the well See Also LiquidHandle.builders.move_rate
Returns:

position_xy parameters for a LiquidHandle instruction
Return type:

dict
Raises:
  • TypeError – If position is non-numeric
  • ValueError – If position is not in range
position_z(reference=None, offset=None, move_rate=None, detection_method=None, detection_threshold=None, detection_duration=None, detection_fallback=None, detection=None)

Helper for building position_z parameters

Parameters:
  • reference (str, optional) –
    Must be one of “well_top”, “well_bottom”, “liquid_surface”,
    ”preceding_position”
  • offset (Unit or str, optional) – Offset from reference position
  • move_rate (dict, optional) – Controls the rate at which the tip moves in the well See Also LiquidHandle.builders.move_rate
  • detection_method (str, optional) – Must be one of “tracked”, “pressure”, “capacitance”
  • detection_threshold (Unit or str, optional) – The threshold which must be crossed before a positive reading is registered. This is applicable for capacitance and pressure detection methods
  • detection_duration (Unit or str, optional) – The contiguous duration where the threshold must be crossed before a positive reading is registered. This is applicable for pressure detection methods
  • detection_fallback (dict, optional) – Fallback option which will be used if sensing fails See Also LiquidHandle.builders.position_z
  • detection (dict, optional) – A dict of detection parameters. Should only be specified if none of the other detection parameters have been specified.
Returns:

position_z parameters for a LiquidHandle instruction
Return type:

dict
Raises:
  • ValueError – If reference was not in the allowed list
  • ValueError – If both detection_method|duration|threshold|fallback and detection are specified
  • ValueError – If detection_method is not in the allowed list
  • ValueError – If detection parameters were specified, but the reference position doesn’t support detection
shape(rows=1, columns=1, format=None)

Helper function for building a shape dictionary

Parameters:
  • rows (int, optional) – Number of rows to be concurrently transferred
  • columns (int, optional) – Number of columns to be concurrently transferred
  • format (str, optional) – Plate format in String form. e.g. “SBS96” or “SBS384”
Returns:

shape parameters
Return type:

dict
Raises:
  • TypeError – If rows/columns aren’t ints
  • ValueError – If an invalid row/column count is given
  • ValueError – If an invalid shape is given
  • ValueError – If rows/columns are greater than what is allowed for the format
transport(volume=None, pump_override_volume=None, flowrate=None, delay_time=None, mode_params=None)

Helper for building transports

Parameters:
  • volume (Unit or str, optional) – Volume to be aspirated/dispensed. Positive volume -> Dispense. Negative -> Aspirate
  • pump_override_volume (Unit or str, optional) – Calibrated volume, volume which the pump will move
  • flowrate (dict, optional) – Flowrate parameters See Also LiquidHandle.builders.flowrate
  • delay_time (Unit or str, optional) – Time spent waiting after executing mandrel and pump movement
  • mode_params (dict, optional) – Mode parameters See Also LiquidHandle.builders.mode_params
Returns:

transport parameters for a LiquidHandle instruction
Return type:

dict
class autoprotocol.builders.SpectrophotometryBuilders

These builders are meant for helping to construct arguments for the Spectrophotometry instruction.

__delattr__

x.__delattr__(‘name’) <==> del x.name

__format__()

default object formatter

__getattribute__

x.__getattribute__(‘name’) <==> x.name

__hash__
__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__repr__
__setattr__

x.__setattr__(‘name’, value) <==> x.name = value

__sizeof__() → int

size of object in memory, in bytes

__str__
static absorbance_mode_params(wells, wavelength, num_flashes=None, settle_time=None)
Parameters:
  • wells (iterable(Well) or WellGroup) – Wells to be read.
  • wavelength (Unit or str) – The wavelengths at which to make absorbance measurements.
  • num_flashes (int, optional) – The number of discrete reads to be taken and then averaged.
  • settle_time (Unit or str, optional) – The time to wait between moving to a well and reading it.
Returns:

Formatted mode_params for an absorbance mode.
Return type:

dict
Raises:
  • TypeError – Invalid type specified for input parameters, e.g. num_flashes not of type int
  • ValueError – Invalid wells specified
fluorescence_mode_params(wells, excitation, emission, num_flashes=None, settle_time=None, lag_time=None, integration_time=None, gain=None, read_position=None)
Parameters:
  • wells (iterable(Well) or WellGroup) – Wells to be read.
  • excitation (list(dict)) – A list of SpectrophotometryBuilders.wavelength_selection to determine the wavelegnth(s) of excitation light used.
  • emission (list(dict)) – A list of SpectrophotometryBuilders.wavelength_selection to determine the wavelegnth(s) of emission light used.
  • num_flashes (int, optional) – The number of discrete reads to be taken and then combined.
  • settle_time (Unit or str, optional) – The time to wait between moving to a well and reading it.
  • lag_time (Unit or str, optional) – The time to wait between excitation and reading.
  • integration_time (Unit or str, optional) – Time over which the data should be collected and integrated.
  • gain (int, optional) – The amount of gain to be applied to the readings.
  • read_position (str, optional) – The position from which the wells should be read.
Returns:

Formatted mode_params for a fluorescence mode.
Return type:

dict
Raises:
  • TypeError – Invalid input types, e.g. settle_time is not of type Unit(second)
  • ValueError – Invalid wells specified
  • ValueError – Gain is not between 0 and 1
group(mode, mode_params)
Parameters:
  • mode (str) – A string representation of a valid spectrophotometry mode.
  • mode_params (dict) – A dict of mode_params corresponding to the mode.
Returns:

A spectrophotometry group.
Return type:

dict
Raises:

ValueError – Invalid mode specified
groups(groups)
Parameters:groups (list(dict)) – A list of spectrophotometry groups.
Returns:A list of spectrophotometry groups.
Return type:list(dict)
static luminescence_mode_params(wells, num_flashes=None, settle_time=None, integration_time=None, gain=None)
Parameters:
  • wells (iterable(Well) or WellGroup) – Wells to be read.
  • num_flashes (int, optional) – The number of discrete reads to be taken and then combined.
  • settle_time (Unit or str, optional) – The time to wait between moving to a well and reading it.
  • integration_time (Unit or str, optional) – Time over which the data should be collected and integrated.
  • gain (int, optional) – The amount of gain to be applied to the readings.
Returns:

Formatted mode_params for a luminescence mode.
Return type:

dict
Raises:
  • TypeError – Invalid input types, e.g. settle_time is not of type Unit(second)
  • ValueError – Gain is not between 0 and 1
shake_before(duration, frequency=None, path=None, amplitude=None)
Parameters:
  • duration (Unit or str) – The duration of the shaking incubation.
  • frequency (Unit or str, optional) – The frequency of the shaking motion.
  • path (str, optional) – The name of a shake path. See the spectrophotometry ASC for diagrams of different shake paths.
  • amplitude (Unit or str, optional) – The amplitude of the shaking motion.
Returns:

Formatted mode_params for a shake mode.
Return type:

dict
shake_mode_params(duration=None, frequency=None, path=None, amplitude=None)
Parameters:
  • duration (Unit or str, optional) – The duration of the shaking incubation, if not specified then the incubate will last until the end of read interval.
  • frequency (Unit or str, optional) – The frequency of the shaking motion.
  • path (str, optional) – The name of a shake path. See the spectrophotometry ASC for diagrams of different shake paths.
  • amplitude (Unit or str, optional) – The amplitude of the shaking motion.
Returns:

Formatted mode_params for a shake mode.
Return type:

dict
shape(rows=1, columns=1, format=None)

Helper function for building a shape dictionary

Parameters:
  • rows (int, optional) – Number of rows to be concurrently transferred
  • columns (int, optional) – Number of columns to be concurrently transferred
  • format (str, optional) – Plate format in String form. e.g. “SBS96” or “SBS384”
Returns:

shape parameters
Return type:

dict
Raises:
  • TypeError – If rows/columns aren’t ints
  • ValueError – If an invalid row/column count is given
  • ValueError – If an invalid shape is given
  • ValueError – If rows/columns are greater than what is allowed for the format
static wavelength_selection(shortpass=None, longpass=None, ideal=None)

Generates a representation of a wavelength selection by either filters (using shortpass/longpass) or monochromators (using ideal)

Parameters:
  • shortpass (Unit, str, optional) –
  • longpass (Unit, str, optional) –
  • ideal (Unit, str, optional) –
Returns:

Wavelength selection parameters.
Return type:

dict
class autoprotocol.builders.ThermocycleBuilders

These builders are meant for helping to construct the groups argument in the Protocol.thermocycle method

__delattr__

x.__delattr__(‘name’) <==> del x.name

__format__()

default object formatter

__getattribute__

x.__getattribute__(‘name’) <==> x.name

__hash__
__reduce__()

helper for pickle

__reduce_ex__()

helper for pickle

__repr__
__setattr__

x.__setattr__(‘name’, value) <==> x.name = value

__sizeof__() → int

size of object in memory, in bytes

__str__
group(steps, cycles=1)

Helper function for creating a thermocycle group, which is a series of steps repeated for the number of cycles

Parameters:
  • steps (list(ThermocycleBuilders.step)) – Steps to be carried out. At least one step has to be specified. See ThermocycleBuilders.step for more information
  • cycles (int, optional) – Number of cycles to repeat the specified steps. Defaults to 1
Returns:

A thermocycling group
Return type:

dict
Raises:
  • TypeError – Invalid input types, i.e. cycles is not of type int and steps is not of type list
  • ValueError – cycles is not positive
  • ValueError – steps does not contain any elements
shape(rows=1, columns=1, format=None)

Helper function for building a shape dictionary

Parameters:
  • rows (int, optional) – Number of rows to be concurrently transferred
  • columns (int, optional) – Number of columns to be concurrently transferred
  • format (str, optional) – Plate format in String form. e.g. “SBS96” or “SBS384”
Returns:

shape parameters
Return type:

dict
Raises:
  • TypeError – If rows/columns aren’t ints
  • ValueError – If an invalid row/column count is given
  • ValueError – If an invalid shape is given
  • ValueError – If rows/columns are greater than what is allowed for the format
static step(temperature, duration, read=None)

Helper function for creating a thermocycle step.

Parameters:
  • temperature (Unit or dict(str, Unit)) –

    Block temperature which the contents should be thermocycled at.

    If a gradient thermocycle is desired, specifying a dict with “top” and “bottom” keys will control the desired temperature at the top and bottom rows of the block, creating a gradient along the column.

    ..code-block:: python

    temperature = {“top”: “50:celsius”, “bottom”: “45:celsius”}
  • duration (str or Unit) – Duration where the specified temperature parameters will be applied
  • read (Boolean, optional) – Determines if a read at wavelengths specified by the dyes in the parent thermocycle instruction will be enabled for this particular step. Useful for qPCR applications.
Returns:

A thermocycling step
Return type:

dict
Raises:
  • TypeError – Invalid input types, e.g. read is not of type bool
  • ValueError – Invalid format specified for temperature dict
  • ValueError – Duration is not greater than 0 second