Step Sankey

Displays a step-by-step Sankey diagram showing which events users experience at each ordinal position in their path. The horizontal axis represents step number, making it easy to see how paths diverge over time.

Each column shows the share of paths at that step position — the values in each column sum to 1. In diff mode, columns show the difference between the two groups, so values sum to 0.

Step Sankey and Step Matrix visualise the same underlying data — es.step_sankey_data() — in different forms: Step Sankey as a flow diagram, Step Matrix as a heatmap table. Use whichever makes the pattern you are looking for easier to spot.

Usage

es.step_sankey()

With options:

es.step_sankey(
    max_steps=15,
    path_pattern="path_start->.*->purchase->.*->path_end",
    diff=["country", "US", "<OUTER>"],
)

Parameters

Parameter	Type	Default	Description
`max_steps`	`int`	`10`	Maximum number of path steps to compute.
`step_window`	`int`	`3`	Number of columns shown around each anchor step. Can also be adjusted interactively in the sidebar.
`path_pattern`	`str \| None`	`None`	Filter paths and optionally split into blocks. Syntax: `"event_a->.->event_b"`, where `->` separates events and `.` matches any sequence. See Path pattern below.
`diff`	`list \| None`	`None`	Diff mode: `[segment_col, value1, value2]`. Use `"<OUTER>"` as `value2` to compare against all other users.
`path_id_col`	`str \| None`	`None`	Override the path ID column.
`height`	`int`	`500`	Widget height in pixels.
`sidebar_open`	`bool`	`True`	Whether the settings sidebar starts open.

Path pattern

Without a pattern, Step Sankey shows transitions across all paths from path_start to path_end. With a pattern you can focus on a specific part of the journey: what do users do in the steps immediately surrounding this event?

When the pattern contains more than one anchor event — for example ".*->add_to_cart->.*->purchase->.*" — the diagram renders one Sankey block per anchor, creating a funnel-like view. Each block is centred on its anchor event (step 0), so you can compare the context around add_to_cart and purchase side by side without switching views.

# What happens right before and after purchase?
es.step_sankey(path_pattern=".*->purchase")

# Funnel view: two blocks — one centred on add_to_cart,
# one on purchase. Compare the context around each step.
es.step_sankey(path_pattern=".*->add_to_cart->.*->purchase")

# What led to an error that occurred right after purchase?
es.step_sankey(path_pattern=".*->purchase->error")

# Where do users drop off?
# Centres on path_end so you can see which events precede exit.
es.step_sankey(path_pattern=".*->path_end")

Headless mode

es.step_sankey_data() returns the step matrices as a tuple of DataFrames without rendering a widget.

Mode	Returns
Standard	`tuple[DataFrame, ...]` — one DataFrame per matrix block
Diff (`diff=`)	`tuple[tuple[DataFrame, ...], tuple[DataFrame, ...], tuple[DataFrame, ...]]` — `(combined, group1, group2)`

matrices = es.step_sankey_data(max_steps=10)

# diff mode
combined, g1, g2 = es.step_sankey_data(
    max_steps=10,
    diff=["platform", "mobile", "desktop"],
)