Data Compilation

Tabular data compilers for finite update-support problems.

class updatesupport.data.DataDiagnostic(code, severity, message, count=None, columns=(), public_value=None, hidden_cell=None, details=<factory>)[source]

Bases: object

One data preflight diagnostic emitted before solving.

Parameters:
code: str
severity: str
message: str
count: int | None = None
columns: tuple[str, ...] = ()
public_value: tuple[Hashable, ...] | None = None
hidden_cell: tuple[Hashable, ...] | None = None
details: dict[str, Any]
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.data.DataDiagnostics(rows_seen, total_weight, retained_weight, dropped_weight, hidden_cells, retained_hidden_cells, dropped_hidden_cells, public_cells, singleton_public_fibers, constant_public_fibers, diagnostics=())[source]

Bases: object

Pre-solve diagnostics for a compiled tabular problem.

Parameters:

  • rows_seen (int)

  • total_weight (float)

  • retained_weight (float)

  • dropped_weight (float)

  • hidden_cells (int)

  • retained_hidden_cells (int)

  • dropped_hidden_cells (int)

  • public_cells (int)

  • singleton_public_fibers (int)

  • constant_public_fibers (int)

  • diagnostics (tuple[DataDiagnostic, ...])

rows_seen: int
total_weight: float
retained_weight: float
dropped_weight: float
hidden_cells: int
retained_hidden_cells: int
dropped_hidden_cells: int
public_cells: int
singleton_public_fibers: int
constant_public_fibers: int
diagnostics: tuple[DataDiagnostic, ...] = ()
property dropped_weight_share: float
property warning_count: int
property info_count: int
as_dict()[source]
Return type:

dict[str, Any]

class updatesupport.data.GroupedProblem(problem, public_law, public_columns, hidden_columns, target_column, target_functional, total_weight, cell_weights, q=None, q_name='saturated', q_description='arbitrary reweighting among retained hidden cells inside each observed public cell', diagnostics=None, target_procedure=None, target_procedure_context=None, target_standard_error_column=None)[source]

Bases: object

A finite problem compiled from grouped tabular observations.

Parameters:
problem: FiniteProblem
public_law: dict[tuple[Hashable, ...], float]
public_columns: tuple[str, ...]
hidden_columns: tuple[str, ...]
target_column: str | RowMetric
target_functional: LinearTarget | UncertainLinearTarget | RatioTarget
total_weight: float
cell_weights: dict[tuple[Hashable, ...], float]
q: QPreset | None = None
q_name: str = 'saturated'
q_description: str = 'arbitrary reweighting among retained hidden cells inside each observed public cell'
diagnostics: DataDiagnostics | None = None
target_procedure: ProcedureTarget | None = None
target_procedure_context: ProcedureTargetContext | None = None
target_standard_error_column: str | RowMetric | None = None
to_report(**kwargs)[source]

Build a public-descent evidence report from this compiled problem.

Parameters:

kwargs (Any)

claim(estimate_name, **kwargs)[source]

Create a claim spec using this compiled problem’s metadata.

The returned spec can be verified against the original rows or, for a primary-interval-only audit, against this GroupedProblem. Refinement and repair searches still need the original rows because they recompile alternate public representations.

Parameters:

  • estimate_name (str)

  • kwargs (Any)

support_function_report(targets, **kwargs)[source]

Evaluate named linear directions against this problem’s public law.

Parameters:
updatesupport.data.from_dataframe(data, *, public=None, hidden=None, target=None, target_standard_error=None, weight=None, public_columns=None, hidden_columns=None, target_column=None, target_standard_error_column=None, weight_column=None, min_cell_weight=1.0, q='saturated', q_radius=None, target_confidence_multiplier=1.96)[source]

Compile tabular observations into a finite update-support problem.

data may be a pandas-like dataframe with to_dict("records") or an iterable of row mappings. Each hidden cell receives the weighted empirical mean of target as its estimand value. If target is a ProcedureTarget, the procedure is compiled once for the selected public representation and must return a column name or RowMetric. The returned problem uses an environment built from the selected q preset. The default is q="saturated", which fixes the observed public law and allows arbitrary reweighting inside retained public fibers.

If target_standard_error is supplied, each hidden cell also receives a weighted-mean standard error under independent row-level target estimation errors. The compiled target remains linear in the hidden-cell point estimates, and reports can use the standard errors for estimator-uncertainty-aware interval adjustments.

The *_columns keyword names are accepted as compatibility aliases for public, hidden, target, and weight.

Parameters:
Return type:

GroupedProblem

Metric abstractions for plugin-provided target values.

class updatesupport.metrics.RowMetric(name, func, columns=(), description='')[source]

Bases: object

A row-level metric that can be used as a from_dataframe target.

Domain extensions can return RowMetric objects to keep their domain-specific target logic outside the core package while still compiling to the same finite update-support problem.

Parameters:
name: str
func: Callable[[Mapping[str, Any]], float]
columns: tuple[str, ...] = ()
description: str = ''
evaluate(row)[source]
Parameters:

row (Mapping[str, Any])

Return type:

float

updatesupport.metrics.row_metric(name, func, *, columns=(), description='')[source]

Create a reusable row-level metric for from_dataframe.

Parameters:
Return type:

RowMetric

updatesupport.metrics.target_name(target)[source]

Return the display name for a column or row metric target.

Parameters:

target (str | RowMetric)

Return type:

str

updatesupport.metrics.target_description(target)[source]

Return a human-readable description for a target.

Parameters:

target (str | RowMetric)

Return type:

str

updatesupport.metrics.evaluate_target(row, target, *, get_value)[source]

Evaluate a column target or row metric against one record.

Parameters:
Return type:

float