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 normalized 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, expressed in normalized batch time (the same 0..1 axis compare uses): a phase spanning the fraction [a, b] of the candidate batch (first to last candidate sample) is compared against the fraction [a, b] of the golden batch. Both slices are resampled to n_resample points. This assumes the phase sequence and relative phase lengths are 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`.