Lineage from liquid handling
The Liquid Handling SDK records lineage events automatically. Tip, liquid, gripper, and labware operations on a liquid handler add events to the run, and the deck's labware is described.
Prerequisites
unitelabs-liquid-handling≥ 0.42.0- UniteLabs SDK ≥ 0.20.0
- UniteLabs Platform ≥ 0.34.0
- UniteLabs API ≥ 0.17.0
What the library records
| Operation | Recorded when | From → to | Main extras |
|---|---|---|---|
pick_up_tip | A channel picks up a tip | tip slot → channel | channel, tip, tip_type |
put_down_tip | A channel returns a tip to a rack | channel → tip slot | channel, tip, tip_type |
discard_tip | A channel drops a tip into a waste | channel → waste | channel, tip, origin_slot |
aspirate | A channel draws liquid | well or tube → channel | channel, volume_ul, mixture, liquid_class |
dispense | A channel expels liquid | channel → well or tube | channel, volume_ul, mixture, liquid_class |
mix_in_place | An aspirate or dispense mixes the well | well → same well | channel, volume_ul, cycles |
move_labware | A gripper or the autoload moves labware | site → site | labware, barcode |
pick_up_tool | Channels mount a tool, such as the CO-RE gripper | tool park site → channel | tool, tool_type |
put_down_tool | Channels return the tool | channel → tool park site | tool, tool_type |
load_labware | Labware is added to the instrument, or is on it at the start | → site | labware, barcode |
unload_labware | Labware is removed from the instrument | site → | labware, barcode |
seed_container | Liquid is in a well with no recorded source | → well or tube | volume_ul, mixture |
volume_ul is the volume of liquid transferred. If it differs from the volume specified in your workflow code, volume_requested_ul holds the requested volume. mixture lists the liquids that make up the transferred liquid, with the volume of each in microlitres.
Each side of an event names the entity it interacts with (see Entities for the kinds and their IDs).
A tube is labware of its own, so a transfer names the tube. When a tube is loaded, the event names its slot in the tube rack or the carrier site it sits in.
How entity IDs are constructed
A liquid handler's own parts carry its actor in their ID, like its channels do:
| Part | ID | Example |
|---|---|---|
| Deck | deck:<actor> | deck:star |
| Deck position | deck:<actor>:<position> | deck:star:7, deck:bravo:5 |
| Loading tray | loading_tray:<actor> | loading_tray:star |
| Tray track | loading_tray:<actor>:<track> | loading_tray:star:7 |
| Tool park site | park:<actor>:<tool> | park:star:CO-RE gripper |
| Waste | waste:<actor>:<name> | waste:star:WasteBlock |
What a deck position is depends on the liquid handler. A Hamilton carrier loads onto a deck track, deck:star:7, and a Bravo plate onto a deck location, deck:bravo:5.
The wastes depend on the liquid handler too. A STAR has a waste for the channels and one for the 96 head. A Bravo discard names the deck position it drops the tips into.
channel, deck, loading_tray, park or waste as a labware identifier: the library refuses them.Labware and liquid changes without robot action
At the first operation of a run, the library records a load_labware event for each item on the deck, and a seed_container event for each well that holds liquid in your deck setup. This is the starting state of the run. Labware you add later records its own load, and its liquid is seeded at that time.
If your code adds liquid to a well on the deck with add_liquid during the run, that is a seed_container event too. If your code removes liquid outside a robot action, the library records an audit event with the new volume. When liquid level detection finds a different volume than the model held, an audit event corrects it the same way.
Carriers on the loading tray
On a Hamilton STAR or Vantage, the loading tray is part of the instrument. When the autoload moves a carrier from the tray to the deck, the library records one move_labware event, from loading_tray:star:7 to deck:star:7. Unloading reverses it. The plates on the carrier keep their history.
Labware you take off the deck, for example with lh.deck.remove(plate) or by moving it onto a device with a gripper, is unloaded. Its wells' history ends there. If you load it again, the wells that hold liquid are seeded again from the model.
Failures
When an operation fails, the library records an error event for each channel or item the operation didn't complete. The event has the same operation, source, and target as the successful one would have, plus error (the exception class) and message in its extras. A cancelled operation is recorded the same way.
On a partial failure, such as 8 channels aspirating where 2 fail on a clot, the 6 channels that moved liquid record aspirate and the other 2 record error.
Next steps
- Data lineage: what lineage is and how the Platform shows it.
- Set up lineage for liquid handling: set up a workflow and check its events locally.
- Read lineage events from another system.
- Lineage delivery: when and how the SDK sends the events to the Platform.
- Emit lineage events for devices the library doesn't drive.
- Migrate the Liquid Handling SDK if your workflow records its own liquid-handling events.
Last updated