Data lineage
Data lineage records what happened to material (samples, consumables, liquids) during a workflow run. It ties each action (an aspirate, a robotic arm moving a plate) to its source, destination, time, and actor, so you can follow a sample through the lab.
For example, a liquid transfer can produce this path:
Source plate A1 → Pipette channel 0 → Target plate B1
From that path you can answer:
- Where did the liquid in the target well come from?
- Which operations changed a sample?
- Which device or tool performed each action?
- When did each action happen, and which ones failed?
What you can use it for
Use lineage to review what happened in a well, trace material back to its sources, investigate a run result, or tie an identity such as a barcode to labware.
Lineage is also available through the API. A LIMS, audit store, or data pipeline can read completed history or subscribe to new events while runs are active.
What is included
UniteLabs provides:
- Run-level storage for lineage events.
- Well History and Lineage Graph views in the Platform UI.
- An API for historical reads and live event streaming.
- Workspace context that gives event references labware names, types, roles, and barcodes.
- Automatic recording of liquid handling operations, such as aspirate, dispense, and mix, by the Liquid Handling SDK. See Lineage from liquid handling.
For events the library doesn't record, a workflow can add its own with Audit.emit. See Emit lineage events.
How lineage works
A run's lineage has two parts:
- Events record actions. An aspirate event connects
source_plate:A1tochannel:star:pipettes:0; a dispense event connects that channel totarget_plate:B1. - Workspace context describes the labware events refer to. It tells the Platform that
source_plateis a well plate named "Source plate" with barcode "SOURCE-001".
Liquid handler operation
│
▼
Event + workspace context (recorded by the Liquid Handling SDK)
│
▼
UniteLabs Platform (sent by the SDK at each phase boundary)
│
├── Run view
└── Lineage API
Entities
Each event names the entity the material came from and the entity it went to. An entity has a short string ID and a kind:
| Kind | Entity | ID | Example |
|---|---|---|---|
labware | Plate, reservoir, rack, carrier, tool, deck | <labware> | source_plate |
well | Well of a plate, compartment of a reservoir | <labware>:<address> | source_plate:A1 |
tube | A tube, which is labware of its own | <tube> | sample_7 |
tip_slot | Slot of a tip rack | <rack>:<address> | tips:A1 |
tube_slot | Slot of a tube rack, where a tube sits | <rack>:<address> | tube_rack:A1 |
carrier_site | Site on a carrier (0-based) | <carrier>:<n> | plate_carrier:2 |
deck_site | Position or track on a liquid handler's deck | deck:<actor>:<position> | deck:star:7 |
loading_tray_site | Track on the loading tray of a Hamilton autoload | loading_tray:<actor>:<track> | loading_tray:star:7 |
tool_site | Park site of a tool | park:<actor>:<tool> | park:star:CO-RE gripper |
channel | Pipetting channel | channel:<actor>:<module>:<n> | channel:star:pipettes:3 |
waste | Tip waste | waste:<actor>:<name> | waste:star:WasteBlock |
A well, a tube slot and a carrier site all use the same ID shape, <parent>:<address>. To tell them apart, each side of an event lists its kind and the parts of its ID next to the ID itself:
{ "entity_id": "source_plate:A1", "kind": "well", "parent": "source_plate", "address": "A1" }
{ "entity_id": "channel:star:pipettes:3", "kind": "channel", "actor": "star", "module": "pipettes", "index": 3 }
{ "entity_id": "deck:star:7", "kind": "deck_site", "parent": "deck:star", "address": "7", "actor": "star" }
Anything a liquid handler owns has its actor in the ID. That covers the channels, deck (deck:<actor>), loading tray (loading_tray:<actor>), park sites of its tools and wastes. Two liquid handlers in one run never share a deck position or a waste. A STAR with one waste block for the channels and another for the 96 head records two wastes.
The <module> part of a channel ID names the pipetting module of the liquid handler: pipettes for the single channels and pipette_head for a multi-channel head, such as a 96 head. A Hamilton Vantage with XL channels has a second set of single channels, pipettes_xl. Its channel 0 is channel:vantage:pipettes_xl:0, which is a different channel from channel:vantage:pipettes:0. The <n> part is the index of the channel in its module.
The words channel, deck, loading_tray, park and waste are reserved for these IDs and can't be labware identifiers.
The kind defines what type of physical object an entity represents. The Platform and any other software that uses lineage events can then treat each kind on its own, for example show wells, tip slots and deck positions differently.
Labware IDs are the identifier of the labware in your deck setup. Keep them unique within a run. A unique identifier lets a plate keep one history throughout the workflow, even when a gripper moves it between devices.
Event categories
Each event has a type:
| Type | Meaning |
|---|---|
lineage | Material, tip, tool, and labware movement that took place. |
error | An operation that failed. It names what the operation would have touched. |
audit | A correction of a known volume, for example after liquid level detection. |
identification | An identity associated with an entity, such as a barcode. |
measurement | A measured value associated with an entity. |
A failed aspirate is an error event, not a lineage event.
What the Platform shows
Open a run and select the Lineage tab:
- Well History shows the events of a selected well, tip slot, channel, or site, with the volume the well holds after each event.
- Lineage Graph shows resources and the movement between them. Failed operations are marked as red dashed edges. Events with the same verb between the same two resources share one edge, labeled with their count, for example
ASPIRATE ×2. A run with too many connections to draw at once opens on a search. - Trace upstream narrows the graph to the sources that contributed to a well, labware, channel, or barcode that you search for. It lists only the events that happened before the last dispense into that resource. For example, a sample that a channel aspirated after it dispensed into the traced well is not a source of that well.
The following example traces a well of a lysis plate upstream. Channel 0 of the STAR picked up a tip, aspirated sample S01, and dispensed it into the lysis buffer in lysis_plate:A1.

The well history of the sample well in the same run shows its seeded volume, an aspirate, a correction by liquid level detection, and a failed aspirate.

On an active run, new events show up as they reach the Platform, by default when each phase exits. You can also download the run's lineage as JSON.
Next steps
- Lineage from liquid handling: what the library records and how to get better lineage.
- Set up lineage for liquid handling and check the events before you deploy.
- Emit lineage events for devices the library doesn't drive.
- Read lineage events through the API or live event stream.
- Read Labware to understand resource identifiers and parent-child relationships.
Last updated