Eventstream

Eventstream is the central object in retentioneering. It wraps your event data and exposes all widgets and data processors as methods.

Throughout this documentation, stream refers to an Eventstream instance. All code examples assume you have created one as shown below.

Key concepts

Path is the unit of analysis — an ordered sequence of events that all analysis tools (transition graph, step matrix, funnel, path metrics) operate on. What counts as a path is defined by the path_col you choose, not fixed by the library:

• path_col="user_id" — a path is the whole user journey. If you come from Amplitude or Mixpanel, this is the closest match to how those tools group events by user.
• path_col="session_id" — a path is a single session.

Every widget and most data processors accept a path_col override, so the same eventstream can be analysed at user grain and at session grain without rebuilding it — but path_col must be one of the columns declared in path_cols (see schema below); passing any other column raises an error.

path_cols must be listed coarsest grain first: every value of path_cols[i+1] must belong to exactly one value of path_cols[i] (e.g. every session_id belongs to exactly one user_id, so path_cols=["user_id", "session_id"] is correct). This nesting is validated against your data when the Eventstream is created — a schema declared the wrong way round (or a session_id that isn't actually unique per user) raises SchemaConfigError immediately, rather than producing silently-wrong analysis. See ADR-0004 for why.

Need to group by something that isn't a nested grain of your path — a device type, a campaign, an arbitrary cohort? That's not a path_col; use a segment column instead (see below).

Segment is a way to split paths into meaningful groups. A split is defined by a segment column that maps each event to a group: for example, a country column assigns one of the segment levels US, DE, FR to every event of a path. Segments can be static (acquisition channel, user age group, etc.) or dynamic — changing along the path, like weekend/weekday or an evolving user state (new/returning/loyal). Segment columns are declared in the schema (segment_cols) or created with the Add Segment data processor, and drive all segment-aware tools. See the Segments page for the full story.

Creating an Eventstream

By default, Eventstream expects columns named user_id, event, and timestamp. If your data uses different column names, pass a schema.

import pandas as pd
import retentioneering as rete

df = pd.read_csv("events.csv")
stream = rete.Eventstream(df)

You can also pass a CSV path directly:

stream = rete.Eventstream("events.csv")

Expected data format

Each row in your DataFrame represents a single event. At minimum, you need a path identifier column, an event name column, and a timestamp column.

Parameters

Schema

The schema tells retentioneering which columns in your DataFrame correspond to paths, events, timestamps, and segments. Pass it as a dict to the schema parameter.

stream = rete.Eventstream(df, schema={
    "path_cols": ["user_id"],
    "event_cols": ["event"],
    "timestamp_col": "timestamp",
    "segment_cols": ["country", "plan"],
})

Sample dataset

retentioneering ships with a synthetic e-commerce dataset you can use to try the library without your own data. It contains six months of user sessions on a consumer electronics store, with several embedded behavioral patterns designed to showcase the analysis tools.

import retentioneering as rete

stream = rete.datasets.load_ecom()

which is equivalent to:

import retentioneering as rete

df = rete.datasets.load_ecom(as_dataframe=True)
stream = rete.Eventstream(df, schema={
    "path_cols": ["user_id", "session_id"],
    "segment_cols": [
        "platform",
        "acquisition_channel",
        "user_cohort",
        "user_lifecycle",
    ],
})

Inspecting your data

stream.describe() is a quick sanity check on what got loaded: dataset shape, schema, date range, event frequency, and path length/duration statistics.

stream.describe()

Parameters:

• percentiles — percentiles (0-1) reported in path_stats. Default (0.25, 0.5, 0.75, 0.9, 0.99).
• top_events — number of most frequent events to include in event_frequency. Default 20; pass None to include every unique event, unranked and unlimited (e.g. when building a full event rename mapping, where the default cap would silently drop long-tail events).

Returns a dict: