Retentioneering Documentation

In Retentioneering, segmentation is the mechanism used to slice an eventstream into comparable groups. Unlike tools that define a single group of users, a segment in Retentioneering is a segment column that maps each event to a group (e.g., a country column splits the stream into US, DE, FR, etc.).

Segments are categorized into two types:

• Static Segments: The value is constant for the entire path (e.g., acquisition_channel, cluster_label, or the deepest funnel step reached). These answer "which paths behave differently?".
• Dynamic Segments: The value can change along a single path (e.g., weekend vs weekday, or inside vs outside an incident window). These answer "which parts of a path behave differently?".

Segment-aware tools like Segment Overview can split paths into within-segment fragments, allowing you to compare behavior within a specific time window against behavior outside of it for the same user.

stream = Eventstream(df, schema={
    "segment_cols": ["country", "plan"],
})

When analyzing data in Retentioneering, it is critical to distinguish between the unit of analysis (path) and cross-cutting breakdowns (segments).

The Path

• A path is the unit of analysis (e.g., a user journey, a session, or a specific fragment).
• The path is defined by the path_cols hierarchy.
• While tools allow a path_col override to analyze at different grains (e.g., switching from user-level to session-level), the chosen column must be one of the columns defined in the path_cols hierarchy.
• Using a column outside of path_cols as a path will raise an error.

Segments

• A segment is defined by a segment column (e.g., device_type, campaign_id).
• Segments can be static (one value per path) or dynamic (the value changes along the path).
• Best Practice: If you want to perform a cross-cutting breakdown (e.g., comparing how 'Mobile' users behave vs 'Desktop' users), do not try to use device_type as a path_col. Instead, use segment_cols or the diff functionality.

Retentioneering uses a docstring-driven documentation pipeline where code docstrings serve as the single source of truth for reference material. This ensures consistency across the documentation website, Python's help() function, and LLM agents (via the MCP server).

Key Components:

• Reference Docs: Rendered from Eventstream docstrings using Jinja templates located in docs/templates/. The docstring provides the summary, parameters, and runnable examples, while templates handle the layout.
• Conceptual Guides: Hand-written markdown files in docs/guide/*.md (e.g., Quick Start, Eventstream guide) are copied directly to the build.
• Widget Demos: Live widget demos are generated by docs/scripts/generate_widget_demos.py. These use the <DemoWidget cmd={...}> tag in templates, which executes against a bundled dataset and exports via export_html() to ensure examples are always functional code.
• Figures/Images: Hand-written SVGs are stored in docs/img/ and referenced in markdown using the path /docs-demos/img/<name>.svg. The system automatically renders markdown images as centered <figure> elements with the image title as the <figcaption>.

Most path analysis questions are comparative (e.g., comparing an A/B test arm, a platform, or a time window). You can define these groups as a segment. When a widget is used with two segments, it enters diff mode, rendering the difference (group1 − group2) instead of the absolute numbers for a single group.

Common use cases for diffing include:

• Anomalous periods: Using a dynamic segment to split an eventstream into "inside the window" and "outside" to see which transitions degraded.
• Funnel progression: Using add_segment(..., funnel_events=[...]) to label paths by the deepest funnel level completed, allowing you to compare users who "stalled" against those who "converted".
• User lifecycle stages: Using split_sessions to number sessions and creating segments based on that number (e.g., "first session" vs "experienced user") to compare the same people at different stages of their lifetime.

If you have many segment levels (e.g., dozens of countries), use the Segment Overview widget to view metrics in a heatmap across all levels before choosing a specific pair to diff.

# Example concept: labeling paths by funnel depth to enable comparison
# (Refer to recipes for specific implementation details)
stream = stream.add_segment(..., funnel_events=[event1, event2, event3])