autoprotocol.liquid_handle

liquid_handle.liquid_handle_method

LiquidHandleMethod

Base class for generating complex liquid handling behavior.

copyright

2021 by The Autoprotocol Development Team, see AUTHORS for more details.

license

BSD, see LICENSE for more details

Summary

LiquidHandleMethods are passed as arguments to Protocol methods along with LiquidClasses to specify complex series of liquid handling behaviors.

Notes

Methods in this file should not be used directly, but are intended to be extended by other methods depending on desired behavior.

When creating a vendor-specific library it’s likely desirable to monkey patch LiquidHandleMethod._get_tip_types to reference TipTypes that the vendor supports.

class autoprotocol.liquid_handle.liquid_handle_method.LiquidHandleMethod(tip_type: Optional[autoprotocol.liquid_handle.tip_type.TipType] = None, blowout: bool = True)[source]

Base LiquidHandleMethod

General framework for liquid handling abstractions and helpers for building a series of liquid_handle transports.

_shape

the SBS shape and number of rows and columns of the liquid_handle

Type

dict

_transports

tracks transports to be added to the LiquidHandle instruction

Type

list

Notes

There is a hierarchy of logic to all LiquidHandleMethods that abstracts a complex set of liquid handling behavior into smaller, discrete steps.

For step x (aspirate, dispense, mix) and parameter y (e.g. blowout):
  • Protocol method:
    • calls LiquidHandleMethod._`x`_transports

  • LiquidHandleMethod._`x`_transports method:
    • clears the _transports list

    • walks through all _transport methods including _transport_`y`

    • returns the _transports lists

  • LiquidHandleMethod._transport_`y` method:
    • checks parameter y in addition to the default_`y` method

    • possibly generates a series of transports based on the two values

    • calls lower level helper methods

  • LiquidHandleMethod lower level helper methods:
    • generate transports and append them to _transports

Examples

For specifying a single, global liquid handling behavior across all volumes the easiest way is to specify parameters when instantiating a LiquidHandleMethod.

from autoprotocol import Unit
from autoprotocol.instruction import LiquidHandle
from autoprotocol.liquid_handle import LiquidHandleMethod

lhm = LiquidHandleMethod(
    blowout=LiquidHandle.builders.blowout(volume=Unit(10, "uL"))
)

For behavior that relies on more liquid handling parameters or even defines new behavior you can define your own LiquidHandleMethod.

from autoprotocol import Unit
from autoprotocol.instruction import LiquidHandle
from autoprotocol.liquid_handle import LiquidHandleMethod

class NewLHM(LiquidHandleMethod):
    def default_blowout(self, volume):
        if volume < Unit(10, "uL"):
            blowout_volume = Unit(1, "uL")
        else:
            blowout_volume = Unit(10, "uL")
        return LiquidHandle.builders.blowout(
            volume=blowout_volume
        )

See also

Transfer

method for handling liquid between two locations

Mix

method for handling liquid within locations

LiquidClass

contain properties that are intrinsic to specific liquids

Protocol

contains methods that accept LiquidHandleMethods as arguments

blowout: bool = True
Parameters
  • tip_type (str, optional) – tip_type to be used for the LiquidHandlingMethod

  • blowout (bool or dict, optional) – whether to execute a blowout step or the parameters for one. this generates two operations, an initial air aspiration before entering any wells, and a corresponding final air dispense after the last operation that involves liquid See Also LiquidHandle.builders.blowout

default_blowout(volume: autoprotocol.unit.Unit)[source]

Default blowout behavior

Parameters

volume (Unit) –

Returns

blowout_params

Return type

dict

See also

blowout

holds any user specified blowout parameters

_transport_blowout

generates the actual blowout transports

static default_lld_position_z(liquid: LiquidClass)[source]

Default lld position_z

Returns

position_z for sensing the liquid surface

Return type

dict

static default_tracked_position_z()[source]

Default tracked position_z

Returns

position_z for tracking the liquid surface

Return type

dict

static default_well_bottom_position_z()[source]

Default well bottom position_z

Returns

position_z for the well bottom

Return type

dict

static default_well_top_position_z()[source]

Default well top position_z

Returns

position_z for the well top

Return type

dict

liquid_handle.liquid_class

LiquidClass

Base class for defining the portions of liquid handling behavior that are intrinsic to specific types of liquids.

copyright

2021 by The Autoprotocol Development Team, see AUTHORS for more details.

license

BSD, see LICENSE for more details

class autoprotocol.liquid_handle.liquid_class.LiquidClass(calibrated_volume: Optional[Unit] = None, aspirate_flowrate: Optional[dict] = None, dispense_flowrate: Optional[dict] = None, delay_time: Optional[Unit] = None, clld_threshold: Optional[Unit] = None, plld_threshold: Optional[Unit] = None)[source]

Contains properties intrinsic to individual LiquidClasses

name

the name of the liquid_class may be used by vendors to generate more sensible defaults for unspecified behavior

Type

str

volume_calibration_curve

a calibration curve describing the relationship between tip_type, volume bins, and volume calibration parameters See Also VolumeCalibration

Type

dict(str, VolumeCalibration)

aspirate_flowrate_calibration_curve

a calibration curve describing the relationship between tip_type, volume bins, and aspirate flowrate calibration parameters See Also VolumeCalibration

Type

dict(str, VolumeCalibration)

dispense_flowrate_calibration_curve

a calibration curve describing the relationship between tip_type, volume bins, and dispense flowrate calibration parameters See Also VolumeCalibration

Type

dict(str, VolumeCalibration)

_safe_volume_multiplier

a multiplier used by LiquidHandleMethods to estimate safe pump buffers for volume calibration without any prior knowledge about tip_type See Also LiquidHandleMethod._estimate_calibrated_volume

Type

Numeric

Examples

For specifying a single, global liquid handling behavior across all volumes the easiest way is to specify parameters when instantiating a LiquidClass. If the following LiquidClass is specified then the pump_override_volume will always be set to 10:uL and the flowrate for all aspirate steps will have a target of 10:uL/s, regardless of the stated volume to be transferred.

from autoprotocol import Unit
from autoprotocol.instruction import LiquidHandle
from autoprotocol.liquid_handle import LiquidClass

lc = LiquidClass(
    aspirate_flowrate=LiquidHandle.builders.flowrate(
        target=Unit(10, "ul/s")
    ),
    calibrated_volume=Unit(10, "uL")
)

For behavior that differs between volumes you can define your own LiquidClass.

from autoprotocol import Unit
from autoprotocol.instruction import LiquidHandle
from autoprotocol.liquid_handle.liquid_class import (
    LiquidClass, VolumeCalibration, VolumeCalibrationBin
)

vol_curve = {
    "generic_1_50": VolumeCalibration(
        (Unit(5, "uL"), VolumeCalibrationBin(
            slope=1.1, intercept=Unit(0.1, "uL")
        )),
        (Unit(10, "uL"), VolumeCalibrationBin(
            slope=0.9, intercept=Unit(0.2, "uL")
        ))
    )
}
asp_flow_curve = {
    "generic_1_50": VolumeCalibration(
        (Unit(5, "uL"), LiquidHandle.builders.flowrate(
            target=Unit(50, "uL/s")
        )),
        (Unit(15, "uL"), LiquidHandle.builders.flowrate(
            target=Unit(200, "uL/s")
        ))
    )
}

class NewLC(LiquidClass):
    def __init__(self, *args, **kwargs):
        super(NewLC, self).__init__(*args, **kwargs)
        self.volume_calibration_curve = vol_curve
        self.aspirate_flowrate_calibration_curve = asp_flow_curve

See also

VolumeCalibration

used to specify calibration_curves

LiquidHandleMethod

used to specify liquid handling movement behavior

Protocol.transfer

accepts LiquidClass arguments to determine behavior

Protocol.mix

accepts a LiquidClass argument to determine behavior

plld_threshold: Optional[Unit] = None
Parameters
  • calibrated_volume (Unit, optional) – used to specify a calibrated volume, if not specified then will default to the calibration from volume_calibration_curve

  • aspirate_flowrate (dict, optional) – used to specify an aspirate flowrate, if not specified then will default to the calibration using aspirate_flowrate_calibration_curve

  • dispense_flowrate (dict, optional) – used to specify a dispense flowrate, if not specified then will default to the calibration using dispense_flowrate_calibration_curve

  • delay_time (Unit, optional) – the amount of time to wait after each liquid handling step. this is helpful for cases such as pressure equilibration

  • clld_threshold (Unit, optional) – the capacitive liquid level detection threshold

  • plld_threshold (Unit, optional) – the pressure liquid level detection threshold

class autoprotocol.liquid_handle.liquid_class.VolumeCalibrationBin(slope, intercept)[source]

Wrapper for slope and intercept parameters for linear fitting Holds information required to calibrate a volume for liquid handle step assuming a linear relationship between volume and calibrated volume.

static __new__(cls, slope, intercept)[source]
Parameters
  • slope (Number) – The slope of the linear fit volume calibration function.

  • intercept (Unit) – The intercept of the linear fit volume calibration function.

Returns

an object used for linear fitting volumes within a bin

Return type

VolumeCalibrationBin

Raises

TypeError – if slope is not a number

calibrate_volume(volume)[source]

Calibrates the volume using slope and intercept

Parameters

volume (Unit) – the volume to be calibrated

Returns

calibrated volume

Return type

Unit

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

property intercept

Alias for field number 1

property slope

Alias for field number 0

class autoprotocol.liquid_handle.liquid_class.VolumeCalibration(*args)[source]

Wrapper for a volume-binned calibration curve A data structure that represents a calibration curve for either volumes or flowrates that are binned by upper bounded volume ranges.

binned_calibration_for_volume(volume)[source]

Gets the smallest suitable bin in the calibration curve Finds the smallest point on the calibration curve that has a bin that’s greater than or equal to the size of the specified value.

Parameters

volume (Unit or int or float) – the value to be binned

Returns

target_bin

Return type

dict

Raises

RuntimeError – No suitably large calibration bin

liquid_handle.transfer

Transfer LiquidHandleMethod

copyright

2021 by The Autoprotocol Development Team, see AUTHORS for more details.

license

BSD, see LICENSE for more details

Base LiquidHandleMethod used by Protocol.transfer to generate a series of movements between pairs of wells.

class autoprotocol.liquid_handle.transfer.Transfer(tip_type: Optional[str] = None, blowout: Optional[Union[bool, dict]] = True, prime: Optional[Union[bool, autoprotocol.unit.Unit]] = True, transit: Optional[Union[bool, autoprotocol.unit.Unit]] = True, mix_before: Optional[Union[bool, dict]] = False, mix_after: Optional[Union[bool, dict]] = True, aspirate_z: Optional[dict] = None, dispense_z: Optional[dict] = None)[source]

LiquidHandleMethod for generating transfers between pairs of wells

LiquidHandleMethod for transferring volume from one well to another.

Parameters
  • tip_type (str, optional) – tip_type to be used for the LiquidHandlingMethod

  • blowout (bool or dict, optional) – whether to execute a blowout step or the parameters for one. this generates a pair of operations: an initial air aspiration before entering any wells and a corresponding air dispense after the last operation that involves liquid See Also LiquidHandle.builders.blowout

  • prime (bool or Unit, optional) – whether to execute a prime step or the parameters for one. this generates a pair of aspirate/dispense operations around the aspiration step in the sequence: aspirate_prime -> aspirate_target_volume -> dispense_prime

  • transit (bool or Unit, optional) – whether to execute a transit step or the parameters for one. this generates a pair of operations wherein air is aspirated just before leaving the source location and dispensed immediately after reaching the destination location

  • mix_before (bool or dict, optional) – whether to execute a mix_before step or the parameters for one. this generates a series of aspirate and dispense steps within the source location before aspirating the target volume See Also LiquidHandle.builders.mix

  • mix_after (bool or dict, optional) – whether to execute a mix_after step or the parameters for one. this generates a series of aspirate and dispense steps within the destination location after dispensing the target volume See Also LiquidHandle.builders.mix

  • aspirate_z (dict, optional) – the position that the tip should move to prior to aspirating, if the position references the liquid_surface then aspirate movements will track the surface with the defined offset. See Also LiquidHandle.builders.position_z

  • dispense_z (dict, optional) – the position that the tip should move to prior to dispensing, if the position references the liquid_surface then dispense will track the surface with the defined offset. See Also LiquidHandle.builders.position_z

_source_liquid

used to determine calibration, flowrates, and sensing thresholds

Type

LiquidClass

_destination_liquid

used to determine calibration, flowrates, and sensing thresholds

Type

LiquidClass

Notes

The primary entry points that for this class are:
  • _aspirate_transports : generates transports for a source location

  • _dispense_transports : generates transports for a destination location

See also

LiquidHandleMethod

base LiquidHandleMethod with reused functionality

Protocol.transfer

the standard interface for interacting with Transfer

default_blowout(volume)[source]

Default blowout behavior

Parameters

volume (Unit) –

Returns

blowout_params

Return type

dict

See also

blowout

holds any user specified blowout parameters

_transport_blowout

generates the actual blowout transports

default_mix_before(volume: autoprotocol.unit.Unit)[source]

Default mix_before parameters

Parameters

volume (Unit) –

Returns

mix_before params

Return type

dict

See also

mix_before

holds any user defined mix_before parameters

_transport_mix

generates the actual mix_before transports

default_aspirate_z(volume: autoprotocol.unit.Unit)[source]

Default aspirate_z parameters

Parameters

volume (Unit) –

Returns

aspirate position_z

Return type

dict

See also

aspirate_z

holds any user defined aspirate_z parameters

_transport_aspirate_target_volume

generates actual aspirate transports

default_prime(volume: autoprotocol.unit.Unit)[source]

Default prime volume

Parameters

volume (Unit) –

Returns

priming volume

Return type

Unit

See also

prime

holds any user defined prime volume

_transport_aspirate_target_volume

generates actual aspirate transports

default_transit(volume: autoprotocol.unit.Unit)[source]

Default transit volume

Parameters

volume (Unit) –

Returns

transit volume

Return type

Unit

See also

transit

holds any user defined transit volume

_transport_aspirate_transit

generates the actual transit transports

_transport_dispense_transit

generates the actual transit transports

default_dispense_z(volume: autoprotocol.unit.Unit)[source]

Default aspirate_z parameters

Parameters

volume (Unit) –

Returns

dispense position_z

Return type

dict

See also

dispense_z

holds any user defined dispense_z parameters

_transport_dispense_target_volume

generates actual dispense transports

default_mix_after(volume: autoprotocol.unit.Unit)[source]

Default mix_after parameters

Parameters

volume (Unit) –

Returns

mix_after params

Return type

dict

See also

mix_after

holds any user defined mix_after parameters

_transport_mix

generates the actual mix_after transports

static default_lld_position_z(liquid: LiquidClass)

Default lld position_z

Returns

position_z for sensing the liquid surface

Return type

dict

static default_tracked_position_z()

Default tracked position_z

Returns

position_z for tracking the liquid surface

Return type

dict

static default_well_bottom_position_z()

Default well bottom position_z

Returns

position_z for the well bottom

Return type

dict

static default_well_top_position_z()

Default well top position_z

Returns

position_z for the well top

Return type

dict

class autoprotocol.liquid_handle.transfer.DryWellTransfer(tip_type=None, blowout=True, prime=True, transit=True, mix_before=False, mix_after=False, aspirate_z=None, dispense_z=None)[source]

Dispenses while tracking liquid without mix_after

default_dispense_z(volume)[source]

Default aspirate_z parameters

Parameters

volume (Unit) –

Returns

dispense position_z

Return type

dict

See also

dispense_z

holds any user defined dispense_z parameters

_transport_dispense_target_volume

generates actual dispense transports

default_aspirate_z(volume: autoprotocol.unit.Unit)

Default aspirate_z parameters

Parameters

volume (Unit) –

Returns

aspirate position_z

Return type

dict

See also

aspirate_z

holds any user defined aspirate_z parameters

_transport_aspirate_target_volume

generates actual aspirate transports

default_blowout(volume)

Default blowout behavior

Parameters

volume (Unit) –

Returns

blowout_params

Return type

dict

See also

blowout

holds any user specified blowout parameters

_transport_blowout

generates the actual blowout transports

static default_lld_position_z(liquid: LiquidClass)

Default lld position_z

Returns

position_z for sensing the liquid surface

Return type

dict

default_mix_after(volume: autoprotocol.unit.Unit)

Default mix_after parameters

Parameters

volume (Unit) –

Returns

mix_after params

Return type

dict

See also

mix_after

holds any user defined mix_after parameters

_transport_mix

generates the actual mix_after transports

default_mix_before(volume: autoprotocol.unit.Unit)

Default mix_before parameters

Parameters

volume (Unit) –

Returns

mix_before params

Return type

dict

See also

mix_before

holds any user defined mix_before parameters

_transport_mix

generates the actual mix_before transports

default_prime(volume: autoprotocol.unit.Unit)

Default prime volume

Parameters

volume (Unit) –

Returns

priming volume

Return type

Unit

See also

prime

holds any user defined prime volume

_transport_aspirate_target_volume

generates actual aspirate transports

static default_tracked_position_z()

Default tracked position_z

Returns

position_z for tracking the liquid surface

Return type

dict

default_transit(volume: autoprotocol.unit.Unit)

Default transit volume

Parameters

volume (Unit) –

Returns

transit volume

Return type

Unit

See also

transit

holds any user defined transit volume

_transport_aspirate_transit

generates the actual transit transports

_transport_dispense_transit

generates the actual transit transports

static default_well_bottom_position_z()

Default well bottom position_z

Returns

position_z for the well bottom

Return type

dict

static default_well_top_position_z()

Default well top position_z

Returns

position_z for the well top

Return type

dict

class autoprotocol.liquid_handle.transfer.PreMixBlowoutTransfer(tip_type=None, blowout=True, prime=True, transit=True, mix_before=False, mix_after=True, aspirate_z=None, dispense_z=None, pre_mix_blowout=True)[source]

Adds an additional blowout before the mix_after step

default_pre_mix_blowout(volume: autoprotocol.unit.Unit)[source]

Default pre_mix_blowout parameters

Parameters

volume (Unit) –

Returns

pre_mix_blowout params

Return type

dict

See also

pre_mix_blowout

holds any user defined pre_mix_blowout parameters

_transport_pre_mix_blowout

generates the actual blowout transports

default_aspirate_z(volume: autoprotocol.unit.Unit)

Default aspirate_z parameters

Parameters

volume (Unit) –

Returns

aspirate position_z

Return type

dict

See also

aspirate_z

holds any user defined aspirate_z parameters

_transport_aspirate_target_volume

generates actual aspirate transports

default_blowout(volume)

Default blowout behavior

Parameters

volume (Unit) –

Returns

blowout_params

Return type

dict

See also

blowout

holds any user specified blowout parameters

_transport_blowout

generates the actual blowout transports

default_dispense_z(volume: autoprotocol.unit.Unit)

Default aspirate_z parameters

Parameters

volume (Unit) –

Returns

dispense position_z

Return type

dict

See also

dispense_z

holds any user defined dispense_z parameters

_transport_dispense_target_volume

generates actual dispense transports

static default_lld_position_z(liquid: LiquidClass)

Default lld position_z

Returns

position_z for sensing the liquid surface

Return type

dict

default_mix_after(volume: autoprotocol.unit.Unit)

Default mix_after parameters

Parameters

volume (Unit) –

Returns

mix_after params

Return type

dict

See also

mix_after

holds any user defined mix_after parameters

_transport_mix

generates the actual mix_after transports

default_mix_before(volume: autoprotocol.unit.Unit)

Default mix_before parameters

Parameters

volume (Unit) –

Returns

mix_before params

Return type

dict

See also

mix_before

holds any user defined mix_before parameters

_transport_mix

generates the actual mix_before transports

default_prime(volume: autoprotocol.unit.Unit)

Default prime volume

Parameters

volume (Unit) –

Returns

priming volume

Return type

Unit

See also

prime

holds any user defined prime volume

_transport_aspirate_target_volume

generates actual aspirate transports

static default_tracked_position_z()

Default tracked position_z

Returns

position_z for tracking the liquid surface

Return type

dict

default_transit(volume: autoprotocol.unit.Unit)

Default transit volume

Parameters

volume (Unit) –

Returns

transit volume

Return type

Unit

See also

transit

holds any user defined transit volume

_transport_aspirate_transit

generates the actual transit transports

_transport_dispense_transit

generates the actual transit transports

static default_well_bottom_position_z()

Default well bottom position_z

Returns

position_z for the well bottom

Return type

dict

static default_well_top_position_z()

Default well top position_z

Returns

position_z for the well top

Return type

dict

liquid_handle.mix

Mix LiquidHandleMethod

Base LiquidHandleMethod used by Protocol.mix to generate a series of movements within individual wells.

copyright

2021 by The Autoprotocol Development Team, see AUTHORS for more details.

license

BSD, see LICENSE for more details

class autoprotocol.liquid_handle.mix.Mix(tip_type=None, blowout=True, repetitions=None, position_z=None)[source]

LiquidHandleMethod for generating transfers within wells

LiquidHandleMethod for moving volume within a single well.

_liquid

used to determine calibration, flowrates, and sensing thresholds

Type

LiquidClass

Notes

The primary entry points that for this class are:
  • _mix_transports : generates transports within a single location

See also

LiquidHandleMethod

base LiquidHandleMethod with reused functionality

Protocol.mix

the standard interface for interacting with Mix

default_blowout(volume)[source]

Default blowout behavior

Parameters

volume (Unit) –

Returns

blowout_params

Return type

dict

See also

blowout

holds any user specified blowout parameters

_transport_blowout

generates the actual blowout transports

default_repetitions(volume: autoprotocol.unit.Unit)[source]

Default mix repetitions

Parameters

volume (Unit) –

Returns

number of mix repetitions

Return type

int

See also

repetitions

holds any user defined repetition parameters

_transport_mix

generates the actual mix transports

default_position_z(volume: autoprotocol.unit.Unit)[source]

Default position_z

Parameters

volume (Unit) –

Returns

mix position_z

Return type

dict

See also

position_z

holds any user defined position_z parameters

_transport_mix

generates the actual mix transports

static default_lld_position_z(liquid: LiquidClass)

Default lld position_z

Returns

position_z for sensing the liquid surface

Return type

dict

static default_tracked_position_z()

Default tracked position_z

Returns

position_z for tracking the liquid surface

Return type

dict

static default_well_bottom_position_z()

Default well bottom position_z

Returns

position_z for the well bottom

Return type

dict

static default_well_top_position_z()

Default well top position_z

Returns

position_z for the well top

Return type

dict

liquid_handle.tip_type

Generic tip type and device class mappings for LiquidHandleMethods

copyright

2021 by The Autoprotocol Development Team, see AUTHORS for more details.

license

BSD, see LICENSE for more details