Step Matrix

Displays a heatmap table of step-by-step transition probabilities. Each cell shows the share of paths that pass through a given event at a given step relative to an anchor. The horizontal axis represents step offset from the anchor (negative steps are before it, positive are after), and the vertical axis lists the events.

Each column sums to 1 in standard mode (every path is accounted for at each step). In diff mode each cell shows value2 − value1, so columns sum to 0. Red cells mean the event is more common in group 2; blue cells mean it is more common in group 1.

Step Matrix and Step Sankey visualise the same underlying data in different forms.

Usage

es.step_matrix()

With options:

es.step_matrix(
    path_pattern="path_start->.*->purchase->.*->path_end",
    diff=["is_new_user", False, True],
    cloud_file_name="my_matrix",
)

Parameters

Parameter	Type	Default	Description
`max_steps`	`int`	`10`	Maximum number of steps to compute on each side of the anchor events.
`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]`. Cells show value2 − value1. Hover a cell to see the individual group values and the difference.
`cloud_file_name`	`str \| None`	`None`	Save and restore widget state to the cloud. See Saving widget state.
`height`	`int`	`600`	Widget height in pixels.
`sidebar_open`	`bool`	`True`	Whether the settings sidebar starts open.

Path pattern

Without a pattern, Step Matrix shows transitions across all paths from path_start to path_end. With a pattern you can zoom in on a specific part of the journey and ask: what do users do right before and after this event?

When the pattern contains more than one anchor event — for example ".*->add_to_cart->.*->purchase->.*" — the widget renders one matrix block per anchor, displayed side by side. This is similar to a funnel: each block focuses on the neighbourhood of one key step, so you can see how behaviour around add_to_cart differs from behaviour around purchase without switching views.

Patterns that do not start with path_start or do not end with path_end show a serrated edge on the corresponding side, signalling that paths continue beyond the visible range.

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

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

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

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

Headless mode

Step Matrix uses es.step_sankey_data() under the hood. Call it directly to get the raw step matrices as 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)`

data = es.step_sankey_data(
    max_steps=10,
    path_pattern="path_start->.*->purchase",
)