multi_process_traceability

multi_process_traceability ¤

Multi-process traceability across parallel and sequential stations.

Handles real production topologies where: - Each station / process segment has its own ID UUID (carrying the current order / serial number). - Multiple handover signals exist between station pairs (fires when an item transfers). - Stations can run in parallel (e.g., two welding cells feeding one painting station).

Example topology::

Welding Cell 1 ─┐
                 ├─► Painting ─► Assembly ─► Test
Welding Cell 2 ─┘

Each cell has its own id_uuid that carries the serial number currently being processed. Handover signals between cells confirm the transfer.

MultiProcessTraceabilityEvents ¤

MultiProcessTraceabilityEvents(
    dataframe: DataFrame,
    processes: List[Dict[str, str]],
    *,
    handovers: Optional[List[Dict[str, str]]] = None,
    event_uuid: str = "prod:multi_process_trace",
    id_value_column: str = "value_string",
    handover_value_column: str = "value_integer",
    time_column: str = "systime"
)

Bases: Base

Trace items across a multi-station topology with parallel paths.

Example usage::

trace = MultiProcessTraceabilityEvents(
    df,
    processes=[
        {"id_uuid": "serial_weld1",  "station": "Welding Cell 1"},
        {"id_uuid": "serial_weld2",  "station": "Welding Cell 2"},
        {"id_uuid": "serial_paint",  "station": "Painting"},
        {"id_uuid": "serial_assy",   "station": "Assembly"},
    ],
    handovers=[
        {"uuid": "ho_w1_paint", "from_station": "Welding Cell 1", "to_station": "Painting"},
        {"uuid": "ho_w2_paint", "from_station": "Welding Cell 2", "to_station": "Painting"},
        {"uuid": "ho_paint_assy", "from_station": "Painting", "to_station": "Assembly"},
    ],
)

timeline = trace.build_timeline()
lead = trace.lead_time()
parallel = trace.parallel_activity()
handover_log = trace.handover_log()
paths = trace.routing_paths()
station_stats = trace.station_statistics()

Initialize multi-process traceability.

Parameters:

Name	Type	Description	Default
`dataframe`	`DataFrame`	Input DataFrame with timeseries data.	required
`processes`	`List[Dict[str, str]]`	List of process definitions, each a dict with: - id_uuid: UUID of the signal carrying item IDs at this station. - station: Human-readable station name.	required
`handovers`	`Optional[List[Dict[str, str]]]`	Optional list of handover signal definitions, each a dict: - uuid: UUID of the handover signal. - from_station: Station name the item leaves. - to_station: Station name the item arrives at. Handover signal value > 0 (or True) indicates a transfer event.	`None`
`event_uuid`	`str`	UUID to tag derived events with.	`'prod:multi_process_trace'`
`id_value_column`	`str`	Column holding item ID strings in process signals.	`'value_string'`
`handover_value_column`	`str`	Column holding handover trigger values.	`'value_integer'`
`time_column`	`str`	Name of timestamp column.	`'systime'`

build_timeline ¤

build_timeline() -> pd.DataFrame

Build a full timeline of every item at every station.

Handles parallel stations: the same item may appear at overlapping time intervals at different stations (concurrent processing), or different items at parallel cells of the same station type.

Returns:

Type	Description
`DataFrame`	DataFrame with columns:
`DataFrame`	item_id: Order / serial number.
`DataFrame`	station: Human-readable station name.
`DataFrame`	id_uuid: Source UUID for this station's ID signal.
`DataFrame`	start: Interval start.
`DataFrame`	end: Interval end.
`DataFrame`	duration_seconds: Time at this station.
`DataFrame`	sample_count: Number of data points.
`DataFrame`	step_sequence: Visit order per item (1-based, by start time).
`DataFrame`	is_parallel: True if this interval overlaps with another station for the same item.
`DataFrame`	uuid: Event UUID.

lead_time ¤

lead_time() -> pd.DataFrame

Compute end-to-end lead time per item across all processes.

Returns:

Type	Description
`DataFrame`	DataFrame with columns:
`DataFrame`	item_id
`DataFrame`	first_station: First station visited.
`DataFrame`	last_station: Last station visited.
`DataFrame`	first_seen: Earliest timestamp.
`DataFrame`	last_seen: Latest timestamp.
`DataFrame`	lead_time_seconds: Total elapsed time.
`DataFrame`	stations_visited: Number of distinct stations.
`DataFrame`	station_path: Ordered station names (" -> ").
`DataFrame`	has_parallel: Whether item had parallel processing.
`DataFrame`	uuid: Event UUID.

parallel_activity ¤

parallel_activity() -> pd.DataFrame

Find items that were processed at multiple stations simultaneously.

Returns:

Type	Description
`DataFrame`	DataFrame with columns:
`DataFrame`	item_id
`DataFrame`	station_a: First overlapping station.
`DataFrame`	station_b: Second overlapping station.
`DataFrame`	overlap_start: Start of overlap period.
`DataFrame`	overlap_end: End of overlap period.
`DataFrame`	overlap_seconds: Duration of overlap.
`DataFrame`	uuid: Event UUID.

handover_log ¤

handover_log() -> pd.DataFrame

Extract handover events and correlate with item IDs.

For each handover signal, detects trigger points (value > 0 or value changes to a truthy state) and resolves which item was being transferred based on the from-station's ID signal at that time.

Returns:

Type	Description
`DataFrame`	DataFrame with columns:
`DataFrame`	timestamp: When the handover fired.
`DataFrame`	item_id: Item being transferred (from from_station's ID signal).
`DataFrame`	from_station: Source station.
`DataFrame`	to_station: Destination station.
`DataFrame`	handover_uuid: UUID of the handover signal.
`DataFrame`	handover_value: Raw value of the handover signal.
`DataFrame`	uuid: Event UUID.

station_statistics ¤

station_statistics() -> pd.DataFrame

Compute dwell-time statistics per station across all items.

Distinguishes parallel cells of the same station type.

Returns:

Type	Description
`DataFrame`	DataFrame with columns:
`DataFrame`	station: Station name.
`DataFrame`	id_uuid: Specific cell UUID (for parallel cells).
`DataFrame`	item_count: Distinct items processed.
`DataFrame`	min_dwell_seconds
`DataFrame`	avg_dwell_seconds
`DataFrame`	max_dwell_seconds
`DataFrame`	total_dwell_seconds

routing_paths ¤

routing_paths() -> pd.DataFrame

Analyze routing path frequencies across all items.

Returns:

Type	Description
`DataFrame`	DataFrame with columns:
`DataFrame`	station_path: Ordered station names (" -> ").
`DataFrame`	item_count: Items that followed this path.
`DataFrame`	avg_lead_time_seconds
`DataFrame`	min_lead_time_seconds
`DataFrame`	max_lead_time_seconds
`DataFrame`	has_parallel_steps: Whether path includes parallel processing.