Add Clusters

Cluster paths using ML and add a new segment column with integer cluster labels.

Per-path metrics are computed from features, optionally scaled, then passed to the chosen clustering algorithm. The resulting cluster label is broadcast to every row of the corresponding path.

Usage

stream.add_clusters(
    name="cluster",
    features=[
        {"metric": "length"},
        {"metric": "event_count", "metric_args": {"events": "purchase"}},
    ],
    method="kmeans",
    n_clusters=4,
    scaler="minmax",
)

Parameters

Parameter	Type	Description
`name`	`str`	Name of the new segment column to add.
`features`	`list of dict`	Metric configurations used as clustering features. Each dict has a `"metric"` key (str) and an optional `"metric_args"` key (dict). Available metrics: `"length"`, `"duration"`, `"event_count"`, `"has_event"`, `"time_between"`, `"first_event_time"`, `"active_days"`, `"matches_pattern"`, `"in_segment"`. See the Path Metrics documentation page for the full metric reference.
`method`	`str, default` "kmeans"``	Clustering algorithm. One of `"kmeans"` or `"hdbscan"`.
`scaler`	`str or None, default` None``	Feature scaler applied before clustering. One of `"minmax"`, `"standard"`, or `None`.
`n_clusters`	`int, optional`	Number of clusters (required for `"kmeans"`).
`min_cluster_size`	`int, optional`	Minimum cluster size (used by `"hdbscan"`).
`cluster_selection_epsilon`	`float, optional`	HDBSCAN cluster-selection epsilon.
`nmf_components`	`int, optional`	When set, reduces features to this many NMF components before clustering.
`path_col`	`str, optional`	Path ID column override; defaults to `schema.path_col`.
`event_col`	`str, optional`	Event column override; defaults to `schema.event_col`.