Principle:Online ml River Cluster Evolution Monitoring

Knowledge Sources	Domains	Last Updated
River River Docs	Online Clustering, Model Inspection, Concept Drift, Streaming Analytics	2026-02-08 16:00 GMT

Overview

Cluster Evolution Monitoring is the pattern for monitoring how cluster structures evolve over time by inspecting internal model state such as centroids, micro-cluster counts, and weights during the online learning process.

Description

In online clustering, the cluster structure is not static -- it evolves as new data arrives. Clusters may shift position, new clusters may emerge, existing clusters may merge or disappear, and the relative sizes of clusters may change. Understanding these dynamics is crucial for detecting concept drift, diagnosing model behavior, and building adaptive systems.

River's clustering algorithms expose their internal state through well-defined attributes, enabling users to inspect the cluster structure at any point during the stream. This pattern involves periodically or continuously reading model attributes to track cluster evolution.

Different algorithms expose different levels of internal state:

• KMeans: Exposes a centers dictionary mapping cluster IDs to centroid positions. Tracking centroid movement over time reveals how clusters drift.
• DBSTREAM: Exposes micro_clusters (the raw micro-cluster set), clusters (macro-clusters after reclustering), centers (macro-cluster centers), and the shared density graph. Monitoring micro-cluster births and deaths reveals density changes.
• DenStream: Exposes p_micro_clusters (potential) and o_micro_clusters (outlier) collections. Tracking the ratio of potential to outlier micro-clusters indicates data quality and cluster stability.
• CluStream: Exposes micro_clusters with temporal statistics and centers (macro-cluster centers). The temporal micro-clusters inherently track when data arrived.

By logging these attributes at regular intervals, users can build a time series of cluster statistics that reveals the evolution of the data-generating process.

Usage

Use Cluster Evolution Monitoring when:

• You want to detect concept drift by observing when cluster positions shift significantly.
• You need to diagnose clustering quality over time by tracking the number of micro-clusters, their weights, and spatial distribution.
• You are building dashboards or visualizations that display the current cluster state.
• You want to trigger alerts when clusters appear, disappear, or merge unexpectedly.
• You need to compare algorithms by observing how their internal states evolve differently on the same stream.

This is a Pattern Doc that documents how to use the inspection capabilities of River's clustering algorithms, not a specific algorithm implementation.

Theoretical Basis

The theoretical basis for cluster evolution monitoring rests on the concept of non-stationary data distributions in streaming environments:

PATTERN: Cluster Evolution Monitoring Loop

model = SomeClusterer(...)
history = []

FOR each (x, _) in data_stream at time t:
    model.learn_one(x)
    label = model.predict_one(x)

    // Periodic state snapshot
    IF t mod snapshot_interval == 0:
        snapshot = {
            'time': t,
            'centers': copy(model.centers),     // centroid positions
            'n_clusters': len(model.centers),   // number of active clusters
        }

        // Algorithm-specific state:
        IF model is DBSTREAM:
            snapshot['n_micro'] = len(model.micro_clusters)
        IF model is DenStream:
            snapshot['n_potential'] = len(model.p_micro_clusters)
            snapshot['n_outlier'] = len(model.o_micro_clusters)

        history.append(snapshot)

What to monitor:

Signal	Interpretation
Centroid position shift	Clusters are drifting; the underlying distribution is changing.
Increase in number of micro-clusters	New density regions are appearing in the data.
Decrease in number of micro-clusters	Clusters are merging or data density is decreasing.
Outlier micro-cluster count rising (DenStream)	Increasing noise or new cluster formation.
Shared density graph changes (DBSTREAM)	Cluster connectivity is evolving.

Drift detection heuristic:

FOR each consecutive pair of snapshots (s_t, s_{t+1}):
    delta = SUM_i distance(s_t.centers[i], s_{t+1}.centers[i])
    IF delta > drift_threshold:
        ALERT: significant cluster drift detected

Related Pages

• Implementation:Online_ml_River_Cluster_Centers_Inspection