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
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
- Raises
TypeError – if slope is not a number
- 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
- _destination_liquid¶
used to determine calibration, flowrates, and sensing thresholds
- Type
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
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
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
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
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
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
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
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