batch_tracking

batch_tracking

Batch / recipe production tracking.

Detect batch boundaries from a string signal that carries the current batch ID, compute duration statistics, per-batch yield, and batch transition matrices.

BatchTrackingEvents

BatchTrackingEvents(
    dataframe: DataFrame,
    batch_uuid: str,
    *,
    event_uuid: str = "prod:batch",
    value_column: str = "value_string",
    time_column: str = "systime"
)

Bases: Base

Track batch/recipe production from a batch-ID string signal.

A "batch" is defined as a contiguous period where the batch-ID value remains constant. A new batch begins when the value changes.

Example usage

batches = BatchTrackingEvents(df, batch_uuid='batch_id_signal')

detected = batches.detect_batches() stats = batches.batch_duration_statistics() yields = batches.batch_yield('part_counter') transitions = batches.batch_transition_matrix()

Initialize batch tracker.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	Input DataFrame with timeseries data.	required
batch_uuid	str	UUID of the batch-ID signal.	required
event_uuid	str	UUID to tag derived events with.	'prod:batch'
value_column	str	Column holding the batch ID string.	'value_string'
time_column	str	Name of timestamp column.	'systime'

detect_batches

detect_batches() -> pd.DataFrame

Detect batch start/end from value changes in the batch-ID signal.

Returns:

Type	Description
DataFrame	DataFrame with columns:
DataFrame	batch_id: The batch identifier string.
DataFrame	start: Timestamp of the first sample in the batch.
DataFrame	end: Timestamp of the last sample in the batch.
DataFrame	duration_seconds: Duration of the batch.
DataFrame	sample_count: Number of data points in the batch.
DataFrame	uuid: Event UUID.
DataFrame	source_uuid: Source signal UUID.

batch_duration_statistics

batch_duration_statistics() -> pd.DataFrame

Compute duration statistics grouped by batch type (batch_id).

Returns:

Type	Description
DataFrame	DataFrame with columns:
DataFrame	batch_id
DataFrame	count: Number of occurrences of this batch type.
DataFrame	min_duration_seconds
DataFrame	avg_duration_seconds
DataFrame	max_duration_seconds
DataFrame	total_duration_seconds

batch_yield

batch_yield(
    counter_uuid: str,
    *,
    value_column_counter: str = "value_integer",
    handle_resets: bool = True
) -> pd.DataFrame

Compute production quantity for each detected batch.

Uses a monotonic counter signal. With handle_resets=True the reset-aware increments are computed once over the whole counter and each is booked to the batch that was running when it was produced: a reading reports the production since the previous reading, so it belongs to the batch whose ID was last seen strictly before it. A batch therefore owns the counter readings after its first sample up to and including the next batch-ID change, the production between the last sample of one batch and the first sample of the next counts for the earlier batch, and the batch quantities add up to the counter total (readings before the first batch-ID sample, after the last one, or while the batch ID is empty belong to no batch).

Parameters:

Name	Type	Description	Default
counter_uuid	str	UUID of the monotonic part counter.	required
value_column_counter	str	Column holding counter values.	'value_integer'
handle_resets	bool	When True (default), treat a decreasing counter as a reset and count the production after the reset instead of losing it, so quantity is the reset-aware total for the batch. The result gains a resets column with the number of resets observed in each batch. When False, quantity is simply max(0, last - first) of the readings between the batch's first and last sample (0 for fewer than two readings): a batch containing a reset reports too little and production between batches is lost.	True

Returns:

Type	Description
DataFrame	DataFrame with columns:
DataFrame	batch_id
DataFrame	start
DataFrame	end
DataFrame	duration_seconds
DataFrame	quantity: Parts produced during the batch (see above).
DataFrame	uuid
DataFrame	source_uuid
DataFrame	resets (only when handle_resets=True)

batch_transition_matrix

batch_transition_matrix(
    *, layout: Literal["long", "wide"] = "long"
) -> pd.DataFrame

Count which batch follows which.

Parameters:

Name	Type	Description	Default
layout	Literal['long', 'wide']	"long" (default) returns one row per observed transition. "wide" returns the pivoted matrix.	'long'

Returns:

Type	Description
DataFrame	With layout="long", a DataFrame with columns from_state,
DataFrame	to_state and transition_count (int), one row per observed
DataFrame	(from_state, to_state) pair, sorted by from_state and
DataFrame	to_state. With fewer than two batches the result is empty and
DataFrame	keeps these columns.
DataFrame	With layout="wide", a pivot table where index = from_batch,
DataFrame	columns = to_batch, values = transition count, plus a total
DataFrame	column. The batch columns depend on the data, so with fewer than
DataFrame	two batches the result is an empty frame with only the total
DataFrame	column (index named from_batch).

Raises:

Type	Description
ValueError	If layout is not "long" or "wide".