order_traceability

order_traceability ¤

Value-based traceability across stations.

Given multiple station UUIDs that each carry a string signal (any shared identifier — serial number, order number, batch ID, lot number, etc.), build an end-to-end timeline showing when each identifier was at each station, with durations and total lead times.

Typical use case: every machine on a production line writes the current identifier to its own UUID. This module joins those signals to answer "when was identifier X at station A, then B, then C?"

ValueTraceabilityEvents ¤

ValueTraceabilityEvents(
    dataframe: DataFrame,
    station_uuids: dict[str, str],
    *,
    event_uuid: str = "prod:value_trace",
    value_column: str = "value_string",
    time_column: str = "systime"
)

Bases: Base

Trace a shared identifier across multiple stations.

Each station has its own UUID that carries a string value (the identifier currently being processed — serial number, order ID, batch code, etc.). This module detects when a given identifier appears at each station and builds a timeline.

Example usage

trace = ValueTraceabilityEvents( df, station_uuids={ 'station_a_uuid': 'Station A', 'station_b_uuid': 'Station B', 'station_c_uuid': 'Station C', }, )

Full timeline of every identifier across all stations¤

timeline = trace.build_timeline()

Lead time from first to last station¤

lead = trace.lead_time()

Where is each identifier right now?¤

status = trace.current_status()

Station dwell-time statistics¤

dwell = trace.station_dwell_statistics()

Initialize value traceability.

Parameters:

Name	Type	Description	Default
`dataframe`	`DataFrame`	Input DataFrame with timeseries data.	required
`station_uuids`	`dict[str, str]`	Mapping of UUID -> human-readable station name. e.g. {'uuid_abc': 'Station A', 'uuid_def': 'Station B'}	required
`event_uuid`	`str`	UUID to tag derived events with.	`'prod:value_trace'`
`value_column`	`str`	Column holding the identifier string value.	`'value_string'`
`time_column`	`str`	Name of timestamp column.	`'systime'`

build_timeline ¤

build_timeline(
    *, infer_dwell_from_next: bool = False
) -> pd.DataFrame

Build a full timeline of every identifier at every station.

Parameters:

Name	Type	Description	Default
`infer_dwell_from_next`	`bool`	When False (default), an interval's `end` is the last sample of the identifier at that station, so a station that logs the identifier only once on arrival (the common event/change-encoded case) reports a dwell of `0`. When True, each visit's `end` is set to the same identifier's next station arrival, so the dwell is the honest arrival-here → arrival-at-next-station time. The last visit per identifier stays open (keeps its own last sample).	`False`

Returns:

Type	Description
`DataFrame`	DataFrame with columns:
`DataFrame`	identifier: The shared identifier string.
`DataFrame`	station_uuid: UUID of the station signal.
`DataFrame`	station_name: Human-readable station name.
`DataFrame`	start: Timestamp when the identifier appeared at the station.
`DataFrame`	end: Timestamp of the last sample at the station.
`DataFrame`	duration_seconds: Time spent at the station.
`DataFrame`	sample_count: Number of data points.
`DataFrame`	station_sequence: Order of visit (1-based) per identifier.
`DataFrame`	uuid: Event UUID.
`DataFrame`	source_uuid: UUID of the station signal (same as station_uuid).

lead_time ¤

lead_time() -> pd.DataFrame

Compute end-to-end lead time per identifier.

Returns:

Type	Description
`DataFrame`	DataFrame with columns:
`DataFrame`	identifier
`DataFrame`	first_station: Name of first station visited.
`DataFrame`	last_station: Name of last station visited.
`DataFrame`	first_seen: Earliest timestamp across all stations.
`DataFrame`	last_seen: Latest timestamp across all stations.
`DataFrame`	lead_time_seconds: Total time from first seen to last seen.
`DataFrame`	stations_visited: Number of distinct stations visited.
`DataFrame`	station_path: Arrow-separated ordered station names.
`DataFrame`	uuid: Event UUID.
`DataFrame`	start: Same as first_seen.
`DataFrame`	end: Same as last_seen.
`DataFrame`	duration_seconds: Same as lead_time_seconds (float seconds).
`DataFrame`	source_uuid: Comma-joined station UUIDs in visit order (each listed once).

current_status ¤

current_status(
    *, infer_dwell_from_next: bool = False
) -> pd.DataFrame

Determine the last-known station for each identifier.

Parameters:

Name	Type	Description	Default
`infer_dwell_from_next`	`bool`	Forwarded to :meth:`build_timeline`. Note the current (last) station's dwell is still open, so this mainly affects identifiers whose latest visit has a later arrival.	`False`

Returns:

Type	Description
`DataFrame`	DataFrame with columns:
`DataFrame`	identifier
`DataFrame`	current_station: Name of the last station where seen.
`DataFrame`	current_station_uuid: UUID of that station.
`DataFrame`	arrived_at: When the identifier arrived at the current station.
`DataFrame`	time_at_station_seconds: Dwell time at the current station so far.
`DataFrame`	uuid: Event UUID.

station_dwell_statistics ¤

station_dwell_statistics(
    *, infer_dwell_from_next: bool = False
) -> pd.DataFrame

Compute dwell-time statistics per station (across all identifiers).

Parameters:

Name	Type	Description	Default
`infer_dwell_from_next`	`bool`	Forwarded to :meth:`build_timeline`. Pass True when stations log an identifier once on arrival, so dwell is measured arrival-here → arrival-at-next-station instead of collapsing to zero.	`False`

Returns:

Type	Description
`DataFrame`	DataFrame with columns:
`DataFrame`	station_name
`DataFrame`	station_uuid
`DataFrame`	identifier_count: Number of distinct identifiers seen.
`DataFrame`	min_dwell_seconds
`DataFrame`	avg_dwell_seconds
`DataFrame`	max_dwell_seconds
`DataFrame`	total_dwell_seconds