Emit lineage events
Some libraries record lineage for the devices they drive. For example, the Liquid Handling SDK records every liquid handler operation (see Lineage from liquid handling). For other devices, such as a shaker, a plate reader, or a barcode scanner, emit the events from your workflow.
For the model and Platform views, see Data lineage. For API access, see Read lineage events.
Prerequisites
- UniteLabs SDK ≥ 0.20.0
- A workflow executed on the UniteLabs Platform
Audit.emit records into the active run context. Code inside @workflow, @phase, and @step functions has one. Outside a run context, Audit.emit returns without recording anything. To record events in a script or test, use with Audit.capture() as ctx: and read them from ctx.state["events"].
Record an operation
Emit the event in your workflow after the operation succeeds:
from unitelabs.sdk import Audit, Operation
from unitelabs.sdk.automate import lineage
plate = lineage.labware("sample_plate")
# After the shaker finished shaking the plate:
Audit.emit(
"shaker",
Operation.SHAKE,
lineage.entity(plate),
lineage.entity(plate),
lineage.VERSION,
extras={"rpm": 1200, "duration_s": 300},
)
| Argument | Meaning | Example |
|---|---|---|
actor | The device or service that performed the operation. | shaker |
operation | What happened, as an Operation member. | SHAKE |
inputs | The entity the material came from. {} for none. | sample_plate |
outputs | The entity that received it. {} for none. | sample_plate |
version | The payload contract version. Pass lineage.VERSION. | 2.0.0 |
extras | Optional facts about the operation. | speed and duration |
event_type | The event category. The default is lineage. | lineage |
The SDK adds an event ID, a timestamp, and the IDs of the active flow and task run.
Name entities
unitelabs.sdk.automate.lineage builds entity IDs: labware, well, tube, tip_slot, tube_slot, carrier_site and sample, and for the parts of an instrument channel, deck, deck_site, loading_tray, loading_tray_site, park and waste, which take the actor. Each builder returns an ID that knows its kind. lineage.entity writes the kind and the parts of the ID next to it. With lineage.VERSION as the event's version, the Platform reads the kind instead of guessing from the ID. For the kinds and their parts, see Entity sides.
Use the same labware identifiers as your deck setup. Your events then join the history that other libraries record for the same labware. The words channel, deck, loading_tray, park and waste are reserved and can't be labware identifiers.
To check a payload in a test, use lineage.validate_event. It returns a list of problems with the payload for its operation.
Describe labware
Events name labware by a short ID. The workspace context gives the Platform a name, a type, a role, and a barcode for each ID. Add an entry to ctx.state["labware_context"] for labware that no library describes:
from unitelabs.sdk import get_context
ctx = get_context()
ctx.state.setdefault("labware_context", {})["sample_plate"] = {
"name": "Sample plate",
"type": "Eppendorf_96_PCR",
"role": "wellplate",
"barcode": "SAMPLE-001",
}
The SDK sends the workspace at the next phase boundary when it has changed. For the role values, see Read workspace context.
Choose an event category
Set event_type to the category of the event:
| Category | Use for |
|---|---|
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. |
To record a barcode you scan during the run, emit an identification event:
Audit.emit(
"barcode_reader",
Operation.LOAD_LABWARE,
{},
lineage.entity(lineage.labware("sample_plate")),
lineage.VERSION,
event_type="identification",
extras={"barcode": "SAMPLE-001"},
)
Choose an operation
Operation has these members: ASPIRATE, DISPENSE, MIX_IN_PLACE, SEED_CONTAINER, PICK_UP_TIP, PUT_DOWN_TIP, DISCARD_TIP, PICK_UP_TOOL, PUT_DOWN_TOOL, MOVE_LABWARE, LOAD_LABWARE, UNLOAD_LABWARE, OPEN_CONTAINER, CLOSE_CONTAINER, THERMAL_CONTROL, SHAKE and CENTRIFUGE. If no member matches exactly, use the closest one and put the details in extras.
Delivery
The SDK sends the events and the workspace when each phase exits and when the workflow exits. To send them earlier, or to fail the run when they can't be sent, see Lineage delivery.
Last updated