Retentioneering

Retentioneering is an open-source Python library for understanding user behavior from event logs. Find where users get stuck, compare the paths different groups take, and discover patterns across clicks, sessions and repeat visits. Explore the data yourself or let an AI agent work with the same tools.

Run a demo notebook in Google Colab – no need to install the library locally, sample data included.

Quick start · Use cases · Use an AI agent · Docs

A demo of the interactive features of the transition graph widget. You can highlight a route, compare path groups, focus on the step you want to investigate, and explore incoming and outgoing transition probabilities in the ego view.

Is it for you?

Use Retentioneering when you have a question about the sequence of actions like these:

• A metric changed. Where did journeys change and move the metric?
• Users stop before reaching a goal. What do they do instead and how do successful paths differ?
• You want to understand engagement. What behavior types are represented, and how does usage evolve across visits?
• You need to investigate a flow. Where do checkout, onboarding, support or agent runs loop, branch or stall?

Bring an event-level export from your analytics platform, warehouse or application logs. All you need is a user, session or case ID; an event name; and a timestamp.

Quick start

Python: 3.10 - 3.13.

Environment: Jupyter (Jupyter Notebook, JupyterLab, JupyterLab Desktop), VS Code, Cursor, Google Colab.

To install the library, run

pip install retentioneering

Within a notebook, use %pip install retentioneering instead. See the installation guide for the details.

To try out the library quickly, without loading your own data, you can use a built-in e-commerce dataset:

import retentioneering as rete

stream = rete.datasets.load_ecom()  # bundled synthetic store
stream.transition_graph()

Common use cases

Below are a few examples of how you can apply retentioneering tools to approach common analytical problems on the bundled e-commerce demo dataset. The code chunks assume stream = rete.datasets.load_ecom().

A key metric dropped. Where did journeys change and cause it?

Create a binary segment that cuts each path at the boundaries of the affected period: its events inside the period are labelled inside, the rest outside, so one path can contribute to both parts. Then compare user behavior across these parts with the transition graph widget.

periods = stream.add_segment("period", time_range=("2024-05-19", "2024-06-07"))
periods.transition_graph(diff=("period", "inside", "outside"))