Collapse Events

Merge consecutive or grouped events into a single representative event.

Exactly one of consecutive, event_groups, group_col, or session_id_col must be provided.

Usage

# Collapse any run of the same event
stream.collapse_events(consecutive=True)

# Collapse only repeated page_view events
stream.collapse_events(consecutive=["page_view"])

# Merge checkout steps into a single "checkout" event
stream.collapse_events(event_groups=[{"events": ["checkout_start", "checkout_step", "checkout_confirm"], "name": "checkout"}])

Parameters

Parameter	Type	Description
`consecutive`	`bool or list of str, optional`	Collapse consecutive repeats of the same event into one. Pass `True` to collapse all events; pass a list of event names to collapse only those specific events.
`event_groups`	`list of dict, optional`	Merge a set of events that belong together into a single representative event. Each group dict must have either an `events` key (list of event names to merge) or a `separator` / `start_event` + `end_event` pair. Additional keys:
`group_col`	`str, optional`	Group consecutive rows by this column's value: each run of rows sharing the same value is collapsed into one event named after that value. Example: a `session_type` column with values `browse, browse, search` collapses the path into `browse -> search` events.
`session_id_col`	`str, optional`	Collapse events within each session defined by this column. Requires `session_type_col` as well.
`session_type_col`	`str, optional`	Column that distinguishes session event types (used with `session_id_col`).
`agg`	`dict, optional`	Aggregation rules for non-event columns when rows are merged, as a `{column: agg_func}` dict. Example: `{"duration": "sum"}`.
`path_col`	`str, optional`	Path ID column override; defaults to `schema.path_col`.
`event_col`	`str, optional`	Event column override; defaults to `schema.event_col`.

Event group keys

name (str) — label for the merged event. Required unless cases are given.
cases (list of dict, optional) — conditional labels: each case is {"condition": <filter_paths-style condition>, "name": <label>}, evaluated against the merged group's own events; the group-level name becomes the fallback label for groups no case matched.