Cluster Analysis
An interactive tool for finding an optimal splitting of paths by behavioral metrics. Allows you to inspect clusters in a Segment Overview-style heatmap and offers the best possible splitting from the silhouette score perspective. Once the splitting looks right, you can label the clusters and save them as a new segment column of the eventstream right from the UI by clicking "Save Clusters".
Usage
stream.cluster_analysis(
features=[{"metric": "length"}, {"metric": "duration"}, {"metric": "event_count_bulk"}],
n_clusters="3-6",
)
Parameters
Data
Data parameters change the computed result. They are exactly the arguments of
the widget's headless twin stream.cluster_analysis_data() — see
headless mode below.
| Parameter | Type | Description |
|---|---|---|
features | list of dict, optional | Metric configurations used as clustering features (see the Path Metrics). If omitted, the sidebar starts pre-filled with a wildcard event_count_bulk metric (one column per event in the eventstream) — that pre-fill is a starting point to edit, not something that runs on its own: passing features explicitly (or clicking "Apply" in the sidebar) is what actually triggers clustering. |
method | {"kmeans", "hdbscan"}, default "kmeans" | Clustering algorithm. |
scaler | {"minmax", "standard"}, optional | Feature scaler applied before clustering; default "minmax". |
n_clusters | int, list of int, or str, optional | Number of clusters. A single int fixes the cluster count; a list of ints or a range string (e.g. "3-8") runs a silhouette-scored grid search over that range and picks the best. Defaults to "3-8". |
overview_metrics | list of dict, optional | Metrics shown in the overview heatmap after clustering (independent of features). If omitted, the sidebar starts pre-filled with a wildcard event_count_bulk metric here too (mean count per event); same as features, it only takes effect once you click "Apply" or pass the argument explicitly. Both features and overview_metrics accept metric configs from the same Path Metrics registry. |
path_col | str, optional | Path ID column override; defaults to schema.path_col. |
Display
Display parameters only affect how the widget is rendered.
| Parameter | Type | Description |
|---|---|---|
height | int, default 520 | 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.cluster_analysis_data()
Run cluster analysis headlessly and return a dict of results.
Pass lists for n_clusters / nmf_components / min_cluster_size to trigger
grid search with silhouette scoring. For the kmeans method (the default),
n_clusters defaults to "3-8" if omitted — including for
nmf_components-only searches.
best_params holds the concrete parameter values actually used to produce
overview_df (the winning combination when searching, or just the fixed
values passed in otherwise) — pass it straight to add_clusters to
materialize the same clustering as a segment column.
Examples
Basic
stream.cluster_analysis(
features=[
{"metric": "event_count_bulk", "metric_args": {"events": ["catalog", "product_view", "add_to_cart", "purchase"]}},
],
n_clusters=3,
)