UniteLabs
Concept

Data lineage

Follow material, samples, and labware through a workflow run.

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:A1 to channel:star:pipettes:0; a dispense event connects that channel to target_plate:B1.
  • Workspace context describes the labware events refer to. It tells the Platform that source_plate is 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:

KindEntityIDExample
labwarePlate, reservoir, rack, carrier, tool, deck<labware>source_plate
wellWell of a plate, compartment of a reservoir<labware>:<address>source_plate:A1
tubeA tube, which is labware of its own<tube>sample_7
tip_slotSlot of a tip rack<rack>:<address>tips:A1
tube_slotSlot of a tube rack, where a tube sits<rack>:<address>tube_rack:A1
carrier_siteSite on a carrier (0-based)<carrier>:<n>plate_carrier:2
deck_sitePosition or track on a liquid handler's deckdeck:<actor>:<position>deck:star:7
loading_tray_siteTrack on the loading tray of a Hamilton autoloadloading_tray:<actor>:<track>loading_tray:star:7
tool_sitePark site of a toolpark:<actor>:<tool>park:star:CO-RE gripper
channelPipetting channelchannel:<actor>:<module>:<n>channel:star:pipettes:3
wasteTip wastewaste:<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:

TypeMeaning
lineageMaterial, tip, tool, and labware movement that took place.
errorAn operation that failed. It names what the operation would have touched.
auditA correction of a known volume, for example after liquid level detection.
identificationAn identity associated with an entity, such as a barcode.
measurementA 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

Last updated