Categorical Rollup Design¶

design_categorical_rollup(...) searches for an exact global grouping of one retained categorical column under saturated Q. It answers a more specific question than column-subset refinement search:

Can we publish a useful rollup of this category instead of either suppressing it completely or exposing every retained level?

The first slice exhaustively evaluates every set partition of the retained category levels up to a declared maximum group count. It returns the smallest budget-feasible grouping that certifies the claim when one exists.

Basic Workflow¶

import updatesupport as us

claim = us.claim(
    "Conversion remains above the reporting floor",
    public=["segment", "region"],
    hidden=["segment", "region", "acquisition_channel", "tenure_band"],
    target="conversion_rate",
    weight="users",
    ambiguity_limit=0.015,
    decision=us.threshold_decision(">=", 0.18),
    q_presets=["saturated"],
)

design = claim.design_categorical_rollup(
    rows,
    column="acquisition_channel",
    max_groups=4,
    bucket_budget=40,
    output_column="acquisition_channel_group",
)

print(design.to_markdown())

The functional spelling is equivalent:

design = us.design_categorical_rollup(
    rows,
    claim,
    column="acquisition_channel",
    max_groups=4,
)

The report includes the selected mapping, ambiguity before and after the rollup, the best grouping for each group count, the Pareto frontier over group count/public cells/ambiguity, claim status, and exact-search metadata.

Exact Saturated Evaluation¶

For a candidate global mapping g(c) from category level c to rollup group, the proposed public representation is:

(base public columns, g(c))

Within each resulting public fiber, saturated Q may place the fiber’s mass on any retained hidden cell in that fiber. Candidate ambiguity is therefore:

sum_(o, group) p(o, group)
    * [max h(d) - min h(d)] over d in that public fiber

The implementation evaluates this closed form directly. It does not launch an LP or CVXPY solve for every grouping.

The category mapping is global: a category belongs to the same rollup group in every base public cell. This produces one reportable schema rather than a different category definition for every segment or region.

Selection Semantics¶

When the claim has an ambiguity limit or decision rule, selection proceeds as follows:

discard candidates that exceed the public-cell budget;
find candidates satisfying the supplied ambiguity and decision requirements;
choose the certifying candidate with the fewest category groups, then the fewest realized public cells, then the smallest ambiguity;
if no candidate certifies the claim, return the lowest-ambiguity budget-feasible candidate and label it as non-certifying.

Without a claim threshold, the selected design minimizes ambiguity within the declared group and public-cell budgets. The frontier remains available when an analyst wants a different complexity/stability tradeoff.

Applying The Design¶

There are three possible outputs:

One group: retain the base public representation.
One group per category: add the original categorical column.
Intermediate rollup: add a generated categorical group column.

Use the report to transform rows or immediately rerun the claim:

transformed = design.transform(rows)
audit = design.audit(rows)

design.recommended_public gives the selected public columns, and design.selected_claim gives the corresponding saturated ClaimSpec.

Applying an intermediate design to a previously unseen category raises an error. New categories are support drift and are not silently assigned to an arbitrary group.

Search Guard¶

The number of set partitions grows by Bell numbers. Exact search therefore has max_categories=9 by default. Nine retained levels produce 21,147 possible partitions before applying max_groups.

Raise max_categories only when that combinatorial cost is acceptable. Larger domains will need a later constrained, dynamic-programming, MIP, or heuristic search mode.

Structured Exports¶

design.to_json()
design.to_tables()
design.to_dataframes()

Named tables include summary, claim, selected_groups, best_by_group_count, frontier, and limitations.

Scope Boundary¶

This feature searches one retained categorical column under saturated Q. It does not yet learn ordered numeric cutpoints, category hierarchies, different groupings by public fiber, or rollups jointly optimized across several columns.