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(model: Optional[str] = None, chip_material: Optional[str] = None, nozzle: Optional[str] = None)[source]

Helper for building device level mode_params

Mode params contain information about desired device hardware to be used

Parameters

  • model (string, optional) – Tempest chip model.

  • chip_material (string, optional) – Material that the tempest chip is made of.

  • nozzle (string, optional) – Type of chip nozzle.

Returns

device_mode_params for a LiquidHandle instruction

Return type

dict

Raises

  • ValueError – If model is not None or “high_volume”

  • ValueError – If nozzle is not None or “standard”

  • ValueError – If chip_material is not None or in the allowable list of tempest chip materials

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