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, while in diff mode columns sum to 0.

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

Usage

stream.step_matrix(path_pattern="purchase")
stream.step_matrix(path_pattern="add_to_cart->.*->purchase")
stream.step_matrix(diff=("is_new_user", False, True))

Parameters

Data

Data parameters change the computed result. They are exactly the arguments of the widget's headless twin stream.step_matrix_data() — see headless mode below.

Parameter	Type	Description
`max_steps`	`int, default 10`	Number of path steps to compute on each side of the anchor.
`diff`	`tuple or list, optional`	Draws a comparative chart for a pair of segments; see Diff mode. `(segment_col, value1, value2)` or `(path_ids1, path_ids2)`; `value2` may be `<REST>`.
`path_col`	`str, optional`	Path ID column override; defaults to `schema.path_col`.
`path_pattern`	`str, optional`	Restrict/split paths using a `"->"`-separated sequence of anchor events, where `.` matches any run of events, e.g. `"add_to_cart->.->purchase"`. Without a pattern, shows the whole path from `path_start` to `path_end`. Multiple anchors render one matrix block per anchor, side by side. A pattern that doesn't start at `path_start` or end at `path_end` shows a serrated edge, signalling paths continue beyond the visible range. To see the neighborhood around a single event: `path_pattern="add_to_cart"`.

Display

Display parameters only affect how the widget is rendered.

Parameter	Type	Description
`step_window`	`int, default 3`	Number of step columns shown around each anchor.
`height`	`int, default 600`	Widget height in pixels.
`sidebar_open`	`bool, default True`	Whether the sidebar starts open.
`state_file`	`str, optional`	JSON file the widget state is bound to; see Saving widget state.

Headless mode

stream.step_matrix_data()

Alias for step_sankey_data — Step Matrix and Step Sankey render the same underlying per-step data, so both widgets share one headless method.

Examples

Basic

Without a path_pattern, the matrix is anchored at path_start: column 0 is the first step of every path, and each column to the right is one step further in.

stream.step_matrix()

Path pattern - central event

A single event as path_pattern re-centers the matrix on that event instead of path_start: column 0 is always purchase, negative columns are the steps leading up to it, positive columns are what follows.

stream.step_matrix(path_pattern="purchase")

Path pattern - funnel patterns

Chaining several anchors with .* renders one matrix block per anchor, side by side, so you can follow a multi-step funnel across blocks.

stream.step_matrix(path_pattern="payment_details->.*->shipping_details->.*->purchase", step_window=2)

Path pattern - drop-off points

path_pattern="path_end" centers on where paths end, so the columns to the left show what users tend to do right before dropping off (or completing their path).

stream.step_matrix(path_pattern="path_end")

Diff mode

Passing diff splits paths into two segments and shows the difference between them at each step, making it easy to spot where the segments' behavior diverges.

stream.step_matrix(diff=["platform", "mobile", "desktop"])