Implementation:Online ml River Cluster STREAMKMeans

Knowledge Sources	Domains	Last Updated
River River Docs Streaming-data algorithms for high-quality clustering (O'Callaghan et al., 2002)	Online Clustering, Chunk-Based Streaming	2026-02-08 16:00 GMT

Overview

Concrete tool for performing chunk-based streaming K-Means clustering, buffering observations in fixed-size chunks and periodically applying incremental K-Means to merge local cluster summaries into a global model.

Description

The cluster.STREAMKMeans class implements the STREAMKMeans algorithm. It maintains a temporary chunk buffer and a global cluster.KMeans instance. As new points arrive, they are accumulated in the buffer. When the buffer reaches chunk_size, a new local cluster.KMeans is instantiated and trained on all points in the chunk. The local centers are then fed into the global K-Means, which incrementally updates the overall cluster structure. The centers attribute always reflects the current global cluster centers.

Any additional keyword arguments passed to the constructor (such as halflife, sigma, seed) are forwarded to both the global and local cluster.KMeans instances.

Usage

Import cluster.STREAMKMeans when you want chunk-based online clustering that offers a quality improvement over pure per-point online K-Means. It is straightforward to configure with just a chunk size and number of clusters.

Code Reference

Source Location

river/cluster/streamkmeans.py:L6-L112

Signature

class STREAMKMeans(base.Clusterer):
    def __init__(self, chunk_size=10, n_clusters=2, **kwargs)

Import

from river import cluster

Key Parameters

Parameter	Default	Description
chunk_size	10	Maximum number of points buffered before triggering local K-Means and merging into the global model.
n_clusters	2	Number of clusters produced by both local and global K-Means instances.
**kwargs	--	Additional arguments passed to the internal cluster.KMeans instances (e.g., halflife, sigma, seed).

Methods

Method	Signature	Description
learn_one	learn_one(x: dict, w=None) -> None	Adds x to the chunk buffer; when the buffer is full, applies local K-Means and merges centers into the global model.
predict_one	predict_one(x: dict, w=None) -> int	Returns the index of the nearest global cluster center to x using Minkowski distance.

Key Attributes

Attribute	Type	Description
centers	dict	Current global cluster centers, updated after each chunk is processed.

I/O Contract

Inputs

Parameter	Type	Description
x	dict	A dictionary mapping feature names to numeric values.

Outputs

Output	Type	Description
predict_one return	int	The cluster index assigned to the observation based on nearest global center.

Usage Examples

from river import cluster
from river import stream

X = [
    [1, 0.5], [1, 0.625], [1, 0.75], [1, 1.125], [1, 1.5], [1, 1.75],
    [4, 1.5], [4, 2.25], [4, 2.5], [4, 3], [4, 3.25], [4, 3.5]
]

streamkmeans = cluster.STREAMKMeans(
    chunk_size=3,
    n_clusters=2,
    halflife=0.5,
    sigma=1.5,
    seed=0
)

for x, _ in stream.iter_array(X):
    streamkmeans.learn_one(x)

streamkmeans.predict_one({0: 1, 1: 0})
# 0

streamkmeans.predict_one({0: 5, 1: 2})
# 1

Related Pages

• Principle:Online_ml_River_STREAMKMeans_Clustering