golden_batch

golden_batch ¤

Golden-batch deviation: compare new batch trajectories to a reference.

In batch process development a golden batch is a canonical run whose trajectory delivered the target product. Comparing later batches to that trajectory -- per timestep, per phase, or as a whole-trajectory shape distance -- is a workhorse diagnostic in pharma, food, and specialty chemicals.

This detector supports three comparison modes:

pointwise -- resample both batches to a common normalised batch time and report the maximum signed residual.
area -- numerical integral of the absolute residual using the trapezoid rule. Captures cumulative deviation.
dtw -- pure-numpy dynamic time warping distance with a Sakoe -Chiba band. Captures trajectory shape even when batches run at different paces. No external DTW library required.

GoldenBatchDeviationEvents ¤

GoldenBatchDeviationEvents(
    reference_df: DataFrame,
    signal_uuid: str,
    *,
    event_uuid: str = "dev:golden_batch_deviation",
    value_column: str = "value_double",
    time_column: str = "systime",
    n_resample: int = 256
)

Bases: Base

Quantify deviation of a new batch from a golden reference batch.

compare ¤

compare(
    batch_df: DataFrame,
    *,
    mode: str = "pointwise",
    dtw_band_frac: float = 0.1
) -> pd.DataFrame

Compare a single new batch to the stored golden reference.

Parameters:

Name	Type	Description	Default
`batch_df`	`DataFrame`	Long-form DataFrame containing the candidate batch's signal. The configured `signal_uuid` is used to extract the trace.	required
`mode`	`str`	`"pointwise"`, `"area"`, or `"dtw"`.	`'pointwise'`
`dtw_band_frac`	`float`	Sakoe-Chiba band width as a fraction of the resampled grid length. Only used for `mode="dtw"`.	`0.1`

Returns:

Type	Description
`DataFrame`	Interval-shape DataFrame with one row, columns: `start`,
`DataFrame`	`end`, `duration_seconds`, `uuid`, `mode`,
`DataFrame`	`deviation_score`, `max_abs_residual`,
`DataFrame`	`batch_time_at_max`.

phase_breakdown ¤

phase_breakdown(
    batch_df: DataFrame,
    phase_df: DataFrame,
    *,
    phase_uuid: str
) -> pd.DataFrame

Per-phase deviation of a batch against the golden reference.

The reference batch is sliced into phases by the same boundaries applied to the candidate batch -- this assumes the phase sequence is consistent across runs, which is true for recipes that are executed phase-by-phase under recipe control.

Parameters:

Name	Type	Description	Default
`batch_df`	`DataFrame`	Long-form signal DataFrame for the candidate batch.	required
`phase_df`	`DataFrame`	Long-form DataFrame containing the phase-tracking signal, where `value_string` (or the configured value column) carries the phase name.	required
`phase_uuid`	`str`	UUID of the phase signal in `phase_df`.	required

Returns:

Type	Description
`DataFrame`	Summary DataFrame: `start`, `end`, `duration_seconds`,
`DataFrame`	`phase`, `deviation_score`, `max_abs_residual`.