robotools.worklists

Creating worklist files for the Tecan Freedom EVO.

class robotools.worklists.base.BaseWorklist(filepath: str | Path | None = None, max_volume: int | float = 950, auto_split: bool = True, diti_mode: bool = False)

Bases: list[str]

Context manager for the creation of Worklists.

Attributes:

filepath

Path to which the worklist will write, if specified.

Methods

append(object, /)	Append object to the end of the list.
aspirate(labware, wells, volumes, *[, ...])	Performs aspiration from the provided labware.
aspirate_well(rack_label, position, volume, *)	Command for aspirating with a single tip.
clear(/)	Remove all items from list.
comment(comment)	Adds a comment.
commit()	Inserts a 'break' that forces the execution of aspirate/dispense operations at this point.
copy(/)	Return a shallow copy of the list.
count(value, /)	Return number of occurrences of value.
decontaminate()	Decontamination wash consists of a decontamination wash followed by a normal wash.
dispense(labware, wells, volumes, *[, ...])	Performs dispensing into the provided labware.
dispense_well(rack_label, position, volume, *)	Command for dispensing with a single tip.
distribute(source, source_column, ...[, ...])	Transfers from a Trough into many destination wells using multi-pipetting.
extend(iterable, /)	Extend list by appending elements from the iterable.
flush()	Discards the contents of the tips WITHOUT WASHING or DROPPING of tips.
index(value[, start, stop])	Return first index of value.
insert(index, object, /)	Insert object before index.
pop([index])	Remove and return item at index (default last).
reagent_distribution(src_rack_label, ...[, ...])	Transfers from a Trough into many destination wells using multi-pipetting.
remove(value, /)	Remove first occurrence of value.
reverse(/)	Reverse IN PLACE.
save(filepath)	Writes the worklist to the filepath.
set_diti(diti_index)	Switches the DiTi types within the worklist.
sort(*[, key, reverse])	Sort the list in ascending order and return None.
wash([scheme])	Washes fixed tips or replaces DiTis.

transfer

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

Performs aspiration from the provided labware.

Parameters:

labwareliquidhandling.Labware

Source labware

wellsstr or iterable

List of well ids

volumesfloat or iterable

Volume(s) to aspirate

labelstr

Label of the operation to log into labware history

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.

kwargs

Additional keyword arguments to pass to aspirate_well. Most prominent example: liquid_class. Take a look at Worklist.aspirate_well for the full list of options.

Returns:

vaspirated

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

aspirate_well(rack_label: str, position: int, volume: float, *, liquid_class: str = '', tip: Tip | int | Iterable = Tip.Any, rack_id: str = '', tube_id: str = '', rack_type: str = '', forced_rack_type: str = '') → None

Command for aspirating with a single tip.

Each Aspirate record specifies the aspiration parameters for a single tip (the next unused tip from the tip selection you have specified).

Parameters:

rack_labelstr

User-defined labware name (max 32 characters)

positionint

Number of the well

volumefloat

Volume in microliters (will be rounded to 2 decimal places)

liquid_classstr, optional

Overwrites the liquid class for this step (max 32 characters)

tipTip, int or Iterable of Tip / int, optional

Tip that will be selected (Tip, 1-8 or Iterable of the former two)

rack_idstr, optional

Barcode of the labware (max 32 characters)

tube_idstr, optional

Barcode of the tube (max 32 characters)

rack_typestr

Configuration name of the labware (max 32 characters). An error is raised if it missmatches with the underlying worktable.

forced_rack_typestr, optional

Overrides rack_type from worktable

comment(comment: str | None) → None

Adds a comment.

Parameters:

commentstr

A single- or multi-line comment. Be nice and avoid special characters.

commit() → None

Inserts a ‘break’ that forces the execution of aspirate/dispense operations at this point.

WARNING: may be unreliable

If you don’t specify a Break record, Freedom EVOware normally executes pipetting commands in groups to optimize the efficiency. For example, if you have specified four tips in the Worklist command, Freedom EVOware will queue Aspirate records until four of them are ready for execution. This allows pipetting to take place using all four tips at the same time. Specify the Break record if you want to execute all of the currently queued commands without waiting. You can use the Break record e.g. to create a worklist which pipettes using only one tip at a time (even if you chose more than one tip in the tip selection).

decontaminate() → None

Decontamination wash consists of a decontamination wash followed by a normal wash.

dispense(labware: Labware, wells: str | Sequence[str] | ndarray, volumes: float | Sequence[float] | ndarray, *, label: str | None = None, compositions: List[Dict[str, float] | None] | None = None, vtrack: float | Sequence[float] | ndarray | None = None, **kwargs) → None

Performs dispensing into the provided labware.

Parameters:

labwareliquidhandling.Labware

Source labware

wellsstr or iterable

List of well ids

volumesfloat or iterable

Volume(s) to dispense in the command

labelstr

Label of the operation to log into labware history

compositionslist

Iterable of liquid compositions

vtrack

Volume to add to the destination in digital volume tracking. Defaults to volume. Used by transfer commands to account for on_underflow situations where more volume was aspirated than considered aspiratable based on volume tracking.

kwargs

Additional keyword arguments to pass to dispense_well. Most prominent example: liquid_class. Take a look at Worklist.dispense_well for the full list of options.

dispense_well(rack_label: str, position: int, volume: float, *, liquid_class: str = '', tip: Tip | int = Tip.Any, rack_id: str = '', tube_id: str = '', rack_type: str = '', forced_rack_type: str = '') → None

Command for dispensing with a single tip.

Each Dispense record specifies the dispense parameters for a single tip. It uses the same tip which was used by the preceding Aspirate record.

Parameters:

rack_labelstr

User-defined labware name (max 32 characters)

positionint

Number of the well

volumefloat

Volume in microliters (will be rounded to 2 decimal places)

liquid_classstr, optional

Overwrites the liquid class for this step (max 32 characters)

tipTip, int or Iterable of Tip / int, optional

Tip that will be selected (Tip, 1-8 or Iterable of the former two)

rack_idstr, optional

Barcode of the labware (max 32 characters)

tube_idstr, optional

Barcode of the tube (max 32 characters)

rack_typestr, optional

Configuration name of the labware (max 32 characters). An error is raised if it missmatches with the underlying worktable.

forced_rack_typestr, optional

Overrides rack_type from worktable

distribute(source: Labware, source_column: int, destination: Labware, destination_wells: str | Sequence[str] | ndarray, *, volume: float, diti_reuse: int = 1, multi_disp: int = 1, liquid_class: str = '', label: str = '', direction: str = 'left_to_right', src_rack_id: str = '', src_rack_type: str = '', dst_rack_id: str = '', dst_rack_type: str = '') → None

Transfers from a Trough into many destination wells using multi-pipetting.

Does NOT support large volume operations.

Parameters:

sourceliquidhandling.Labware

Source labware with virtual_rows (a Trough)

source_columnint

0-based column number of the reagent in the source labware

destinationliquidhandling.Labware

Destination labware

destination_wellsarray-like

List or array of destination wells

volumefloat

Microliters to dispense into each destination

multi_dispint

Maximum number of allowed multi-dispenses

liquid_classstr

Liquid class to use for the operation

labelstr

Label of the operation

diti_reuseint

Number of allowed re-uses for disposable tips

directionstr

Moving direction on the destination (‘left_to_right’ or ‘right_to_left’)

src_rack_idstr, optional

Barcode of the source labware

src_rack_typestr, optional

Configuration name of the source labware

dst_rack_idstr, optional

Barcode of the destination labware

dst_rack_typestr

Configuration name of the destination labware

property filepath: Path | None

Path to which the worklist will write, if specified.

flush() → None

Discards the contents of the tips WITHOUT WASHING or DROPPING of tips.

reagent_distribution(src_rack_label: str, src_start: int, src_end: int, dst_rack_label: str, dst_start: int, dst_end: int, *, volume: float, diti_reuse: int = 1, multi_disp: int = 1, exclude_wells: Iterable[int] | None = None, liquid_class: str = '', direction: str = 'left_to_right', src_rack_id: str = '', src_rack_type: str = '', dst_rack_id: str = '', dst_rack_type: str = '') → None

Transfers from a Trough into many destination wells using multi-pipetting.

⚠ This is the low-level version. Use .distribute() for a more user-friendly signature. ⚠

Parameters:

src_rack_labelstr

Name of the source labware on the worktable

src_startint

First well to be used in the source labware

end_startint

Last well to be used in the source labware

src_rack_labelstr

Name of the destination labware on the worktable

src_startint

First well to be used in the destination labware

end_start :int

Last well to be used in the destination labware

volumefloat

Microliters to dispense into each destination

diti_reuseint

Number of allowed re-uses for disposable tips

multi_dispint

Maximum number of allowed multi-dispenses

exclude_wellslist

Numbers of destination wells to skip

liquid_classstr

Liquid class to use for the operation

directionstr

Moving direction on the destination (‘left_to_right’ or ‘right_to_left’)

src_rack_idstr, optional

Barcode of the source labware

src_rack_typestr, optional

Configuration name of the source labware

dst_rack_idstr, optional

Barcode of the destination labware

dst_rack_typestr, optional

Configuration name of the destination labware

save(filepath: str | Path) → None

Writes the worklist to the filepath.

Parameters:

filepath

File name or path to write (must include a .gwl extension)

set_diti(diti_index: int) → None

Switches the DiTi types within the worklist.

IMPORTANT: As the DiTi index in worklists is 1-based you have to increase the shown DiTi index by one.

Choose the required DiTi type by specifying the DiTi index. Freedom EVOware automatically assigns a unique index to each DiTi type. The DiTi index is shown in the Edit Labware dialog box for the DiTi labware (Well dimensions tab).

The Set DiTi Type record can only be used at the very beginning of the worklist or directly after a Break record. A Break record always resets the DiTi type to the type selected in the Worklist command. Accordingly, if your worklist contains a Break record, you may need to specify the Set DiTi Type record again.

Parameters:

diti_indexint

Type of DiTis to use in subsequent steps

transfer(source: Labware, source_wells: str | Sequence[str] | ndarray, destination: Labware, destination_wells: str | Sequence[str] | ndarray, volumes: float | Sequence[float] | ndarray, *, label: str | None = None, wash_scheme: Literal[1, 2, 3, 4, 'flush', 'reuse'] = 1, partition_by: str = 'auto', **kwargs)

wash(scheme: int = 1) → None

Washes fixed tips or replaces DiTis.

Washes/replaces the tip that was used by the preceding aspirate record(s).

Parameters:

schemeint

Number indicating the wash scheme (default: 1)

Exceptions related to liquid handling with worklists.

exception robotools.worklists.exceptions.CompatibilityError

Bases: NotImplementedError

Exception that’s thrown when device-specific implementations are required.

exception robotools.worklists.exceptions.InvalidOperationError

Bases: Exception

When an operation cannot be performed under the present circumstances.

Utility functions that are relevant for worklist commands.

robotools.worklists.utils.optimize_partition_by(source: Labware, destination: Labware, partition_by: str, label: str | None = None) → Literal['source', 'destination']

Determines optimal partitioning settings.

Parameters:

source

Source labware object.

destination

Destination labware object.

partition_by

User-provided partitioning settings.

label

Label of the operation (optional).

———-

source (Labware): source labware object

destination (Labware): destination labware object

partition_bystr

user-provided partitioning settings

labelstr

label of the operation (optional)

Returns:

partition_by

Either ‘source’ or ‘destination’

robotools.worklists.utils.partition_by_column(sources: Iterable[str], destinations: Iterable[str], volumes: Iterable[float], partition_by: Literal['source', 'destination']) → List[Tuple[List[str], List[str], List[float]]]

Partitions sources/destinations/volumes by the source column and sorts within those columns.

Parameters:

sourceslist

The source well ids; same length as destinations and volumes

destinationslist

The destination well ids; same length as sources and volumes

volumeslist

The volumes; same length as sources and destinations

partition_bystr

Either ‘source’ or ‘destination’

Returns:

column_groupslist

A list of (sources, destinations, volumes)

robotools.worklists.utils.partition_volume(volume: float, *, max_volume: int | float) → List[float]

Partitions a pipetting volume into zero or more integer-valued volumes that are <= max_volume.

Parameters:

volumefloat

A volume to partition

max_volumeint

Maximum volume of a pipetting step

Returns:

volumeslist

Partitioned volumes

robotools.worklists.utils.prepare_aspirate_dispense_parameters(rack_label: str, position: int, volume: float, liquid_class: str = '', tip: Tip | int | Iterable = Tip.Any, rack_id: str = '', tube_id: str = '', rack_type: str = '', forced_rack_type: str = '', max_volume: int | float | None = None) → Tuple[str, int, str, str, Tip | int | Iterable, str, str, str, str]

Validates and prepares aspirate/dispense parameters.

Parameters:

rack_labelstr

User-defined labware name (max 32 characters)

positionint

Number of the well

volumefloat

Volume in microliters (will be rounded to 2 decimal places)

liquid_classstr, optional

Overrides the liquid class for this step (max 32 characters)

tipTip, int or Iterable of Tip / int, optional

Tip that will be selected (Tip, 1-8 or Iterable of the former two)

rack_idstr, optional

Barcode of the labware (max 32 characters)

tube_idstr, optional

Barcode of the tube (max 32 characters)

rack_typestr, optional

Configuration name of the labware (max 32 characters). An error is raised if it missmatches with the underlying worktable.

forced_rack_typestr, optional

Overrides rack_type from worktable

max_volumeint, optional

Maximum allowed volume

Returns:

rack_labelstr

User-defined labware name (max 32 characters)

positionint

Number of the well

volumestr

Volume in microliters (will be rounded to 2 decimal places)

liquid_classstr

Overrides the liquid class for this step (max 32 characters)

tipTip, int or Iterable of Tip / int

Tip that will be selected (Tip, 1-8 or Iterable of the former two)

rack_idstr

Barcode of the labware (max 32 characters)

tube_idstr

Barcode of the tube (max 32 characters)

rack_typestr

Configuration name of the labware (max 32 characters). An error is raised if it missmatches with the underlying worktable.

forced_rack_typestr

Overrides rack_type from worktable