ump_spec.rules

module ump-spec

Pure rule functions (no I/O). Import from here: from ump_spec.rules import compare_estimands.

Modules

Module	What it holds
`ump_spec.rules.benchmark`	Benchmark pooling maths (spec §25.3 rule 4) and the benchmark parameters registry (spec §21).
`ump_spec.rules.contract`	Check new input against a workflow’s `InputContract` (feature workflow-bundles S3).
`ump_spec.rules.data`	Rules for the data catalogue and connections (POC blueprint DATA-CATALOGUE §2, §4, §6). Pure functions.
`ump_spec.rules.dependence`	Dependence envelope for portfolio sums (G-DEP-01) and aggregation rules (G-UNC-01).
`ump_spec.rules.estimands`	Estimand rules (spec §5): canonical form, compare, align ladder (G-EST-02), fill undeclared with the rule 4 envelope (G-EST-01), plain words.
`ump_spec.rules.experiments`	Experiment rules that several gates and apps share (spec §9, §10, §25.10).
`ump_spec.rules.governance`	Materiality (G-MAT-01), maturity score and stages (§25.5), Benjamini-Hochberg (§10), conflict z (EMA §6.6), evidence ageing / use-by (§9, EMA §7).
`ump_spec.rules.intervals`	Interval helpers: envelopes, widening, width labels, imputed bands, audit level min (G-AUD-01).
`ump_spec.rules.ladder`	Fallback ladder (spec §8) and the tier x operation matrix.
`ump_spec.rules.plain`	Plain-language fields for a ShownNumber (POC reporting views for non-technical readers).
`ump_spec.rules.recipes`	Transform recipes on the catalogue side (POC blueprint TRANSFORM-RECIPES §6 and §7). Pure functions.

Re-exports

Documented on the page of the module that defines them.

Name	Kind	Summary
`AGGREGATION_RULES`	constant	Quantiles never sum: `bounds_only` means a sum is reported as dependence bounds (G-UNC-01).
`ALIGN_LADDER`	constant
`BH_Q_DEFAULT`	constant	§10 proposed.
`CONFIDENCE_RULE`	constant	The confidence rule in words; travels with API responses that publish `confidence`.
`CONVERTERS`	constant
`DEFAULT_MIN_SEGMENT`	constant	Floor used when neither the policy nor the contract sets one (ContractTerms default, G-PRIV-01).
`LADDER`	constant	1 full model, 2 curve params, 3 spend table, 4 summary (warned), 5 benchmarks (warned), 6 not available.
`MATURITY_WEIGHTS`	constant	§25.5 weights: placeholders for the measurement lead to set (treat as proposed).
`PLAIN_FIELDS`	constant
`REFIT_CODES`	constant	Note codes that send a score to refit.
`STAGE_NAMES`	constant
`STAGE_ORDER`	constant
`TIER_OPS`	constant	Spec §8 tier x operation matrix.
`TIER_TO_STEP`	constant
`TIME_DTYPE`	constant	The dtype the time column is cast to.
`WARNED_STEPS`	constant
`WIDTH_CUTS`	constant	Relative width cut points, proposed (UI convention, not from a study).
`AlignmentResult`	class	`rule` is the spec §5 combination rule used (`1`, `2.1` to `2.4`); `resummary` marks the rule 2.2 re-summary of draws; `scope` is the comparison’s scope relation.
`AuditLevel`	constant	§13: 4 exact rerun, 3 close rerun, 2 logged, 1 taken on trust.
`ChannelEstimate`	class
`DependenceEnvelope`	class
`Estimand`	class	The seven fields plus `applies_to` and the registered optional members. `None` (written `"undeclared"`) means undeclared.
`EstimandComparison`	class	`combinable` only when every canonical field is declared and equal, the scopes are equal and both sides share one orientation (rule 1). `scope` is `contained` when one geo set strictly contains the other (aligned, not equal); `sign_flip` when one side is in the reverse orientation.
`FallbackEntry`	class	§19 fallback note. `effect` says how the interval changed, in plain words.
`Interval`	class
`LadderDecision`	class
`MaterialityResult`	class
`MaturityResult`	class
`Note`	class	Informational or warning note (e.g. `ENGINE_STUB`, `NOT_IMPLEMENTED_IN_POC`).
`ShownNumber`	class	The display contract: a value can only be shown with its interval, estimand and trust labels.
`access_plain_words`	function	One sentence for the catalogue, e.g. “No copies kept (read for each run, then dropped); allowed for fit, score and side modelling.”.
`align`	function	G-EST-02 ladder on the canonical forms: converter -> re-ask the model (or, when both sides carry draws and only `point_rule` or `interval` differ, a re-summary of the draws: rule 2.2, no widening) -> assumed alignment with envelope widening -> side by side. Records the step used. A reverse orientation is the `orientation_sign_flip` converter step. A strict geo containment is aligned, not equal: `ESTIMAND_ALIGNED` and the representativeness check. `candidate_intervals` (one per plausible alignment) gives the envelope for an assumed alignment. A `remove_all` vs `marginal` intervention mismatch (ROI vs mROI) is never assumed away: it goes side by side. Strict mode raises `ESTIMAND_ALIGNED` (409) for any rung after the converter.
`allowed_aggregations`	function
`as_audit_level`	function	Narrow an int to `AuditLevel` (raises `ValueError` outside 1..4), for typed callers.
`assess_maturity`	function
`audit_level_min`	function	G-AUD-01: an artifact’s audit level is the lowest of its inputs (1 if no inputs known).
`benjamini_hochberg`	function	Return a reject/flag decision per p-value (same order) controlling FDR at `q`.
`canonical_rows_fingerprint`	function	sha256 hex of `canonical_json({"columns": [...], "rows": [[...], ...]})` over a canonical layout.
`carryover_floor_weeks`	function	EMA Eq. 17: k_min = ceil(ln(threshold)/ln(alpha)), clamped to [1, 26].
`check_aggregation`	function	Return the rule for `op` or raise `UNCERTAINTY_IMPUTED`-family problems when not allowed.
`check_input`	function	Check a frame’s profile against `contract`; see the module docstring for the rules and their order.
`check_use`	function	Raise when the read is not allowed; return the effective policy when it is.
`choose_ladder_step`	function	Pick the highest rung available. `available` holds ladder steps or tiers (A/B/C/D/X). `excluded` removes rungs (e.g. a model that failed the acceptance bar, G-ACC-01).
`comonotone_sum`	function	Perfectly correlated channels: lower quantiles add, upper quantiles add.
`compare_estimands`	function	Compare two estimands in canonical form (spec §5). Undeclared fields count as mismatched and are also listed in `undeclared`. A strict geo containment is reported in `scope`, not `mismatched`.
`conflict_z`	function	EMA §6.6: z = \|tau_hat - mu0\| / sqrt(sigma0^2 + se_exp^2); returns (z, two-sided p).
`dependence_envelope`	function	Sum channel estimates under the declared dependence (spec §7 table).
`effective_access`	function	The policy that governs a read. A stored dataset without its own policy is `allowed` (the client sent the file); a connected one defaults to `transient_only`. Retention and the minimum segment size fall back to the contract (`retention_days`), then to `DEFAULT_MIN_SEGMENT`. The minimum segment size is the stricter (larger) of the policy’s and the contract’s when a contract is known (G-PRIV-01).
`envelope`	function	Smallest interval covering every input (used for assumed alignments and dependence). `level` is the declared level to report (spec §5 rule 4: the envelope keeps the declared level); without it the highest input level is reported.
`fill_plain_fields_deep`	function	Walk a JSON-like structure and add plain fields to every ShownNumber-shaped dict in it (copying containers). For reporting endpoints that return nested views.
`fill_undeclared`	function	G-EST-01 under spec §5 rule 4. Each undeclared field takes the registered default for the source type and is marked `assumed`; a field with no registered default stays undeclared and goes side by side (there are no global defaults). The interval:
`fingerprints_differ`	function	True when both are known and differ (`sha256:` prefixes ignored). Unknown is never drift.
`freq_days`	function	Days per step for the frequencies the continuity check understands (`W`, `W-<DAY>`, `D`), else None.
`impute_band`	function	G-UNC-01 imputation: from the library spread (sd on the value scale) if known, else a proposed tier-default relative band.
`independent_sum`	function	Independence, normal approximation per side (keeps skew: lower and upper half-widths are combined separately in quadrature).
`input_key`	function	The columns that identify a row: the contract’s key, or the time column plus the categorical dims.
`materiality_tier`	function	G-MAT-01 (computed). Thresholds are per account and proposed.
`maturity_score`	function	0..100 = 25 x freshness (1 if refit <= 90d, 0.5 if <= 180d, 0.2 if older, 0 if no model) + 25 x min(tests/4, 1) + 30 x share of channels calibrated + 20 x causal share of spend.
`maturity_stage`	function	Stages are independent flags; the headline stage is the furthest one reached.
`normalise_query`	function	The identity a clean-room release is recorded under for the G-PRIV-03 overlap check: whitespace collapsed and case folded, so `"buyers_q3 "` and `"Buyers_Q3"` are the same query.
`plain_fields`	function	The four plain-language fields for one ShownNumber (or a ShownNumber-shaped dict).
`plain_words`	function	Render the estimand in plain words, naming every assumed or undeclared field (§5 rule 5). Example: “revenue per dollar from removing all spend versus zero spend (assumed; the source did not say), total including carryover, posterior median, 90% eti”.
`precision_weighted_update`	function	EMA Eq. 2 (G-CAL-05 fallback): posterior mean and sd of a normal-normal update.
`reallocation_arms`	function	`(sources, destinations)` when the intervention uses the `from:`/`to:` arm convention.
`reallocation_intervention`	function	How to express a budget shift between channels without a fifth intervention type.
`relative_width`	function
`tier_supports`	function
`use_by_date`	function	Date at which variance inflation reaches k (t = h log2 k).
`variance_inflation`	function	sigma_eff^2 / sigma_post^2 = exp(lambda t), lambda = ln 2 / h.
`widen`	function	Scale each side’s distance from `center` (default midpoint) by `factor`.
`widen_beyond`	function	G-SCN-03: interval doubled beyond seen spend (around the point value).
`width_label`	function	narrow (<= .35), moderate (<= .70), wide; relative to \|value\|. Cut points proposed.
`with_plain_fields`	function	Return `shown` with the plain fields filled in. Dicts are copied (existing values kept unless `overwrite`); a `ShownNumber` model gets a `model_copy(update=...)`. Anything else comes back unchanged. Safe on any input.
`z_for_level`	function

Functions

find_secret_fields

function

def find_secret_fields(
    obj: Any,
    ptr: str = '',
    *,
    name_maps: frozenset[str] | set[str] = frozenset(),
) -> list[str]

JSON pointers of every value that looks like a secret held in clear. Empty means clean.

name_maps names keys whose object value maps names to values (a recipe’s columns: column name to dtype). Inside such a map the key-name rule is skipped, so a column called cookie or pass is not a secret; the shape rules still run on its keys and values.

Source: packages/ump-spec/src/ump_spec/secrets.py, line 93

redact_secrets

function

def redact_secrets(obj: Any) -> Any

A copy of obj with every value find_secret_fields would flag replaced by [redacted]. Use it before logging or returning connector config or a request spec.

Source: packages/ump-spec/src/ump_spec/secrets.py, line 132

shown_number

function

def shown_number(
    value: float,
    lo: float,
    hi: float,
    estimand: Estimand | dict[str, Any],
    *,
    level: float | None = None,
    label: str | None = None,
    trust_level: int = 2,
    audit_level: int = 2,
    fallbacks: list[FallbackEntry] | None = None,
    notes: list[Note] | None = None,
    artifact_id: str | None = None,
    unit_label: str | None = None,
) -> ShownNumber

Build a ShownNumber with plain words and the (proposed) width label filled in. level defaults to the estimand’s interval level.

Source: packages/ump-spec/src/ump_spec/rules/__init__.py, line 89