robotools.liquidhandling

Functions for tracking fluid composition through liquid handling operations.

robotools.liquidhandling.composition.combine_composition(volume_A: float, composition_A: Mapping[str, float] | None, volume_B: float, composition_B: Mapping[str, float] | None) → Dict[str, float] | None

Computes the composition of a liquid, created by the mixing of two liquids (A and B).

Parameters:

volume_Afloat

Volume of liquid A

composition_Adict

Relative composition of liquid A

volume_Bfloat

Volume of liquid B

composition_Bdict

Relative composition of liquid B

Returns:

compositiondict

Composition of the new liquid created by mixing the given volumes of A and B

robotools.liquidhandling.composition.get_initial_composition(name: str, real_wells: ndarray, component_names: Mapping[str, str | None], initial_volumes: ndarray) → Dict[str, ndarray]

Creates a dictionary of initial composition arrays.

Parameters:

namestr

Name of the labware - used for default component names.

real_wellsarray-like

2D array of non-virtual wells in the labware.

component_namesdict

User-provided dictionary that maps real well IDs to component names.

initial_volumesnp.ndarray

Initial volumes of real wells.

Returns:

compositiondict

The component-wise dictionary of numpy arrays that describe the composition of real wells.

robotools.liquidhandling.composition.get_trough_component_names(name: str, columns: int, column_names: Sequence[str | None], initial_volumes: Sequence[int | float]) → Dict[str, str | None]

Determines a fully-specified component name dictionary for a trough.

This helper function exists to provide a different default naming pattern for troughs. Instead of “stocks.A01” this function defaults to “stocks.column_01” with 1-based column numbering.

Parameters:

namestr

Name of the trough - used for default component names.

columnsint

Number of trough columns.

column_namesarray-like

Column-wise component names. Must be given for all columns, but can contain None elements.

initial_volumesarray-like

Column-wise initial volumes. Used to determine if a default component name is needed.

Returns:

component_namesdict

The component name dictionary that maps all row A well IDs to component names.

Exceptions that indicate problems in liquid handling.

exception robotools.liquidhandling.exceptions.VolumeOverflowError(labware: str, well: str, current: float, change: float, threshold: float, label: str | None = None)

Bases: VolumeViolationException

Error that indicates the planned overflow of a well.

exception robotools.liquidhandling.exceptions.VolumeUnderflowError(labware: str, well: str, current: float, change: float, threshold: float, label: str | None = None)

Bases: VolumeViolationException

Error that indicates the planned underflow of a well.

exception robotools.liquidhandling.exceptions.VolumeUnderflowWarning

Bases: VolumeViolationWarning

Warning indicating the possible underflow of a well.

exception robotools.liquidhandling.exceptions.VolumeViolationException

Bases: Exception

Error indicating a violation of volume constraints.

exception robotools.liquidhandling.exceptions.VolumeViolationWarning

Bases: UserWarning

Warning indicating the possible violation of volume constratins.

Object-oriented, stateful labware representations.

class robotools.liquidhandling.labware.Labware(name: str, rows: int, columns: int, *, min_volume: float, max_volume: float, initial_volumes: float | ndarray | None = None, virtual_rows: int | None = None, component_names: Mapping[str, str | None] | None = None)

Bases: object

Represents an array of liquid cavities.

Attributes:

composition

Relative composition of the liquids.

history

List of label/volumes history.

indices

Mapping of well-ids to numpy indices.

is_trough

n_columns

n_rows

report

A printable report of the labware history.

shape

Number of rows and columns.

volumes

Current volumes in the labware.

wells

Array of well ids.

Methods

add(wells, volumes[, label, compositions])	Adds volumes to wells.
condense_log(n[, label])	Condense the last n log entries.
from_dict(data[, cls_trough])	Creates a labware from a dict produced by Labware.to_dict().
get_well_composition(well)	Retrieves the relative composition of a well.
log(label)	Logs the current volumes to the history.
remove(wells, volumes[, label, on_underflow])	Removes volumes from wells.
to_dict()	Serialize to a dict of only atomic data types.

add(wells: str | Sequence[str] | ndarray, volumes: float | Sequence[float] | ndarray, label: str | None = None, compositions: Sequence[Mapping[str, float] | None] | None = None) → None

Adds volumes to wells.

Parameters:

wellsiterable of str

Well ids

volumesfloat, iterable of float

Scalar or iterable of volumes

labelstr

Description of the operation

compositionsiterable

List of composition dictionaries ({ name : relative amount })

property composition: Dict[str, ndarray]

Relative composition of the liquids.

This dictionary maps liquid names (keys) to arrays of relative amounts in each well.

condense_log(n: int, label: str | None = 'last') → None

Condense the last n log entries.

Parameters:

nint

Number of log entries to condense

labelstr

‘first’, ‘last’ or label of the condensed entry (default: label of the last entry in the condensate)

classmethod from_dict(data: Mapping[str, Any], cls_trough: type | None = None) → Labware | Trough

Creates a labware from a dict produced by Labware.to_dict().

Parameters:

data

Dict created by Labware.to_dict().

cls_trough

Optional trough type to use in case the data dict corresponds to a trough labware. Defaults to Trough with a warning if the main class is not a Trough itself.

get_well_composition(well: str) → Dict[str, float]

Retrieves the relative composition of a well.

Parameters:

wellstr

ID of the well for which to retrieve the composition.

Returns:

compositiondict

Keys: liquid names Values: relative amount

property history: List[Tuple[str | None, ndarray]]

List of label/volumes history.

property indices: Dict[str, Tuple[int, int]]

Mapping of well-ids to numpy indices.

property is_trough: bool

log(label: str | None) → None

Logs the current volumes to the history.

Parameters:

labelstr

A label to insert in the history.

property n_columns: int

property n_rows: int

remove(wells: str | Sequence[str] | ndarray, volumes: float | Sequence[float] | ndarray, label: str | None = None, *, on_underflow: Literal['debug', 'warn', 'raise'] = 'raise') → list[float]

Removes volumes from wells.

Parameters:

wellsiterable of str

Well ids

volumesfloat, iterable of float

Scalar or iterable of volumes

labelstr

Description of the operation

on_underflow

What to do about volume underflows (going below vmin) in non-empty wells.

Options:

• "debug" mentions the underflowing wells in a log message at DEBUG level.

• "warn" emits an VolumeUnderflowWarning. This can be captured in unit tests.

• "raise" raises a VolumeUnderflowError about underflowing wells.

Returns:

vaspirated

List of aspirated volumes according to previous filling volume and minima.

property report: str

A printable report of the labware history.

property shape: Tuple[int, int]

Number of rows and columns.

to_dict() → dict[str, Any]

Serialize to a dict of only atomic data types.

Use Labware.from_dict() to recreate a labware from the dict produced by this method.

property volumes: ndarray

Current volumes in the labware.

property wells: ndarray

Array of well ids.

class robotools.liquidhandling.labware.Trough(name: str, virtual_rows: int, columns: int, *, min_volume: float, max_volume: float, initial_volumes: float | Sequence[float] | ndarray = 0, column_names: Sequence[str | None] | None = None)

Bases: Labware

Special type of labware that can be accessed by many pipette tips in parallel.

Attributes:

composition

Relative composition of the liquids.

history

List of label/volumes history.

indices

Mapping of well-ids to numpy indices.

is_trough

n_columns

n_rows

report

A printable report of the labware history.

shape

Number of rows and columns.

volumes

Current volumes in the labware.

wells

Array of well ids.

Methods

add(wells, volumes[, label, compositions])	Adds volumes to wells.
condense_log(n[, label])	Condense the last n log entries.
from_dict(data[, cls_trough])	Creates a labware from a dict produced by Labware.to_dict().
get_well_composition(well)	Retrieves the relative composition of a well.
log(label)	Logs the current volumes to the history.
remove(wells, volumes[, label, on_underflow])	Removes volumes from wells.
to_dict()	Serialize to a dict of only atomic data types.