Historical Calibration

Historical calibration of total-variation recomposition stress tests.

class updatesupport.calibration.HistoricalTVTransition(reference_period, evaluation_period, tv_radius, calibration_eligible, support_compatible, reference_observed_value, recomposed_value, composition_target_change, reference_weight, evaluation_weight, new_hidden_cells=(), missing_reference_public_cells=(), missing_reference_public_mass=0.0, reason='')[source]

Bases: object

One consecutive-period hidden-composition transition.

Parameters:
reference_period: Hashable
evaluation_period: Hashable
tv_radius: float | None
calibration_eligible: bool
support_compatible: bool
reference_observed_value: float
recomposed_value: float | None
composition_target_change: float | None
reference_weight: float
evaluation_weight: float
new_hidden_cells: tuple[tuple[Hashable, ...], ...] = ()
missing_reference_public_cells: tuple[tuple[Hashable, ...], ...] = ()
missing_reference_public_mass: float = 0.0
reason: str = ''
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.calibration.RollingTVBacktest(reference_period, evaluation_period, training_transition_count, calibrated_radius, actual_tv_radius, status, support_compatible, shift_covered, reference_observed_value, recomposed_value, lower, upper, ambiguity, target_covered, ambiguity_limit_met, decision_invariant, decision_certified, reference_decision, realized_decision, realized_decision_matches_reference, reason='')[source]

Bases: object

One rolling one-step TV-radius backtest.

Parameters:

  • reference_period (Hashable)

  • evaluation_period (Hashable)

  • training_transition_count (int)

  • calibrated_radius (float)

  • actual_tv_radius (float | None)

  • status (str)

  • support_compatible (bool)

  • shift_covered (bool | None)

  • reference_observed_value (float)

  • recomposed_value (float | None)

  • lower (float)

  • upper (float)

  • ambiguity (float)

  • target_covered (bool | None)

  • ambiguity_limit_met (bool | None)

  • decision_invariant (bool | None)

  • decision_certified (bool | None)

  • reference_decision (str | None)

  • realized_decision (str | None)

  • realized_decision_matches_reference (bool | None)

  • reason (str)

reference_period: Hashable
evaluation_period: Hashable
training_transition_count: int
calibrated_radius: float
actual_tv_radius: float | None
status: str
support_compatible: bool
shift_covered: bool | None
reference_observed_value: float
recomposed_value: float | None
lower: float
upper: float
ambiguity: float
target_covered: bool | None
ambiguity_limit_met: bool | None
decision_invariant: bool | None
decision_certified: bool | None
reference_decision: str | None
realized_decision: str | None
realized_decision_matches_reference: bool | None
reason: str = ''
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.calibration.HistoricalTVCalibrationReport(claim, period_column, period_order, coverage, min_train_transitions, calibrated_radius, transitions, backtests, backend='cvxpy', solver=None, solver_options=None, title='Historical TV-Radius Calibration', limitations=())[source]

Bases: ReportArtifactMixin

Historical TV-radius calibration with rolling one-step backtests.

Parameters:
claim: ClaimSpec
period_column: str
period_order: tuple[Hashable, ...]
coverage: float
min_train_transitions: int
calibrated_radius: float
transitions: tuple[HistoricalTVTransition, ...]
backtests: tuple[RollingTVBacktest, ...]
backend: str = 'cvxpy'
solver: str | None = None
solver_options: Mapping[str, Any] | None = None
title: str = 'Historical TV-Radius Calibration'
limitations: tuple[str, ...] = ()
property eligible_transition_count: int
property unsupported_transition_count: int
property backtest_count: int
property evaluable_backtest_count: int
property rolling_shift_coverage: float | None
property rolling_target_coverage: float | None
property rolling_decision_preservation: float | None
property q: QPreset

Return the TV preset calibrated on all eligible transitions.

property calibrated_claim: ClaimSpec

Return the source claim with the calibrated TV preset installed.

audit(data, **kwargs)[source]

Audit new data using the calibrated TV radius.

Parameters:
Return type:

ClaimAudit

design(data, **kwargs)[source]

Design a public report using the calibrated TV radius.

Parameters:
Return type:

PublicReportDesign

as_dict()[source]
Return type:

dict[str, Any]

to_tables()[source]
Return type:

dict[str, tuple[dict[str, Any], …]]

to_markdown()[source]
Return type:

str

updatesupport.calibration.calibrate_tv_radius(data, claim, *, period, period_order=None, coverage=0.9, min_train_transitions=3, backend='cvxpy', solver=None, solver_options=None, tolerance=1e-09, title='Historical TV-Radius Calibration')[source]

Calibrate a TV radius from history and run rolling one-step backtests.

The later period’s hidden composition is restandardized to the earlier period’s public law before TV distance is measured. This isolates within-public-cell recomposition from changes in public bucket shares.

Parameters:
Return type:

HistoricalTVCalibrationReport