mojolearn.MiniBatchKMeans#

class mojolearn.MiniBatchKMeans(n_clusters=8, *, init='k-means++', max_iter=100, batch_size=1024, verbose=0, compute_labels=True, random_state=None, tol=0.0, max_no_improvement=10, init_size=None, n_init='auto', reassignment_ratio=0.01)[source]#

Bases: _CentersMixin, _XCluster

Mini-batch k-means clustering.

Follows scikit-learn’s MiniBatchKMeans: each step assigns a random batch of rows to the nearest center and moves the centers, low-count centers are randomly reassigned, and the fit stops early on the smoothed batch inertia. Batches are drawn from this library’s own seeded random stream rather than NumPy’s, so results agree with scikit-learn’s within a tolerance, not bit for bit. Input is converted to float32.

Parameters:

  • n_clusters (int, default 8) – Number of clusters. Must be between 1 and the number of samples.

  • init ({‘k-means++’, ‘random’}, array-like or callable, default ‘k-means++’) – How the centers start. ‘k-means++’ is greedy k-means++, as in scikit-learn. ‘random’ picks n_clusters distinct rows of the init sample, drawn by weight. An array of shape (n_clusters, n_features) gives the starting centers. A callable is called once as init(X, n_clusters, random_state=rs) with every row of X (scikit-learn passes a subsample) and must return such an array; rs is a NumPy RandomState seeded by random_state when NumPy is installed, otherwise the int.

  • max_iter (int, default 100) – Maximum number of passes over the data.

  • batch_size (int, default 1024) – Rows per mini-batch.

  • verbose (int, default 0) – Accepted for scikit-learn compatibility; nothing is printed.

  • compute_labels (bool, default True) – Accepted for scikit-learn compatibility; labels_ is always computed.

  • random_state (int or None, default None) – Non-negative seed for the batch draws and initialization. None means 0, so repeated fits give the same result. A NumPy RandomState is not accepted.

  • tol (float, default 0.0) – Early-stop tolerance on center movement, as in scikit-learn.

  • max_no_improvement (int or None, default 10) – Stop after this many steps without improvement of the smoothed batch inertia. None disables this early stop.

  • init_size (int or None, default None) – Number of rows used for initialization. None uses scikit-learn’s rule (3 * batch_size, at least 3 * n_clusters, at most n_samples).

  • n_init (int or ‘auto’, default ‘auto’) – Number of initializations; the best one is kept. ‘auto’ means 3 for init='random' and 1 otherwise.

  • reassignment_ratio (float, default 0.01) – Controls how often low-count centers are reassigned, as in scikit-learn.

  • numeric_mode (str or None, default None) – Numeric mode for this estimator. None uses the process default (see mojolearn.set_numeric_mode()).

Variables:

  • cluster_centers_ (Array of shape (n_clusters, n_features), float32) – Cluster centers.

  • counts_ (Array of shape (n_clusters,), float32) – Weighted number of rows assigned to each center over the fit.

  • labels_ (Array of shape (n_samples,), int32) – Cluster of each training row.

  • inertia_ (float) – Sum of squared distances of the training rows to their nearest center.

  • n_steps_ (int) – Number of mini-batch steps run.

  • n_iter_ (int) – Number of passes over the data.

  • n_features_in_ (int) – Number of features seen in fit.

Examples

>>> import numpy as np, mojolearn
>>> X = np.random.default_rng(0).random((1000, 8), dtype=np.float32)
>>> model = mojolearn.MiniBatchKMeans(n_clusters=4, random_state=0).fit(X)
>>> labels = model.predict(X)
__init__(n_clusters=8, *, init='k-means++', max_iter=100, batch_size=1024, verbose=0, compute_labels=True, random_state=None, tol=0.0, max_no_improvement=10, init_size=None, n_init='auto', reassignment_ratio=0.01)[source]#

Methods

fit(X[, y, sample_weight])

Fit the centers on X.

fit_predict(X[, y, sample_weight])

Fit the model on X and return the training labels.

fit_transform(X[, y, sample_weight])

Fit the model on X and return the distances to the centers.

get_params([deep])

numeric_mode_used()

The numeric mode this estimator runs in.

partial_fit(X[, y, sample_weight])

Run one mini-batch step on all of X.

predict(X)

Assign each row of X to its nearest cluster center.

score(X[, y, sample_weight])

Opposite of the inertia of X under the fitted centers.

set_params(**params)

Set constructor parameters.

transform(X)

Distance from each row of X to every cluster center.

vendor_used()

The GPU backend this estimator runs on.
fit(X, y=None, sample_weight=None)[source]#

Fit the centers on X.

Parameters:

  • X (array-like of shape (n_samples, n_features)) – Training rows, converted to float32. NaN or infinity raises ValueError.

  • y (ignored) – Present for scikit-learn compatibility.

  • sample_weight (array-like of shape (n_samples,) or None, default None) – Row weights. As in scikit-learn, they weight the k-means++ potentials, the init scoring and the batch draws.

Returns:

self (MiniBatchKMeans) – The fitted estimator.

Raises:

ValueError – If n_clusters is outside [1, n_samples], init is an unknown string or an array of the wrong shape, n_init is below 1, or X contains NaN or infinity.

partial_fit(X, y=None, sample_weight=None)[source]#

Run one mini-batch step on all of X.

As in scikit-learn, the first call initializes the centers from init_size rows of X using init. Later calls continue from the current centers (including those of an earlier fit); the random stream and the reassignment counter carry over between calls.

Parameters:

  • X (array-like of shape (n_samples, n_features)) – Rows for this step, converted to float32.

  • y (ignored) – Present for scikit-learn compatibility.

  • sample_weight (array-like of shape (n_samples,) or None, default None) – Row weights.

Returns:

self (MiniBatchKMeans) – The updated estimator. labels_ and inertia_ describe this batch.

Raises:

ValueError – If X has a different number of features than earlier calls, or on the first call if n_clusters exceeds the number of rows or init is invalid.