collapse_levels

superglm.collapse_levels(

data: Series | NDArray | list[str],

*,

from_level: str | None = None,

below: str | None = None,

groups: dict[str, list[str]] | None = None,

order: list[str] | None = None,

) → LevelGrouping

Build a LevelGrouping from data and grouping rules.

Three modes (mutually exclusive with groups):

• from_level="25" — levels at position >= "25" (in sorted order) collapse to group label "25+".

• below="3" — levels at position < "3" collapse to "<3".

• groups={"South": ["TX", "FL"]} — explicit mapping; unlisted levels are identity-mapped.

from_level and below can be combined, but neither can be mixed with groups.

Parameters:

dataSeries, array, or list of str

The categorical column. Used to discover all unique levels.

from_levelstr or None

Collapse levels at or after this position (inclusive) into a single "<from_level>+" group.

belowstr or None

Collapse levels before this position (exclusive) into a single "<<below>" group.

groupsdict[str, list[str]] or None

Explicit mapping of group labels to lists of original levels.

orderlist[str] or None

Optional explicit level ordering. If not given, levels are sorted lexicographically.

Returns:

LevelGrouping

Raises:

ValueError

If a level appears in multiple groups, if mentioned levels don’t exist in data, or if from_level/below are used with groups.