pytyche.calibrate.layered

Layered calibration deployment primitive — R(p) below ceiling, scale-family above.

The deployment path does NOT read the fitted c parameter; c is persisted only for the matplotlib diagnostic plot. The past-ceiling regime anchors on the SBC-measured pair (max_recorded_nominal, max_recorded_actual) and scales per-test-point empirical anchor quantiles by the Gaussian z-score ratio. This preserves the per-point asymmetry of hurdle CATEs that a fully-Gaussian-σ inflation would average away.

Functions

apply_layered_calibration(result, ...)

Apply a fitted layered calibration to posterior CATE draws.

Classes

CalibratedIntervals(lower, upper, ...)	Per-test-point calibrated intervals + provenance.
CoverageCorrection(x_thresholds, y_values)	Frozen view of a serialized R(p) isotonic correction.
LayeredCalibrationCorrection(mode, ...)	Discriminated container for a fitted layered SBC correction.
ScaleFamilyCorrection(c, ...)	Frozen view of a fitted scale-family correction.

class pytyche.calibrate.layered.CoverageCorrection(x_thresholds, y_values)

Bases: object

Frozen view of a serialized R(p) isotonic correction.

Mirrors the coverage_correction.json schema produced by scripts/fit_sbc_correction.py: a pair of monotone arrays defining the isotonic step function nominal → actual.

Parameters:

• x_thresholds (tuple[float, ...])

• y_values (tuple[float, ...])

class pytyche.calibrate.layered.ScaleFamilyCorrection(c, max_recorded_nominal, max_recorded_actual, fit_method, n_points_fit)

Bases: object

Frozen view of a fitted scale-family correction.

c is the Gaussian-scale LSQ fit, persisted for diagnostic-plot rendering only. apply_layered_calibration() deploys against the empirical anchor (max_recorded_nominal, max_recorded_actual).

Parameters:

• c (float)

• max_recorded_nominal (float)

• max_recorded_actual (float)

• fit_method (str)

• n_points_fit (int)

class pytyche.calibrate.layered.CalibratedIntervals(lower, upper, desired_coverage, achieved_actual_coverage, method, applied_corrections)

Bases: object

Per-test-point calibrated intervals + provenance.

Returned by apply_layered_calibration(). method records which regime fired ("r_of_p" or "scale_family"); applied_corrections carries regime-specific provenance keys.

Parameters:

• lower (ndarray)

• upper (ndarray)

• desired_coverage (float)

• achieved_actual_coverage (float | None)

• method (Literal['r_of_p', 'scale_family'])

• applied_corrections (dict)

class pytyche.calibrate.layered.LayeredCalibrationCorrection(mode, coverage_correction, scale_family)

Bases: object

Discriminated container for a fitted layered SBC correction.

The mode field selects which deployment regimes are supported:

• "layered": both R(p) (below ceiling) and scale-family (past ceiling) regimes available. scale_family MUST be non-None.

• "r_of_p_only": only R(p) is available. Past-ceiling deployment raises rather than silently degrading. scale_family MUST be None.

The construction-time invariant is validated in __post_init__ and at load time by from_directory(). No silent fallback: a caller wanting r_of_p_only semantics on a sweep that DOES have a scale-family file must pass mode="r_of_p_only" explicitly and will see a UserWarning noting the ignored file.

Parameters:

• mode (Literal['layered', 'r_of_p_only'])

• coverage_correction (CoverageCorrection)

• scale_family (ScaleFamilyCorrection | None)

classmethod from_directory(path, *, mode)

Load a correction pair from a directory.

Parameters:

• path (str | Path) – Directory containing coverage_correction.json and, for layered mode, scale_family_correction.json.

• mode (Literal['layered', 'r_of_p_only']) – Explicit deployment mode. No default; the caller must declare their intent at the call site rather than receive silent fallback.

Returns:

Loaded correction with typed inner dataclasses.

Return type:

LayeredCalibrationCorrection

Raises:

FileNotFoundError – If a required JSON file is missing for the requested mode. The message names the missing file.

Warns:

UserWarning – If mode == "r_of_p_only" and scale_family_correction.json is present in the directory — the file is being ignored due to the explicit mode choice (visible signal, not silent).

pytyche.calibrate.layered.apply_layered_calibration(result, correction, desired_coverage)

Apply a fitted layered calibration to posterior CATE draws.

Stateless: does not mutate result. Reads only result.rpv_cate_samples (shape (n, S)) — the per-test-point posterior draws produced by a joint hurdle BCF fit.

Regime selection (hard boundary, no smoothing — see spec “hard boundary switch with no smoothing”):

• desired_coverage <= ceiling → R(p) regime: invert the isotonic curve to find nominal n* such that R(n*) == desired_coverage, then return the symmetric (1-n*)/2 / 1-(1-n*)/2 quantile pair on the per-test-point draws.

• desired_coverage > ceiling → scale-family regime: anchor on the empirical (q_low, q_high) at max_recorded_nominal and inflate both half-widths around the per-point posterior mean by the Gaussian z-score ratio s. This preserves per-point empirical asymmetry that a fully-Gaussian-σ inflation would average away.

The ceiling is correction.scale_family.max_recorded_actual for layered mode and max(correction.coverage_correction.y_values) for r_of_p_only mode.

Parameters:

• result (_HasCateDraws) – Fit result providing rpv_cate_samples: ndarray[(n, S)].

• correction (LayeredCalibrationCorrection) – Fitted layered calibration loaded via LayeredCalibrationCorrection.from_directory().

• desired_coverage (float) – Requested coverage level in the open interval (0, 1).

Returns:

Calibrated per-test-point endpoints plus provenance.

Return type:

CalibratedIntervals

Raises:

ValueError – If desired_coverage is outside (0, 1). If correction.mode == "r_of_p_only" and desired_coverage exceeds the R(p) ceiling — past-ceiling calibration requires a scale-family correction.