autoprotocol.builders¶

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

copyright

2021 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.InstructionBuilders[source]¶

General builders that apply to multiple instructions

shape(rows: int = 1, columns: int = 1, format: Optional[str] = None)[source]¶

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.ThermocycleBuilders[source]¶

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

dyes(**kwargs)[source]¶

Helper function for creating a dye parameter

Parameters

**kwargs (dict(str: int or list(int))) – A mapping from a dye (str) to the index of a well

Returns

A thermocycling dye to well mapping

Return type

dict

Raises

ValueError – If any of the specified dyes are not valid
ValueError – If wells is not an int, str, list(int), or list(str)

dyes_from_well_map(well_map: Dict[autoprotocol.container.Well, str])[source]¶

Helper function for creating a dye parameter from a well_map

Take a map of wells to the dyes it contains and returns a map of dyes to the list of wells that contain it.

Parameters: well_map (dict(well, str)) – A thermocycling well to dye mapping
Returns: A thermocycling dye to well mapping
Return type: dict

See also

Thermocycle.Builders.dyes: standard constructor for the dyes parameter

static melting(start: Optional[Union[str, autoprotocol.unit.Unit]] = None, end: Optional[Union[str, autoprotocol.unit.Unit]] = None, increment: Optional[Union[str, autoprotocol.unit.Unit]] = None, rate: Optional[Union[str, autoprotocol.unit.Unit]] = None)[source]¶

Helper function for creating melting parameters

Generates melt curve parameters for Thermocycle Instructions.

Parameters

start (str or Unit) – The starting temperature for the melt curve
end (str or Unit) – The ending temperature for the melt curve
increment (str or Unit) – The temperature increment of the melt curve
rate (str or Unit) – The duration the individual increments

Returns

A thermocycling melt curve specification

Return type

dict

Raises

ValueError – If some, but not all melt curve parameters are specified

group(steps: List[dict], cycles: int = 1)[source]¶

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

static step(temperature: Union[str, autoprotocol.unit.Unit], duration: Union[str, autoprotocol.unit.Unit], read: Optional[bool] = None)[source]¶

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

shape(rows: int = 1, columns: int = 1, format: Optional[str] = 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.SPEBuilders[source]¶

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

mobile_phase_params(volume: Union[str, autoprotocol.unit.Unit], loading_flowrate: Union[str, autoprotocol.unit.Unit], settle_time: Optional[bool], processing_time: Union[str, autoprotocol.unit.Unit], flow_pressure: Union[str, autoprotocol.unit.Unit], resource_id: Optional[str] = None, is_sample: bool = False, destination_well: Optional[autoprotocol.container.Well] = None, is_elute: bool = False)[source]¶

Create a dictionary with mobile phase parameters which can be used as input for instructions.

Parameters

volume (str or Unit) – the duration to shake the plate for
loading_flowrate (str or Unit, optional) – amplitude of shaking between 1 and 6:millimeter
settle_time (bool, optional) – True for orbital and False for linear shaking
processing_time (str or Unit) – Duration for which pressure is applied to the cartridge after settle_time has elapsed.
flow_pressure (str or Unit) – Pressure applied to the column.
resource_id (str) – Resource ID of desired solvent.
is_sample (bool) – If a sample is processed.
destination_well (Well) – Destination well for eluate. Required parameter for each elute mobile phase parameter
is_elute (bool) – If an elute is processed.

Returns

spe mobile_phase_params

Return type

dict

Raises

ValueError – if shake flow_pressure is not positive
ValueError – if mobile phase solvent and resource_id not included
TypeError – if resource_id is not a string
ValueError – if settle_time is not positive
ValueError – if processing_time is not positive

shape(rows: int = 1, columns: int = 1, format: Optional[str] = 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.DispenseBuilders[source]¶

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

static nozzle_position(position_x: Optional[Union[str, autoprotocol.unit.Unit]] = None, position_y: Optional[Union[str, autoprotocol.unit.Unit]] = None, position_z: Optional[Union[str, autoprotocol.unit.Unit]] = None)[source]¶

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

static column(column: int, volume: Union[str, autoprotocol.unit.Unit]) → autoprotocol.types.protocol.DispenseColumn[source]¶

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: List[Union[autoprotocol.types.protocol.DispenseColumn, dict]])[source]¶

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

shake_after(duration: Union[str, autoprotocol.unit.Unit], frequency: Optional[Union[str, autoprotocol.unit.Unit]] = None, path: Optional[str] = None, amplitude: Optional[Union[str, autoprotocol.unit.Unit]] = None)[source]¶

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: int = 1, columns: int = 1, format: Optional[str] = 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.SpectrophotometryBuilders[source]¶

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

static wavelength_selection(shortpass: Optional[Union[str, autoprotocol.unit.Unit]] = None, longpass: Optional[Union[str, autoprotocol.unit.Unit]] = None, ideal: Optional[Union[str, autoprotocol.unit.Unit]] = None)[source]¶

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

groups(groups)[source]¶

Parameters: groups (list(dict)) – A list of spectrophotometry groups.
Returns: A list of spectrophotometry groups.
Return type: list(dict)

group(mode, mode_params)[source]¶

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

absorbance_mode_params(wells: Union[List[autoprotocol.container.Well], autoprotocol.container.WellGroup], wavelength: Union[str, autoprotocol.unit.Unit], num_flashes: Optional[int] = None, settle_time: Optional[Union[str, autoprotocol.unit.Unit]] = None, read_position: Optional[autoprotocol.types.builders.SpectrophotometryBuildersReadPositions] = None, position_z: Optional[dict] = None)[source]¶

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.
read_position (Enum("top", "bottom"), optional) – The position of the probe relative to the plate for the read
position_z (dict, optional) – This should be specified with either position_z_manual or position_z_calculated

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: Union[List[autoprotocol.container.Well], autoprotocol.container.WellGroup], excitation: Union[str, autoprotocol.unit.Unit], emission: Union[str, autoprotocol.unit.Unit], num_flashes: Optional[int] = None, settle_time: Optional[Union[str, autoprotocol.unit.Unit]] = None, lag_time: Optional[Union[str, autoprotocol.unit.Unit]] = None, integration_time: Optional[Union[str, autoprotocol.unit.Unit]] = None, gain: Optional[Union[int, float]] = None, read_position: Optional[autoprotocol.types.builders.SpectrophotometryBuildersReadPositions] = None, position_z: Optional[dict] = None)[source]¶

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.
position_z (dict, optional) – This should be specified with either position_z_manual or position_z_calculated

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

luminescence_mode_params(wells: Union[List[autoprotocol.container.Well], autoprotocol.container.WellGroup], num_flashes: Optional[int] = None, settle_time: Optional[Union[str, autoprotocol.unit.Unit]] = None, integration_time: Optional[Union[str, autoprotocol.unit.Unit]] = None, gain: Optional[int] = None, read_position: Optional[autoprotocol.types.builders.SpectrophotometryBuildersReadPositions] = None, position_z: Optional[dict] = None)[source]¶

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.
read_position (Enum("top", "bottom"), optional) – The position of the probe relative to the plate for the read
position_z (dict, optional) – This should be specified with either position_z_manual or position_z_calculated

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_mode_params(duration: Optional[Union[str, autoprotocol.unit.Unit]] = None, frequency: Optional[Union[str, autoprotocol.unit.Unit]] = None, path: Optional[autoprotocol.types.builders.SpectrophotometryBuildersShakePaths] = None, amplitude: Optional[Union[str, autoprotocol.unit.Unit]] = None)[source]¶

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

shake_before(duration: Union[str, autoprotocol.unit.Unit], frequency: Optional[Union[str, autoprotocol.unit.Unit]] = None, path: Optional[autoprotocol.types.builders.SpectrophotometryBuildersShakePaths] = None, amplitude: Optional[Union[str, autoprotocol.unit.Unit]] = None)[source]¶

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

position_z_manual(reference: Optional[autoprotocol.types.builders.SpectrophotometryBuildersZReferences] = None, displacement: Optional[Union[str, autoprotocol.unit.Unit]] = None)[source]¶

Helper for building position_z parameters for a manual position_z configuration

Parameters

reference (str, optional) – Must be one of “plate_top”, “plate_bottom”, “well_top”, “well_bottom”
displacement (Unit or str, optional) – Displacement from reference position. Negative would refer to the well_top to well_bottom direction, while positive would refer to the opposite direction.

Returns

position_z parameters for a Spectrophotometry instruction

Return type

dict

Raises

ValueError – If reference was not in the allowed list
ValueError – If invalid displacement was provided

position_z_calculated(wells: List[autoprotocol.container.Well], heuristic: Optional[str] = None)[source]¶

Helper for building position_z parameters for a calculated position_z configuration

Parameters

wells (list(Well)) – List of wells to calculate the z-position from
heuristic (str, optional) – Must be one of “max_mean_read_without_saturation” or “closest_distance_without_saturation”. Please refer to ASC-041 for the full explanation

Returns

position_z parameters for a Spectrophotometry instruction

Return type

dict

Raises

ValueError – If a list of wells is not provided
ValueError – If an invalid heuristic is specified

shape(rows: int = 1, columns: int = 1, format: Optional[str] = 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[source]¶

Builders for LiquidHandle Instructions

location(location: Optional[Union[autoprotocol.container.Well, str]] = None, transports: Optional[List[dict]] = None)[source]¶

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

transport(volume: Optional[Union[str, autoprotocol.unit.Unit]] = None, pump_override_volume: Optional[Union[str, autoprotocol.unit.Unit]] = None, flowrate: Optional[dict] = None, delay_time: Optional[Union[str, autoprotocol.unit.Unit]] = None, mode_params: Optional[dict] = None, density: Optional[Union[str, autoprotocol.unit.Unit]] = None)[source]¶

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
density (Unit or str, optional) – Density of the liquid to be aspirated/dispensed in mg/ml.

Returns

transport parameters for a LiquidHandle instruction

Return type

dict

static flowrate(target: Union[str, autoprotocol.unit.Unit], initial: Optional[Union[str, autoprotocol.unit.Unit]] = None, cutoff: Optional[Union[str, autoprotocol.unit.Unit]] = None, acceleration: Optional[Union[str, autoprotocol.unit.Unit]] = None, deceleration: Optional[Union[str, autoprotocol.unit.Unit]] = None)[source]¶

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

mode_params(liquid_class: Optional[str] = None, position_x: Optional[dict] = None, position_y: Optional[dict] = None, position_z: Optional[dict] = None, tip_position: Optional[dict] = None, volume_resolution: Optional[Union[str, autoprotocol.unit.Unit]] = None)[source]¶

Helper for building transport mode_params

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

Parameters

liquid_class (str, 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.
volume_resolution (Unit, optional) – LiquidHandle dispense mode volume resolution specifies the droplet size to dispense. A specified resolution will exclude machines that are not configured for the given droplet size. By default, None means any droplet size will suffice. Check default droplet size on your machine configuration.

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 device_mode_params(device: str, model: Optional[str] = None, chip_material: Optional[str] = None, nozzle: Optional[str] = None, diaphragm: Optional[int] = None, nozzle_size: Optional[Union[str, autoprotocol.unit.Unit]] = None, tubing: Optional[str] = None, z_drop: Optional[Union[str, autoprotocol.unit.Unit]] = None, viscosity: Optional[str] = None)[source]¶

Helper for building device level mode_params

Mode params contain information about desired device hardware to be used

Parameters

device (str) – x_tempest_chip or x_mantis
model (Optional[str]) – Tempest chip or mantis model.
chip_material (Optional[str]) – Material that the tempest chip is made of.
nozzle (Optional[str]) – Type of chip nozzle for tempest.
diaphragm (Optional[Integer]) – any integer between 0 and 100, inclusive
nozzle_size (Optional[Unit[Length]] or Optional[str]) – one of “0.1:mm”, “0.2:mm”, “0.5:mm”
tubing (Optional[String]) – one of “LV”, “HV”, “P200”, “P1000” TODO: support that source is pipette-tip type
z_drop (Optional[Unit[Length]] or Optional[str]) – within the range: 0:mm - 100:mm, inclusive
viscosity (Optional[String]) – one of “1”, “2-5”, “6-10”, “11-20”, “21-25”

Returns

device_mode_params for a LiquidHandle instruction

Return type

dict

Raises

ValueError – If device is not of the following: [x_tempest_chip, x_mantis]

static validate_device_params(device: str, device_dict: dict) → None[source]¶

Helper validation function to validate device liquid handling params :param device: either x_mantis or x_tempest_chip :type device: str :param device_dict: Dictionary of all device params, as seen in function device_mode_params :type device_dict: dict

Raises

ValueError – If input device is not either x_mantis or x_tempest_chip
ValueError – If input device_dict values are not of the accepted params for the input device
KeyError – If input device_dict key is not in accepted_params keys

static move_rate(target: Optional[Union[str, autoprotocol.unit.Unit]] = None, acceleration: Optional[Union[str, autoprotocol.unit.Unit]] = None)[source]¶

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: Optional[Union[int, float]] = None, move_rate: Optional[dict] = None)[source]¶

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: Optional[str] = None, offset: Optional[Union[str, autoprotocol.unit.Unit]] = None, move_rate: Optional[dict] = None, detection_method: Optional[str] = None, detection_threshold: Optional[Union[str, autoprotocol.unit.Unit]] = None, detection_duration: Optional[Union[str, autoprotocol.unit.Unit]] = None, detection_fallback: Optional[dict] = None, detection: Optional[dict] = None)[source]¶

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

static instruction_mode_params(tip_type: Optional[str] = None)[source]¶

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

mix(volume: Union[str, autoprotocol.unit.Unit], repetitions: int, initial_z: dict, asp_flowrate: Optional[dict] = None, dsp_flowrate: Optional[dict] = None)[source]¶

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

blowout(volume: Union[str, autoprotocol.unit.Unit], initial_z: dict, flowrate: Optional[dict] = None)[source]¶

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

desired_mode(transports: Optional[dict] = None, mode: Optional[str] = None)[source]¶

Helper for selecting dispense mode based on liquid_class name For non-viscous, water-like liquid and air, the method will default to “air_displacement”. To allow for more accurate aspirate and dispense volumes, ‘viscous’ liquid where air pressure alone is sometimes not sufficient to overcome the surface tension to pull or push the liquid sufficiently through transfer tip, it will default to “positive_displacement” unless otherwise specified.

Examples

example_transports = [
    LiquidHandle.builders.transport(
        volume=Unit(1, "uL"),
        density=None,
        pump_override_volume=Unit(2, "uL"),
        flowrate=LiquidHandle.builders.flowrate(
            target=Unit(10, "uL/s")
        ),
        delay_time=Unit(0.5, "s"),
        mode_params=LiquidHandle.builders.mode_params(
            liquid_class="air",
            position_z=LiquidHandle.builders.position_z(
                reference="preceding_position"
            )
        )
    ),
    LiquidHandle.builders.transport(
        volume=Unit(1, "uL"),
        density=None,
        pump_override_volume=Unit(2, "uL"),
        flowrate=LiquidHandle.builders.flowrate(
            target=Unit(10, "uL/s")
        ),
        delay_time=Unit(0.5, "s"),
        mode_params=LiquidHandle.builders.mode_params(
            liquid_class="viscous",
            position_z=LiquidHandle.builders.position_z(
                reference="preceding_position"
            )
        )
    )
]

LiquidHandle.builders.desired_mode(example_transports, None)

This will return “positive_displacement” based on the “viscous” liquid class. Note that “air” (which defaults to “air_displacement”) does not cause a conflict since “air” is often applied in additional transfers of air (such as blowout) for any liquid class, and is disregarded.

Parameters

transports (dict, optional) – Dictionary of the transport parameters
mode (str, optional) – Mode of dispense type

Returns

Mode of dispense type

Return type

str

Raises

TypeError – mode is not in str
ValueError – mode does not contain valid mode value
TypeError – liquid is not of str
ValueError – liquid_class is not a valid value
ValueError – liquid_class did not resolve to a mode
ValueError – multiple liquid_class exists in one LiquidHandle

shape(rows: int = 1, columns: int = 1, format: Optional[str] = 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.PlateReaderBuilders[source]¶

Helpers for building parameters for plate reading instructions

incubate_params(duration: Union[str, autoprotocol.unit.Unit], shake_amplitude: Optional[Union[str, autoprotocol.unit.Unit]] = None, shake_orbital: Optional[bool] = None, shaking: Optional[dict] = None)[source]¶

Create a dictionary with incubation parameters which can be used as input for instructions. Currently supports plate reader instructions and could be extended for use with other instructions.

Parameters

duration (str or Unit) – the duration to shake the plate for
shake_amplitude (str or Unit, optional) – amplitude of shaking between 1 and 6:millimeter
shake_orbital (bool, optional) – True for orbital and False for linear shaking
shaking (dict, optional) – A dict of amplitude and orbital: should only be specified if none of the other tip shake parameters have been specified. Dictionary of incubate parameters

Returns

plate reader incubate_params

Return type

dict

Raises

ValueError – if shake duration is not positive
ValueError – if only one of shake_amplitude or shake_orbital is set
TypeError – if shake_orbital is not a bool
ValueError – if shake_amplitude is not positive

shape(rows: int = 1, columns: int = 1, format: Optional[str] = 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.EvaporateBuilders[source]¶

Helpers for building Evaporate instructions

get_mode_params(mode: Union[autoprotocol.types.builders.EvaporateBuildersValidModes, str], mode_params: Dict[str, Any])[source]¶

Checks on the validity of mode and mode_params, and creates a dictionary for mode_params

Parameters

mode (Str) – Mode of the evaporate method.
mode_params (Dict) – Method parameters for each mode.

Returns

Dictionary of mode_params

Return type

Dict

Raises

ValueError – If mode is not specified.
ValueError – If specified mode is not a valid mode.
ValueError – If mode_params contain key(s) that are not applicable for the specified mode.
TypeError – If there are multiple speed parameters.
ValueError – If container agitation speed is less than 0.
ValueError – If vacuum_pressure is less than 0 torr.

shape(rows: int = 1, columns: int = 1, format: Optional[str] = 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.GelPurifyBuilders[source]¶

Helpers for building GelPurify instructions

extract(source: autoprotocol.container.Well, band_list: List[autoprotocol.types.protocol.GelPurifyBand], lane: Optional[int] = None, gel: Optional[int] = None)[source]¶

Helper for building extract params for gel_purify

Parameters

source (Well) – The Well that contains the sample be purified
band_list (list(dict)) – A list of bands to be extracted from the source sample
lane (int, optional) – The gel lane for the source sample to be run on
gel (int, optional) – The number of the gel if using multiple gels

Returns

gel_purify extract parameters

Return type

dict

Raises

TypeError – If source is not a Well

band(elution_buffer: str, elution_volume: Union[str, autoprotocol.unit.Unit], destination: autoprotocol.container.Well, min_bp: Optional[int] = None, max_bp: Optional[int] = None, band_size_range: Optional[dict] = None)[source]¶

Helper for building band params for gel_purify

Parameters

elution_buffer (str) – The type of elution buffer to be used
elution_volume (str or Unit) – The volume of sample to be eluted
destination (Well) – The Well the extracted samples should be eluted into
min_bp (int, optional) – The minimum size sample to be removed.
max_bp (int, optional) – The maximum size sample to be removed.
band_size_range (dict, optional) – A dict of band size parameters. Should only be specified if none of the other band size parameters have been specified.

Returns

gel_purify band parameters

Return type

dict

Raises

TypeError – If destination is not a Well
TypeError – If min_bp is not an int
TypeError – If max_bp is not an int
ValueError – If min_bp is not less than max_bp

shape(rows: int = 1, columns: int = 1, format: Optional[str] = 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.MagneticTransferBuilders[source]¶

Helpers for building MagneticTransfer instruction parameters

static mag_dry(object: autoprotocol.container.Container, duration: Union[str, autoprotocol.unit.Unit])[source]¶

Helper for building mag_dry sub operations for MagneticTransfer

Parameters

object (Container) – The Container to be operated on
duration (str or Unit) – The duration of the operation

Returns

mag_dry parameters

Return type

dict

Raises

TypeError – If object is not a Container

See also

Protocol.mag_dry

static mag_incubate(object: autoprotocol.container.Container, duration: Union[str, autoprotocol.unit.Unit], magnetize: bool, tip_position: float, temperature: Optional[Union[str, autoprotocol.unit.Unit]] = None)[source]¶

Helper for building mag_incubate sub operations for MagneticTransfer

Parameters

object (Container) – The Container to be operated on
duration (str or Unit) – The duration of the operation
magnetize (bool) – Whether the magnetic head should be engaged during the operation
tip_position (float) – Position relative to well height that magnetic head is held
temperature (str or Unit, optional) – The temperature of the operation

Returns

mag_incubate parameters

Return type

dict

Raises

TypeError – If object is not a Container
TypeError – If magnetize is not a bool
ValueError – If tip_position is not a positive number

See also

Protocol.mag_incubate

static mag_collect(object: autoprotocol.container.Container, cycles: int, pause_duration: Union[str, autoprotocol.unit.Unit], bottom_position: Optional[float] = None, temperature: Optional[Union[str, autoprotocol.unit.Unit]] = None)[source]¶

Helper for building mag_collect sub operations for MagneticTransfer

Parameters

object (Container) – The Container to be operated on
cycles (int) – The number of times the operation should be repeated
pause_duration (str or Unit) – The delay time between each repetition of the operation
bottom_position (float, optional) – Position relative to well height where the magnetic head pauses
temperature (str or Unit, optional) – The temperature of the operation

Returns

mag_collect parameters

Return type

dict

Raises

TypeError – If object is not a Container
TypeError – If cycles is not an int
ValueError – If bottom_position is not a positive number

See also

Protocol.mag_collect

static mag_release(object: autoprotocol.container.Container, duration: Union[str, autoprotocol.unit.Unit], frequency: Union[str, autoprotocol.unit.Unit], center: Optional[float] = None, amplitude: Optional[float] = None, temperature: Optional[Union[str, autoprotocol.unit.Unit]] = None)[source]¶

Helper for building mag_release sub operations for MagneticTransfer

Parameters

object (Container) – The Container to be operated on
duration (str or Unit) – The duration of the operation
frequency (str or Unit) – The frequency of the magnetic head during the operation
center (float, optional) – Position relative to well height where oscillation is centered
amplitude (float, optional) – Distance relative to well height to oscillate around center
temperature (str or Unit, optional) – The temperature of the operation

Returns

mag_release parameters

Return type

dict

Raises

TypeError – If object is not a Container
ValueError – If center is less than 0
ValueError – If amplitude is greater than center

See also

Protocol.mag_release

static mag_mix(object: autoprotocol.container.Container, duration: Union[str, autoprotocol.unit.Unit], frequency: Union[str, autoprotocol.unit.Unit], center: Optional[float] = None, amplitude: Optional[float] = None, magnetize: Optional[bool] = None, temperature: Optional[Union[str, autoprotocol.unit.Unit]] = None)[source]¶

Helper for building mag_mix sub operations for MagneticTransfer

Parameters

object (Container) – The Container to be operated on
duration (str or Unit) – The duration of the operation
frequency (str or Unit, optional) – The frequency of the magnetic head during the operation
center (float, optional) – Position relative to well height where oscillation is centered
amplitude (float, optional) – Distance relative to well height to oscillate around center
magnetize (bool, optional) – Whether the magnetic head should be engaged during the operation
temperature (str or Unit, optional) – The temperature of the operation

Returns

mag_mix parameters

Return type

dict

Raises

TypeError – If object is not a Container
ValueError – If center is less than 0
ValueError – If amplitude is greater than center
TypeError – If magnetize is not a bool

See also

Protocol.mag_mix

shape(rows: int = 1, columns: int = 1, format: Optional[str] = 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.FlowCytometryBuilders[source]¶

Builders for FlowCytometry instructions.

laser(channels: List[autoprotocol.types.protocol.FlowCytometryChannel], excitation: Optional[Union[str, autoprotocol.unit.Unit]] = None, power: Optional[Union[str, autoprotocol.unit.Unit]] = None, area_scaling_factor: Optional[int] = None)[source]¶

Generates a dict of laser parameters.

Parameters

channels (list(dict)) – See FlowCytometryBuilders.channel().
excitation (Unit or str, optional) – Excitation wavelength.
power (Unit or str, optional) – Laser power.
area_scaling_factor (Number, optional) – Value to scale height and area equivalently.

Raises

TypeError – If channels is not a list of dict.
TypeError – If channels is not a list of dict.
TypeError – If area_scaling_factor is not a number.
ValueError – If a gating channel (e.g. SSC) is specified and excitation is also specified.

Returns

A dict of laser parameters.

Return type

dict

channel(emission_filter: autoprotocol.types.protocol.FlowCytometryChannelEmissionFilter, detector_gain: Union[str, autoprotocol.unit.Unit], measurements: Optional[autoprotocol.types.protocol.FlowCytometryChannelMeasurements] = None, trigger_threshold: Optional[int] = None, trigger_logic: Optional[autoprotocol.types.protocol.FlowCytometryChannelTriggerLogic] = None)[source]¶

Generates a dict of channel parameters.

Parameters

emission_filter (dict) – See FlowCytometryBuilders.emission_filter().
detector_gain (Unit or str) – Detector gain.
measurements (dict, optional) – Pulse properties to record. See FlowCytometryBuilders.measurements().
trigger_threshold (int, optional) – Channel intensity threshold. Events below this threshold.
trigger_logic (Enum({"and", "or"}), optional) – Operator used to combine threshold.

Raises

TypeError – If trigger_threshold is not of type int.
ValueError – If trigger_logic is not one of {“and”, “or”}.

Returns

A dict of channel parameters.

Return type

dict

emission_filter(channel_name: str, shortpass: Optional[Union[str, autoprotocol.unit.Unit]] = None, longpass: Optional[Union[str, autoprotocol.unit.Unit]] = None)[source]¶

Generates a dict of emission filter parameters.

Parameters

channel_name (str) – Specifies the channel name.
shortpass (Unit or str) – Shortpass filter wavelength.
longpass (Unit or str) – Longpass filter wavelength.

Raises

ValueError – If values for longpass or shortpass are provided and channel_name is “FSC” or “SSC”.

Returns

A dict of emission_filter params.

Return type

dict

static measurements(area: Optional[bool] = None, height: Optional[bool] = None, width: Optional[bool] = None)[source]¶

Generates a dict of measurements parameters.

Parameters

area (bool, optional) – Area measurement.
height (bool, optional) – Height measurement.
width (bool, optional) – Width measurement.

Raises

TypeError – If any of area | height | width are not of type bool.

Returns

A dict of measurements params.

Return type

dict

collection_conditions(acquisition_volume: Union[str, autoprotocol.unit.Unit], flowrate: Union[str, autoprotocol.unit.Unit], wait_time: Union[str, autoprotocol.unit.Unit], mix_cycles: int, mix_volume: Union[str, autoprotocol.unit.Unit], rinse_cycles: int, stop_criteria: Optional[autoprotocol.types.protocol.FlowCytometryCollectionConditionStopCriteria] = None)[source]¶

Generates a dict of collection_conditions parameters.

Parameters

acquisition_volume (Unit or str) – Acquisition volume.
flowrate (Unit or str) – Flow rate.
wait_time (Unit or str) – Waiting time.
mix_cycles (int) – Number of mixing cycles before acquisition.
mix_volume (Unit or str) – Mixing volume.
rinse_cycles (int) – Number of rinsing cycles.
stop_criteria (dict, optional) – See FlowCytometryBuilders.stop_criteria().

Raises

TypeError – If rinse_cycles is not of type int.
TypeError – If mix_cycles is not of type int.

Returns

A dict of collection_condition parameters.

Return type

dict

static stop_criteria(volume: Optional[Union[str, autoprotocol.unit.Unit]] = None, events: Optional[int] = None, time: Optional[Union[str, autoprotocol.unit.Unit]] = None)[source]¶

Generates a dict of stop_criteria parameters.

Parameters

volume (Unit or str, optional) – Stopping volume.
events (int, optional) – Number of events to trigger stop.
time (Unit or str, optional) – Stopping time.

Raises

TypeError – If events is not of type int.

Returns

A dict of stop_criteria params.

Return type

dict

shape(rows: int = 1, columns: int = 1, format: Optional[str] = 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