ump_spec.rules.plain

module ump-spec

Plain-language fields for a ShownNumber (POC reporting views for non-technical readers).

plain_fields(shown) returns four optional display fields that sit beside the technical ones and never replace them:

• headline: a short plain label, e.g. "Return per $1 on Linear TV";
• range_words: the interval in words, e.g. "likely between $0.60 and $1.87";
• confidence: "high" | "medium" | "low" from the trust level and the interval width;
• why_best_guess: one plain sentence when the number rests on fallbacks, else None.

Confidence rule (proposed, pending the pre-rollout studies, spec §22):

• low when the interval is wide (relative width above 0.70, the proposed WIDTH_CUTS) or the trust level is 1 (taken on trust);
• high when the interval is narrow (relative width at most 0.35), the trust level is 3 or 4 and no fallback was applied;
• medium otherwise.

Pure functions, no I/O beyond the packaged registries. Accepts a ShownNumber or a ShownNumber-shaped dict (apps build loose dicts), and never raises on a malformed input: missing parts give None fields.

Functions

confidence

function

def confidence(shown: Any) -> str | None

high | medium | low (rule in CONFIDENCE_RULE; proposed).

Source: packages/ump-spec/src/ump_spec/rules/plain.py, line 208

fill_plain_fields_deep

function

def fill_plain_fields_deep(obj: Any, *, max_depth: int = 12) -> Any

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.

Source: packages/ump-spec/src/ump_spec/rules/plain.py, line 288

format_value

function

def format_value(v: float, kind: str, *, percent_scale: float = 1.0) -> str

Render one number for range_words. percent_scale is 100 when the values are fractions.

Source: packages/ump-spec/src/ump_spec/rules/plain.py, line 112

headline

function

def headline(shown: Any) -> str | None

Short plain label. Uses the estimand’s unit and channel when it can, else the caption.

Source: packages/ump-spec/src/ump_spec/rules/plain.py, line 139

plain_fields

function

def plain_fields(shown: Any) -> dict[str, Any]

The four plain-language fields for one ShownNumber (or a ShownNumber-shaped dict).

Source: packages/ump-spec/src/ump_spec/rules/plain.py, line 249

range_words

function

def range_words(shown: Any) -> str | None

Source: packages/ump-spec/src/ump_spec/rules/plain.py, line 165

why_best_guess

function

def why_best_guess(shown: Any) -> str | None

One plain sentence when the number rests on fallbacks; None when there are none.

Source: packages/ump-spec/src/ump_spec/rules/plain.py, line 228

with_plain_fields

function

def with_plain_fields(shown: T, *, overwrite: bool = False) -> T

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.

Source: packages/ump-spec/src/ump_spec/rules/plain.py, line 264

Constants

Name	Type	Value	Description
CONFIDENCE_RULE		{'low': 'interval wide (relative width > 0.70) or trust level 1', 'high': 'in...	The confidence rule in words; travels with API responses that publish confidence.
PLAIN_FIELDS		('headline', 'range_words', 'confidence', 'why_best_guess')