Cluster Analysis

Interactive clustering widget for Jupyter notebooks.

Clusters paths by behavioral metrics and shows a Segment Overview-style heatmap for the resulting clusters. All parameters are also editable from the widget's sidebar (including feature/metric configuration and an NMF decomposition option not exposed here as a direct argument).

Usage

stream.cluster_analysis(
    features=[{"metric": "length"}, {"metric": "duration"}],
    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.

No parameters.

Display

Display parameters only affect how the widget is rendered.

Parameter	Type	Description
`features`	`list of dict, optional`	Metric configurations used as clustering features (see the Path Metrics documentation page); defaults to per-event counts for every event in the eventstream.
`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`); defaults to per-event counts for every event. 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`.
`height`	`int, default 520`	Widget height in pixels.
`sidebar_open`	`bool, default True`	Whether the sidebar starts open.

Headless mode

stream.cluster_analysis_data()

Run cluster analysis headlessly and return dict with overview_df / silhouette / nmf.

Pass lists for n_clusters / nmf_components / min_cluster_size to trigger grid search with silhouette scoring. n_clusters is required for the kmeans method (the default), including nmf_components-only searches.

Examples

Basic

stream.cluster_analysis(
  features=[
      {"metric": "event_count", "metric_args": {"events": ["catalog", "product_view", "add_to_cart", "purchase"]}},
  ],
  n_clusters=3,
)