ump_spec.models.calibration

module ump-spec

Calibration record (spec §10): routes R1 to R6, checks 0 to 6, PSIS diagnostics.

Classes

PsisDiagnostics

class

class PsisDiagnostics(StrictModel)

Fields

Name	Type	Default	Description
`khat`	`float`
`ess`	`float`
`n_draws`	`int`
`r_eff`	`float \| None`	`None`	Relative MCMC efficiency of the draws (spec §10); the ESS checked is ess x r_eff. Absent means 1.0.
`khat_threshold`	`Proposed \| None`	`None`
`ess_floor`	`Proposed`	`Proposed(value=400, source='§10')`
`passed`	`bool \| None`	`None`

Methods and properties (1)

evaluate method

def evaluate(self) -> PsisDiagnostics

Source: packages/ump-spec/src/ump_spec/models/calibration.py, line 48

CalibrationCheck

class

class CalibrationCheck(StrictModel)

Fields

Name	Type	Default	Description
`index`	`int`
`sub`	`str \| None`	`None`	Sub-check letter, e.g. ‘a’ for check 2a measurement mapping (§10).
`name`	`str`
`outcome`	`CheckOutcome`
`gate`	`str \| None`	`None`
`detail`	`str`	`''`

Source: packages/ump-spec/src/ump_spec/models/calibration.py, line 67

Excision

class

class Excision(StrictModel)

Fields

Name	Type	Default	Description
`mode`	`ExcisionMode`	`'default_applied'`	not_needed: the flight plus its adstock tail sits outside the training window, so there is nothing to excise (G-CAL-02 passes).
`start`	`str \| None`	`None`
`end_plus_tail`	`str \| None`	`None`
`tail_weeks`	`int \| None`	`None`

Source: packages/ump-spec/src/ump_spec/models/calibration.py, line 78

Conflict

class

class Conflict(StrictModel)

Fields

Name	Type	Default	Description
`z`	`float \| None`	`None`
`p`	`float \| None`	`None`
`bh_flag`	`bool`	`False`
`q`	`Proposed`	`Proposed(value=0.1, source='§10')`
`single_test_flag`	`bool`	`False`
`procedure`	`Literal['abs_z', 'benjamini_hochberg', 'benjamini_yekutieli'] \| None`	`None`	Spec §10: the procedure used (\|z\| rule for m = 1, BH or declared BY).
`m`	`int \| None`	`None`	Number of tests in this calibration artifact.

Source: packages/ump-spec/src/ump_spec/models/calibration.py, line 88

Calibration

class

class Calibration(ArtifactDoc)

Fields

Name	Type	Default	Description
`client_id`	`str \| None`	`None`
`metric_family`	`str \| None`	`None`	Legacy top-level metric family (sales_return, brand_awareness, …); the estimand’s own `metric_family` is preferred. Read by G-EXP-05 (`gates._calibration_target`) and experiments `calibrate.py`.
`model_id_in`	`str`
`model_id_out`	`str \| None`	`None`
`test_result_ids`	`list[str]`	`list()`
`excluded_test_ids`	`list[str]`	`list()`
`channel`	`str \| None`	`None`
`route`	`Route`
`route_attempted`	`list[Route]`	`list()`
`checks`	`list[CalibrationCheck]`	`list()`
`excision`	`Excision`	`Excision()`
`conflict`	`Conflict`	`Conflict()`
`psis`	`PsisDiagnostics \| None`	`None`
`prior`	`ShownNumber \| None`	`None`
`posterior`	`ShownNumber \| None`	`None`
`status`	`Literal['committed', 'provisional']`	`'provisional'`
`approximate`	`bool`	`False`
`refit_queued`	`bool`	`False`
`fallbacks`	`list[FallbackEntry]`	`list()`
`tested_channel`	`str \| None`	`None`	Channel the tests measured. R6 attach-only docs keep `channel` null and put the channel here, so maturity does not count them as calibrated.
`attach_only`	`bool`	`False`	R6: readouts attached beside the model, model unchanged.
`model_tier`	`str \| None`	`None`	Tier (A/B/C/D/X) of model_id_in at calibration time.
`granularity_mapping`	`dict[str, Any] \| None`	`None`	Check 3 (G-CAL-03): test grain to model grain, weights, split assumption.
`prior_for_refit`	`dict[str, Any] \| None`	`None`	R1/R3: prior handed to the next refit, e.g. {mean, sd, scale, from}.
`tests`	`list[dict[str, Any]]`	`list()`	Per-test working: id, channel, class, tau, se, z, p, flag, discounts.
`excluded_reason`	`str \| None`	`None`	Why tests or the calibration were excluded.
`mode`	`str \| None`	`None`	Gate mode the calibration ran under. Written by experiments (`calibrate.py`).
`route_status`	`str \| None`	`None`	Status of the route in words. Written by experiments (`calibrate.py`).
`pilot`	`bool \| None`	`None`	True for a pilot calibration. Written by experiments (`calibrate.py`).
`commit_eligible`	`bool \| None`	`None`	True when the calibrated model may be committed. Written by experiments (`calibrate.py`).
`excision_overlap`	`bool \| None`	`None`	True when the excision window overlaps the training window. Written by experiments (`calibrate.py`).
`measurement_mapping_valid`	`bool \| None`	`None`	True when the test’s measurement maps onto the model’s KPI. Written by experiments (`calibrate.py`).
`refit_queued_planned`	`bool \| None`	`None`	Whether a refit was planned at submission. Written by experiments (`calibrate.py`).
`training_window`	`dict[str, Any] \| None`	`None`	Model training window `{start, end}`. Written by experiments (`calibrate.py`).
`estimand_alignment`	`dict[str, Any] \| None`	`None`	How test and model estimands were aligned (G-EST-02). Written by experiments (`calibrate.py`).
`target_estimand`	`dict[str, Any] \| None`	`None`	Estimand the calibration targets, e.g. a brand metric family. Written by experiments (`calibrate.py`).
`robust_mixture`	`dict[str, Any] \| None`	`None`	Robust mixture prior: experiment weight and the vague component (proposed widths). Written by experiments (`calibrate.py`).
`curve_adjustment`	`dict[str, Any] \| None`	`None`	Curve rescale applied near current spend. Written by experiments (`calibrate.py`).
`assumptions`	`list[Any] \| None`	`None`	Assumed values, each labelled. Written by experiments (`calibrate.py`).
`notes`	`list[dict[str, Any] \| str] \| None`	`None`	Notes (code, severity, gate, message). Written by experiments (`calibrate.py`).

Methods and properties (1)

counts_as_calibrated property

counts_as_calibrated: bool

Spec §10: R6 attaches readouts without changing the model, so it never counts as calibrated.

Source: packages/ump-spec/src/ump_spec/models/calibration.py, line 101

Functions

psis_khat_threshold

function

def psis_khat_threshold(n_draws: int) -> float

§10 (proposed): k-hat < min(1 - 1/log10(S), 0.7).

Source: packages/ump-spec/src/ump_spec/models/calibration.py, line 41

Constants

Name	Type	Value
`Route`		`Literal['R1', 'R2', 'R3', 'R4', 'R5', 'R6']`
`CheckOutcome`		`Literal['pass', 'fallback', 'route', 'exclude_and_continue', 'warn', 'skipped']`
`ExcisionMode`		`Literal['excise', 'joint_model', 'default_applied', 'not_needed']`
`ROUTES`	`dict[str, dict[str, Any]]`	`{'R1': {'name': 'prior', 'needs_tiers': ['A'], 'status': 'Supported'}, 'R2': ...`
`CALIBRATION_CHECKS`	`tuple[str, ...]`	`('double_counting_excision', 'estimand', 'admissibility', 'granularity', 'con...`
`CHECK_GATES`	`dict[int, str \| None]`	`{0: 'G-CAL-02', 1: 'G-EST-02', 2: 'G-EXP-05', 3: 'G-CAL-03', 4: 'G-CAL-01', 5...`