autoprotocol.liquid_handle

liquid_handle.liquid_handle_method

LiquidHandleMethod

Base class for generating complex liquid handling behavior.

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=None, blowout=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
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
static default_lld_position_z(liquid)[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.

class autoprotocol.liquid_handle.liquid_class.LiquidClass(calibrated_volume=None, aspirate_flowrate=None, dispense_flowrate=None, delay_time=None, clld_threshold=None, plld_threshold=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
class autoprotocol.liquid_handle.liquid_class.VolumeCalibrationBin[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()

Return number of occurrences of value.

index()

Return first index of value.

Raises ValueError if the value is not present.

intercept

Alias for field number 1

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

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

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

LiquidHandleMethod for generating transfers between pairs of wells

LiquidHandleMethod for transferring volume from one well to another.

_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)[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)[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)[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)[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)[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)[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)

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)

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)

Default lld position_z

Returns:position_z for sensing the liquid surface
Return type:dict
default_mix_after(volume)

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)

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)

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)

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

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)

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)

Default lld position_z

Returns:position_z for sensing the liquid surface
Return type:dict
default_mix_after(volume)

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)

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)

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)

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.

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

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