| Call | Signature | Does |
|---|---|---|
lh.setup |
() |
Connect the backend. Nothing works before it |
lh.stop |
() |
Close the connection |
lh.summary |
() |
Print the deck rail map, return None |
21 Cheat sheet
Every signature on this page is read from the installed PyLabRobot when the book is built, so it cannot drift from the version you have. A call that disappears upstream renders as MISSING rather than quietly becoming wrong.
21.1 Lifecycle
See chapter 1. async with LiquidHandler(...) as lh: calls both.
21.2 Pipetting
| Call | Signature | Does |
|---|---|---|
lh.aspirate |
(resources, vols, use_channels, flow_rates, …) |
Draw liquid from containers into tips |
lh.dispense |
(resources, vols, use_channels, flow_rates, …) |
Push liquid from tips into containers |
lh.transfer |
(source, targets, source_vol, ratios, …) |
Aspirate once, dispense to several targets |
lh.use_channels |
(channels) |
with: set the default channel set |
lh.aspirate96 |
(resource, volume, offset, flow_rate, …) |
96-head aspirate; takes a scalar volume |
lh.dispense96 |
(resource, volume, offset, flow_rate, …) |
96-head dispense; takes a scalar volume |
lh.stamp |
(source, target, volume, aspiration_flow_rate, …) |
Broken in 0.2.2 — dispenses into source |
vols is a list, one entry per channel. None means backend default, not zero. Chapter 4, chapter 6.
21.3 Tips
| Call | Signature | Does |
|---|---|---|
lh.pick_up_tips |
(tip_spots, use_channels, offsets) |
Pick up tips from tip spots |
lh.drop_tips |
(tip_spots, use_channels, offsets, allow_nonzero_volume) |
Drop tips at a destination you name |
lh.return_tips |
(use_channels, allow_nonzero_volume, offsets) |
Return tips to the spots they came from |
lh.discard_tips |
(use_channels, allow_nonzero_volume, offsets) |
Drop tips in the deck trash |
lh.use_tips |
(tip_spots, channels, discard) |
async with: pick up, then discard or return |
lh.get_mounted_tips |
() |
List of tips on the head, None where empty |
lh.probe_tip_inventory |
(tip_spots, probing_fn, use_channels) |
Ask the machine which spots hold tips |
lh.consolidate_tip_inventory |
(tip_racks, use_channels) |
Pack partial racks into fewer racks |
lh.pick_up_tips96 |
(tip_rack, offset) |
Pick up a whole rack with the 96-head |
lh.drop_tips96 |
(resource, offset, allow_nonzero_volume) |
Drop all 96 tips |
allow_nonzero_volume defaults to False for drop and return, True for discard. Chapter 8.
| Call | Signature | Does |
|---|---|---|
F.get_all_tip_spots |
(tip_racks) |
Flatten racks into one ordered spot list |
F.linear_tip_spot_generator |
(tip_spots, cache_file_path, repeat) |
Walk spots in order; resumes via cache_file_path |
F.randomized_tip_spot_generator |
(tip_spots, K, cache_file_path) |
Random spots, avoiding the last K used |
Both generators are async: await gen.get(n), or async for spot in gen. Exhaustion is StopAsyncIteration. Both also take set_index(i) / reset(), and neither reads the rack’s trackers — for that, filter rack.get_all_items() by has_tip() (chapter 8).
21.4 Indexing
| Call | Signature | Does |
|---|---|---|
plate.get_item |
(identifier) |
One item by (row, col) or identifier |
plate.get_items |
(identifiers) |
Several items by identifiers or indices |
plate.row |
(row) |
A full row, by index or letter |
plate.column |
(column) |
A full column, by index |
plate.traverse |
(batch_size, start, direction, repeat) |
Batches in fill order; start is required |
plate.get_quadrant |
(quadrant, quadrant_type, quadrant_internal_fill_order) |
96-in-384 mapping; "tl"/"tr"/"bl"/"br" |
plate.summary |
(occupied_func) |
Return a grid string (does not print) |
| Expression | Selects |
|---|---|
plate["A1:H1"] |
a range in fill order |
plate["A1", "B2"] |
exactly those wells |
plate[0] / plate[0:5] / plate[range(5)] |
by index — always a list |
plate.get_item((0, 0)) |
row, column — plate[(0, 0)] duplicates index 0 |
An unknown identifier raises IndexError. Chapter 5.
21.5 Deck and resources
| Call | Signature | Does |
|---|---|---|
deck.assign_child_resource |
(resource, location, reassign) |
Put a resource on the deck (rails= on Hamilton) |
deck.get_resource |
(name) |
Find by name, or ResourceNotFoundError |
deck.get_all_resources |
() |
Every resource on the deck, flat |
deck.check_can_drop_resource_here |
(resource, reassign) |
Non-mutating placement preflight |
deck.get_highest_known_point |
() |
Highest z on the deck |
deck.get_trash_area |
() |
The deck’s trash |
| Call | Signature | Does |
|---|---|---|
resource.get_absolute_location |
(x, y, z) |
Deck coordinate; z="t" for the top |
resource.get_all_children |
() |
Every descendant, flat |
resource.rotated |
(x, y, z) |
A new rotated copy — not in-place |
resource.unassign |
() |
Detach from its parent |
resource.assign_child_resource |
(resource, location, reassign) |
Attach a child at a location |
resource.save |
(fn, indent) |
Write layout JSON |
resource.save_state_to_file |
(fn, indent) |
Write state JSON |
resource.load_state_from_file |
(fn) |
Read state JSON back |
resource.serialize_state |
() |
This resource’s state as a dict |
resource.serialize_all_state |
() |
Name → state for the whole subtree |
.location is parent-relative; get_absolute_location() is the deck coordinate. Chapter 3, chapter 11.
21.6 Moving labware
| Call | Signature | Does |
|---|---|---|
lh.move_plate |
(plate, to, intermediate_locations, pickup_offset, …) |
Move a plate and update the tree |
lh.move_lid |
(lid, to, intermediate_locations, pickup_offset, …) |
Move a lid; a plate is a valid destination |
lh.move_resource |
(resource, to, intermediate_locations, pickup_offset, …) |
The general form |
lh.move_tips |
(source_tip_spots, dest_tip_spots) |
Move tips between spots |
Moved by hand? plate.unassign() then site.assign_child_resource(plate). Chapter 9.
21.7 Errors
| Error | Group | Raised when |
|---|---|---|
ResourceNotFoundError |
tree | a name lookup finds nothing |
NoLocationError |
tree | a resource has no location |
TooLittleLiquidError |
tracker | aspirating more than is present |
TooLittleVolumeError |
tracker | dispensing more than fits |
NoTipError |
tracker | a tip was expected |
HasTipError |
tracker / frontend | a tip is already there — two of these |
BlowOutVolumeError |
frontend | blow-out exceeds aspirated volume |
ChannelsDoNotFitError |
frontend | channels cannot be spaced |
ChannelizedError |
backend | STAR only — per-channel failures |
NoChannelError |
backend | Opentrons only |
CrossContaminationError |
— | never raised |
ResourceDefinitionIncompleteError |
— | never raised |
Only the tracker group is suppressible. Chapter 10.
21.8 Tracking
| Call | Signature | Does |
|---|---|---|
set_volume_tracking |
(enabled) |
Turn volume tracking on — off by default |
does_volume_tracking |
() |
Is it on? |
no_volume_tracking |
() |
with: suppress for a block |
set_tip_tracking |
(enabled) |
Turn tip tracking on — off by default |
no_tip_tracking |
() |
with: suppress for a block |
Neither no_* manager uses try/finally: an exception inside the block leaves tracking off. Chapter 10.
21.9 Backends and hardware
Abstract members a backend must implement:
aspirate, aspirate96, can_pick_up_tip, dispense, dispense96, drop_resource, drop_tips, drop_tips96, move_picked_up_resource, num_channels, pick_up_resource, pick_up_tips, pick_up_tips96, stop
14 total. setup is not abstract; stop is.
| Call | Signature | Does |
|---|---|---|
lh.prepare_for_manual_channel_operation |
(channel) |
Enter manual mode for one channel |
lh.move_channel_x |
(channel, x) |
Jog one channel, absolute mm |
lh.move_channel_y |
(channel, y) |
Jog one channel, absolute mm |
lh.move_channel_z |
(channel, z) |
Jog one channel, absolute mm |
Strictness.WARN is the default; STRICT raises on extra kwargs — but not against a backend declaring **kwargs, which the chatterbox does. Chapter 12, chapter 18.
21.10 Defining labware
| Helper | Signature | Does |
|---|---|---|
create_ordered_items_2d |
(klass, num_items_x, num_items_y, dx, dy, dz, …) |
Build a grid; extra kwargs go to each item |
height_volume_functions |
module | 20 volume ↔︎ height functions |
Bind geometry with a wrapper function, not functools.partial — PLR calls the callable positionally. PlateHolder.pedestal_size_z is required. Chapter 17.
21.11 System
| Call | Signature | Does |
|---|---|---|
start_capture |
(fp) |
Record device I/O to a file |
stop_capture |
() |
Stop recording and write it |
get_capture_or_validation_active |
() |
Is capture or replay on? |
Captures record from the io transport layer only — nothing from a chatterbox. pylabrobot.config configures logging only. PLR logs every call at DEBUG to the pylabrobot logger, which does not propagate. Chapter 13.
21.12 Naming convention
<vendor>_<count>_<type>_<volume>uL_<bottom>cor_96_wellplate_360uL_Fb — Corning, 96 wells, 360 µL, flat bottom. Old CamelCase names still import as deprecation shims. Chapter 2.
21.13 Defaults worth memorising
| Thing | Default |
|---|---|
| Volume tracking | off |
| Tip tracking | off |
Strictness |
WARN |
allow_nonzero_volume |
False for drop/return, True for discard |
spread |
"wide" |
| Channel spacing | 9 mm |
head96_installed |
False |
| Visualizer ports | ws 2121, files 1337 |