Widgets

Widgets are interactive visualizations that run directly in your notebook. Each widget connects to your eventstream, computes the relevant analysis, and renders an interactive UI where you can adjust parameters and explore the data without writing additional code.

Creating a widget

Every widget is available as a method on the Eventstream object. In the examples throughout this section, es refers to an Eventstream instance.

es.transition_graph()
es.step_sankey()
es.step_matrix()
es.funnel()
es.segment_overview()
es.cluster_analysis()

All parameters are optional. You can call any widget without arguments and configure it interactively using the sidebar that appears on the right side of the widget.

Common parameters

All widgets share the following parameters:

Interactive configuration

Every widget has a settings sidebar where you can adjust all parameters interactively. Changes take effect immediately when you click Apply. You do not need to re-run the notebook cell.

Passing arguments and configuring the widget in the sidebar are equivalent. For example, these two are the same:

# Configure via arguments
es.funnel(steps=["page_view", "add_to_cart", "purchase"])

# Configure interactively — open the widget, add the same steps in the sidebar
es.funnel()

Arguments are a convenient way to reproduce a specific configuration without clicking through the UI. They are also useful when sharing notebooks — a reader can see the configuration at a glance without opening the widget.

Saving widget state

Cloud save is currently available for the Transition Graph and Step Matrix widgets. Pass a cloud_file_name to enable it:

es.transition_graph(cloud_file_name="my_graph")
es.step_matrix(cloud_file_name="my_matrix")

Hopscotch saves the widget configuration — including node positions — to the cloud whenever you make a change. The next time you run the same cell, the widget restores its previous state automatically.

Cloud save requires authentication. Click the cloud icon in the widget sidebar to sign in. Access is currently invite-only — to request early access, message Vladimir on LinkedIn.

Overriding saved state with arguments

Any argument passed explicitly takes precedence over the saved state. This lets you load a saved configuration and adjust one parameter without touching the rest:

# Load saved configuration but override the height
es.transition_graph(cloud_file_name="my_graph", height=600)

Diff mode

Transition Graph, Step Sankey, Step Matrix, and Funnel support diff mode, which overlays two groups in the same visualization so you can compare their behavior directly.

Pass a 3-element list [segment_col, value1, value2] to the diff parameter:

es.funnel(
    steps=["page_view", "add_to_cart", "purchase"],
    diff=["plan", "pro", "free"],
)

Use the special value <OUTER> as value2 to compare a segment against everyone else:

es.transition_graph(diff=["country", "US", "<OUTER>"])

Diff mode can also be configured interactively in the widget sidebar.

Headless mode

Every widget has a corresponding headless method that runs the same computation and returns the raw data instead of rendering a widget. This is useful for building custom visualizations, exporting results, or running analysis in automated pipelines.

Headless methods follow the naming pattern <widget>_data():

# Get transition matrix as a DataFrame
tm = es.transition_graph_data(edge_weight="proba_out")

# Get funnel results as a dict
result = es.funnel_data(steps=["page_view", "add_to_cart", "purchase"])

Headless methods accept the same parameters as their widget counterparts excluding those that are needed for visualization only like height.