API Surface

updatesupport is organized around claim-first public report design. The main user path is small:

claim = us.claim(
    "reported estimate is stable enough to use",
    public=[...],
    hidden=[...],
    target="metric",
    candidate_refinements=[...],
    ambiguity_limit=0.01,
)

design = claim.design(rows_or_frame)

Core API

The public user-facing surface is:

  • us.claim(...): build a ClaimSpec.

  • ClaimSpec.design(...): audit the claim and design a defensible public representation.

  • us.design_public_report(...): functional equivalent of ClaimSpec.design(...).

  • PublicReportDesign: the report object returned by public-report design.

  • ClaimSpec.audit(...): run the audit.

  • us.audit_claim(...): functional equivalent of ClaimSpec.audit(...).

  • ClaimAudit: the report object returned by an audit.

  • ClaimSpec.calibrate_tv(...): calibrate a TV stress radius from historical period transitions and run rolling one-step backtests.

  • us.calibrate_tv_radius(...): functional equivalent of ClaimSpec.calibrate_tv(...).

  • HistoricalTVCalibrationReport: the calibration, rolling coverage evidence, calibrated Q preset, and current-period audit/design handoff.

  • ClaimSpec.design_categorical_rollup(...): find an exact global grouping of one retained categorical column under saturated Q.

  • us.design_categorical_rollup(...): functional equivalent of the claim method.

  • CategoricalRollupDesign: selected category mapping, group-count tradeoffs, Pareto frontier, structured exports, and transformed-data audit handoff.

  • us.claim_portfolio(...): declare claims that must share one public schema.

  • ClaimPortfolio.design(...): run exact shared representation search.

  • us.design_shared_representation(...): functional equivalent of the portfolio method.

  • SharedRepresentationDesign: selected common schema, per-claim outcomes, shared frontier, best-effort diagnostics, and full claim-audit handoff.

  • ClaimSpec.design_calibrated(...): calibrate historical TV stress and design the current public representation for one claim.

  • ClaimPortfolio.design_calibrated(...): apply the same workflow to one shared public representation across several claims.

  • us.design_calibrated_public_report(...): functional equivalent of the calibrated claim and portfolio methods.

  • CalibratedPublicReportDesign: calibration backtests, optional categorical rollup, selected schema, current audits, nearest breaking witnesses, and structured exports.

  • ClaimSpec.breaking_witness(...): find the closest fixed-public hidden-cell recomposition that fails the claim’s threshold decision.

  • ClaimAudit.breaking_witness(...): reuse an audit’s compiled problem for the same inverse solve.

  • us.minimum_claim_breaking_witness(...): functional equivalent of the claim method.

  • MinimumClaimBreakingWitnessReport: minimum distance, decision-flipping cell law, within-fiber transfer ledger, solver certificate, and exports.

  • ClaimAudit.recommend_refinements(...): claim-centered refinement ranking.

  • ClaimAudit.repair_plan(...): cost-aware action list for stabilizing a claim.

  • us.plan_claim_repair(...): functional helper for scripts; the method form ClaimAudit.repair_plan(...) is the preferred spelling once an audit exists.

  • ClaimRepairPlan: the structured repair-plan report object.

  • us.claim_tree(...): organize related ClaimSpecs into a nested claim tree.

  • us.audit_claim_tree(...): audit a nested claim tree in one call.

  • ClaimTreeAudit: the report object for hierarchical claim reviews.

  • us.threshold_decision(...): add a decision-invariance rule.

  • us.from_dataframe(...): compile rows when you need to inspect the finite problem before auditing.

Public-report design composes the lower-level machinery: claim audit evidence, counterexample witnesses, representation certificates, frontier search, decision-invariant repairs, repair plans, optional refinement attribution, nested claim reports, model-assisted joint draws, structured exports, and limitations.

The package __all__ is intentionally narrower than the set of direct attributes on updatesupport. It is the recommended star-import surface: claim-first workflow, common report functions, Q presets, structured exports, integration adapters, specs, and extension hooks. Diagnostic dataclasses, backend reports, residopt internals, support-function internals, and named linear feasibility objects remain importable directly or from their owning modules, but they are not advertised through from updatesupport import *.

Advanced Evidence Tools

Use these directly only when you intentionally want a lower-level artifact:

  • public_descent_report(...): primary hidden-composition interval evidence.

  • sensitivity_report(...): grid over Q presets, hidden sets, or sparsity thresholds.

  • recommend_refinements(...): one-column ambiguity-reduction screening.

  • recommend_refinement_interactions(...): small interaction-aware refinement search.

  • attribute_refinement_ambiguity(...): Shapley-style attribution of joint ambiguity reduction across candidate refinements.

  • recommend_refinements_sensitivity(...): refinement ranking aggregated over a sensitivity grid.

  • public_representation_frontier(...): public-bucket design frontier.

  • certify_public_representation(...): standalone representation certificate.

  • breakdown_point(...): stress radius where a claim or decision stops passing.

  • minimum_claim_breaking_witness(...): direct inverse solve for the closest threshold-flipping composition in TV, L2, or Mahalanobis geometry.

  • calibrate_tv_radius(...): historical TV-radius calibration and rolling one-step validation.

  • design_categorical_rollup(...): exact restricted partition design for one categorical refinement under saturated Q.

  • design_shared_representation(...): exact common-schema search across several claims with claim-specific targets and stress scenarios.

  • design_calibrated_public_report(...): compose historical TV calibration, optional one-column rollup, single/shared schema search, and direct threshold breaking witnesses.

  • robust_comparison_report(...): robust pairwise/ranking comparison evidence.

These are implementation depth behind the claim workflow. They remain useful for method development, diagnostics, and specialized notebooks, but they should not be the first thing a new analyst has to learn.