MiniBatchKMeans

MiniBatchKMeans is the default backend and the recommended starting point for offline analysis. OverlapIndex fits one scikit-learn MiniBatchKMeans model per label, concatenates their centers into global prototype IDs, and scores samples using squared Euclidean distance to those centers.

When to use it

Choose this backend for most batch workflows, especially when the dataset is too large for repeated full KMeans fits. It supports dense arrays, SciPy sparse feature matrices, and all supported multi-label target formats.

Despite the backend’s name, OverlapIndex treats it as an offline backend. Calling partial_fit on OverlapIndex refits and recomputes the score from the provided batch; it does not call scikit-learn’s incremental MiniBatchKMeans API across batches.

Invocation

Because it is the default, model_type may be omitted:

from overlapindex import OverlapIndex

oi = OverlapIndex(
    kmeans_k=10,
    kmeans_kwargs={
        "random_state": 0,
        "batch_size": 8192,
        "n_init": 1,
    },
)
oi.fit(X, y)
print(oi.index)

The adapter defaults to batch_size=8192, n_init=1, and init="random". Entries in kmeans_kwargs override those defaults and are forwarded to scikit-learn. kmeans_k may be one positive integer for every label or a dictionary of label-specific counts.

Tuning guidance

  • Increase kmeans_k when a label has multimodal or curved support that a few centers cannot represent. More centers increase runtime and may also resolve finer overlap.

  • Never request fewer than two centers per label when a top-two overlap result needs to be well resolved. If a label has fewer samples than requested centers, the backend caps its center count at its sample count.

  • Use a fixed random_state for comparisons.

  • Adjust batch_size for memory and throughput; it does not control OverlapIndex.partial_fit semantics.

  • Use offline_chunk_size to bound the number of rows scored at once when the fitted centroid set is large.

See the runnable examples/iris_default_minibatch_kmeans.py example in the repository.