Calibration limits from analyst-selected baseline subset

[cnicholas]

Problem

When an analyst receives a data stream, the beginning (or other portions) may be contaminated — startup effects, process changes, or known disturbances. The analyst needs to pick a homogeneous subset (typically 10-15 points) from somewhere in the series to establish the voice of the process, then evaluate all other points against those calibrated limits.

Currently the library computes limits from the full dataset. There is no way to say "use points 5-20 as the baseline for limit calculation."

Proposed Feature

A study-level calibrate() method that sets a baseline window. All subsequent execute() calls compute CL/LPL/UPL from the baseline subset only, while plotting and evaluating signals across the full series.

API sketch

# By time values (natural for the analyst)
calibrated = study.calibrate(start='202405', end='202418')

# By index position
calibrated = study.calibrate(start_index=5, end_index=20)

# All subsequent charts use calibrated limits
result = calibrated.execute(chart='XmR')  # limits from baseline only

# Reset
uncalibrated = calibrated.calibrate(None)

What calibration changes

• CL, LPL, UPL computed from the calibration subset only
• All points (before, during, and after window) are plotted
• Signal detection uses calibrated limits against the full series
• Visual indication — calibration window shown on chart (shaded region or boundary markers)

What calibration does NOT change

• Residuals (R1-R5) — computed on full data during formulate()
• SDS detection — runs on raw data, unchanged
• Effects — computed on full data

Persistence

Calibration would be stored on the Study alongside capability specs (LSL/USL/Target), saved and restored together.

Open Design Questions

1. Immutable vs mutable

Should calibrate() return a new Study (consistent with frozen dataclass pattern) or mutate in place? Leaning toward new Study for consistency.

2. Scope: study-level vs execute-level

Should calibration be a study-level setting (applies to all execute calls) or an execute-level parameter? Leaning toward study-level — it's a global analytical decision, like spec limits.

3. Stratification semantics

When calibrating stratified charts (e.g., XmR by=[HOME_TEAM]), does the calibration window apply:

• Per-stratum — same index range within each stratum?
• Global — same time range across all strata?

Leaning toward global time window that maps to per-stratum index ranges — the analyst is saying "I trust weeks 5-18" which applies everywhere.

4. Interaction with phased limits

Calibration (analyst-directed baseline) and phased limits (auto-detected phase boundaries) are somewhat at odds. Should they be mutually exclusive, or can you calibrate within a phase?

5. App integration

In processbehavior-app, the analyst would click two points on the chart to set the calibration window. This requires:

• Click-to-select interaction on Plotly charts
• Visual feedback showing the selected baseline region
• Persistence of calibration settings in session state

Use Case

Continuous improvement: the analyst establishes a baseline during a known-good period, then monitors whether subsequent data stays within those limits or shows improvement/deterioration. This is how experienced analysts actually work with process behavior charts — Wheeler's methodology supports this approach.