Frozen Public-Report Policies

Frozen out-of-sample validation for calibrated public-report designs.

class updatesupport.policy.FrozenSupportCell(state, public_value, mass)

Bases: object

One retained design-period hidden cell in a frozen claim policy.

Parameters:

• state (tuple[Hashable, ...])

• public_value (tuple[Hashable, ...])

• mass (float)

state: tuple[Hashable, ...]

public_value: tuple[Hashable, ...]

mass: float

as_dict()

Return type:

dict[str, Any]

class updatesupport.policy.FrozenClaimPolicy(claim_index, claim, calibrated_radius, reference_support)

Bases: object

One selected and historically calibrated claim contract.

Parameters:

• claim_index (int)

• claim (ClaimSpec)

• calibrated_radius (float)

• reference_support (tuple[FrozenSupportCell, ...])

claim_index: int

claim: ClaimSpec

calibrated_radius: float

reference_support: tuple[FrozenSupportCell, ...]

property estimate_name: str

property selected_public: tuple[str, ...]

property reference_public_cells: tuple[tuple[Hashable, ...], ...]

property reference_hidden_cells: tuple[tuple[Hashable, ...], ...]

property reference_public_law: dict[tuple[Hashable, ...], float]

property reference_cell_weights: dict[tuple[Hashable, ...], float]

property reference_public_map: dict[tuple[Hashable, ...], tuple[Hashable, ...]]

as_dict()

Return type:

dict[str, Any]

class updatesupport.policy.FrozenSupportDrift(calibrated_radius, actual_tv_radius, support_compatible, within_calibrated_radius, reference_public_cell_count, current_public_cell_count, reference_hidden_cell_count, current_hidden_cell_count, new_public_cells=(), missing_reference_public_cells=(), new_hidden_cells=(), missing_reference_hidden_cells=(), reason='')

Bases: object

Observed composition movement relative to frozen design-period support.

Parameters:

• calibrated_radius (float)

• actual_tv_radius (float | None)

• support_compatible (bool)

• within_calibrated_radius (bool | None)

• reference_public_cell_count (int)

• current_public_cell_count (int)

• reference_hidden_cell_count (int)

• current_hidden_cell_count (int)

• new_public_cells (tuple[tuple[Hashable, ...], ...])

• missing_reference_public_cells (tuple[tuple[Hashable, ...], ...])

• new_hidden_cells (tuple[tuple[Hashable, ...], ...])

• missing_reference_hidden_cells (tuple[tuple[Hashable, ...], ...])

• reason (str)

calibrated_radius: float

actual_tv_radius: float | None

support_compatible: bool

within_calibrated_radius: bool | None

reference_public_cell_count: int

current_public_cell_count: int

reference_hidden_cell_count: int

current_hidden_cell_count: int

new_public_cells: tuple[tuple[Hashable, ...], ...] = ()

missing_reference_public_cells: tuple[tuple[Hashable, ...], ...] = ()

new_hidden_cells: tuple[tuple[Hashable, ...], ...] = ()

missing_reference_hidden_cells: tuple[tuple[Hashable, ...], ...] = ()

reason: str = ''

property status: str

property public_cell_change: int

property hidden_cell_change: int

as_dict()

Return type:

dict[str, Any]

class updatesupport.policy.FrozenPolicyClaimResult(policy_claim, drift, audit=None, breaking_witness=None)

Bases: object

One frozen claim evaluated on one future batch.

Parameters:

• policy_claim (FrozenClaimPolicy)

• drift (FrozenSupportDrift)

• audit (ClaimAudit | None)

• breaking_witness (MinimumClaimBreakingWitnessReport | None)

policy_claim: FrozenClaimPolicy

drift: FrozenSupportDrift

audit: ClaimAudit | None = None

breaking_witness: MinimumClaimBreakingWitnessReport | None = None

property claim_index: int

property estimate_name: str

property status: str

property certified: bool

property breaking_tv_distance: float | None

property breaking_radius_multiple: float | None

as_dict()

Return type:

dict[str, Any]

table_row()

Return type:

dict[str, Any]

class updatesupport.policy.FrozenPolicyAudit(policy_name, policy_fingerprint, period, row_count, claim_results, unseen_rollup_categories=(), transform_error=None, title='Frozen Public-Report Policy Audit', limitations=())

Bases: ReportArtifactMixin

One future batch evaluated under a frozen public-report policy.

Parameters:

• policy_name (str)

• policy_fingerprint (str)

• period (Hashable | None)

• row_count (int)

• claim_results (tuple[FrozenPolicyClaimResult, ...])

• unseen_rollup_categories (tuple[Hashable, ...])

• transform_error (str | None)

• title (str)

• limitations (tuple[str, ...])

policy_name: str

policy_fingerprint: str

period: Hashable | None

row_count: int

claim_results: tuple[FrozenPolicyClaimResult, ...]

unseen_rollup_categories: tuple[Hashable, ...] = ()

transform_error: str | None = None

title: str = 'Frozen Public-Report Policy Audit'

limitations: tuple[str, ...] = ()

property status: str

property claim_count: int

property pass_count: int

property review_count: int

property inconclusive_count: int

property support_compatible: bool

property radius_breach_count: int

as_dict()

Return type:

dict[str, Any]

to_tables()

Return type:

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

to_markdown()

Return type:

str

class updatesupport.policy.FrozenPolicyBacktest(policy_name, policy_fingerprint, period_column, period_order, audits, title='Frozen Public-Report Policy Backtest', limitations=())

Bases: ReportArtifactMixin

Ordered holdout-period evaluation of one frozen policy.

Parameters:

• policy_name (str)

• policy_fingerprint (str)

• period_column (str)

• period_order (tuple[Hashable, ...])

• audits (tuple[FrozenPolicyAudit, ...])

• title (str)

• limitations (tuple[str, ...])

policy_name: str

policy_fingerprint: str

period_column: str

period_order: tuple[Hashable, ...]

audits: tuple[FrozenPolicyAudit, ...]

title: str = 'Frozen Public-Report Policy Backtest'

limitations: tuple[str, ...] = ()

property period_count: int

property pass_count: int

property review_count: int

property inconclusive_count: int

property pass_rate: float

property support_compatibility_rate: float

property claim_evaluation_count: int

property claim_pass_rate: float

property radius_breach_count: int

as_dict()

Return type:

dict[str, Any]

to_tables()

Return type:

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

to_markdown()

Return type:

str

class updatesupport.policy.FrozenPublicReportPolicy(name, source_design_status, source_period_column, coverage, historical_row_count, design_row_count, recommended_public, claims, rollup=None, title='Frozen Public-Report Policy', limitations=())

Bases: ReportArtifactMixin

Immutable reporting contract derived from a calibrated design.

Parameters:

• name (str)

• source_design_status (str)

• source_period_column (str)

• coverage (float)

• historical_row_count (int)

• design_row_count (int)

• recommended_public (tuple[str, ...])

• claims (tuple[FrozenClaimPolicy, ...])

• rollup (CategoricalRollupDesign | None)

• title (str)

• limitations (tuple[str, ...])

name: str

source_design_status: str

source_period_column: str

coverage: float

historical_row_count: int

design_row_count: int

recommended_public: tuple[str, ...]

claims: tuple[FrozenClaimPolicy, ...]

rollup: CategoricalRollupDesign | None = None

title: str = 'Frozen Public-Report Policy'

limitations: tuple[str, ...] = ()

classmethod from_design(design, *, require_certified=True, title='Frozen Public-Report Policy')

Freeze a calibrated design without refitting any component.

Parameters:

• design (CalibratedPublicReportDesign)

• require_certified (bool)

• title (str)

Return type:

FrozenPublicReportPolicy

property fingerprint: str

to_dict()

Return a versioned, reloadable policy with a validated portable contract.

Version 1 supports column targets, built-in Q presets with JSON-compatible settings, and JSON scalar or tuple categories. as_dict() remains the descriptive report export for policies containing custom Python objects.

Return type:

dict[str, Any]

to_json(**kwargs)

Serialize the portable policy; executable Python targets are rejected.

Parameters:

kwargs (Any)

Return type:

str

classmethod from_dict(payload)

Restore a versioned policy and verify its contract and fingerprint.

Parameters:

payload (Mapping[str, Any])

Return type:

FrozenPublicReportPolicy

classmethod from_json(text)

Restore a policy without calibration, schema search, or solver calls.

Parameters:

text (str)

Return type:

FrozenPublicReportPolicy

save(path)

Write a portable policy as UTF-8 JSON.

Parameters:

path (str | Path)

Return type:

None

classmethod load(path)

Load and validate a UTF-8 policy JSON file.

Parameters:

path (str | Path)

Return type:

FrozenPublicReportPolicy

audit(data, *, period=None, include_breaking_witness=True, threshold_margin=1e-08, title='Frozen Public-Report Policy Audit')

Evaluate one future batch without refitting the frozen policy.

Parameters:

• data (Any)

• period (Hashable | None)

• include_breaking_witness (bool)

• threshold_margin (float)

• title (str)

Return type:

FrozenPolicyAudit

backtest(data, *, period, period_order=None, include_breaking_witness=False, threshold_margin=1e-08, title='Frozen Public-Report Policy Backtest')

Apply the unchanged policy to ordered holdout periods.

Parameters:

• data (Any)

• period (str)

• period_order (Sequence[Hashable] | None)

• include_breaking_witness (bool)

• threshold_margin (float)

• title (str)

Return type:

FrozenPolicyBacktest

as_dict()

Return type:

dict[str, Any]

to_tables()

Return type:

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

to_markdown()

Return type:

str