mojolearn.BisectingKMeans#

class mojolearn.BisectingKMeans(n_clusters=8, *, init='random', n_init=1, random_state=None, max_iter=300, verbose=0, tol=0.0001, copy_x=True, algorithm='lloyd', bisecting_strategy='biggest_inertia')#

Bisecting k-means clustering.

Starting from one cluster, the leaf with the highest score is split in two by 2-means, n_clusters - 1 times. The 2-means step is this library’s KMeans, so tol uses its centroid-shift rule and the ‘random’ and ‘k-means++’ starts are its own; results agree with scikit-learn’s within a tolerance. Input is converted to float32.

Parameters:

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

  • init ({‘random’, ‘k-means++’}, default ‘random’) – Start of each 2-means split. Any other value raises NotImplementedError.

  • n_init (int, default 1) – Number of 2-means restarts per split; the best is kept. Must be at least 1.

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

  • max_iter (int, default 300) – Maximum iterations of each 2-means.

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

  • tol (float, default 1e-4) – Convergence tolerance of each 2-means, on the centroid shift.

  • copy_x (bool, default True) – Accepted for scikit-learn compatibility; X is never modified.

  • algorithm ({‘lloyd’, ‘elkan’}, default ‘lloyd’) – Accepted for scikit-learn compatibility; both run the same Lloyd iterations.

  • bisecting_strategy ({‘biggest_inertia’, ‘largest_cluster’}, default ‘biggest_inertia’) – Which leaf to split next: the one with the largest inertia, or the one with the most rows.

  • 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) – Centers of the leaf clusters.

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

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

  • 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.BisectingKMeans(n_clusters=4, random_state=0).fit(X)
>>> labels = model.predict(X)

See also

KMeans, MiniBatchKMeans

User guide: Clustering

Choosing an estimator

Methods

fit(X[, y, sample_weight])

Build the bisection tree 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.

predict(X)

Assign each row of X to a leaf cluster.

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)#

Build the bisection tree 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.

Returns:

self (BisectingKMeans) – The fitted estimator.

Raises:

  • NotImplementedError – If init is not ‘random’ or ‘k-means++’.

  • ValueError – If bisecting_strategy or algorithm is unknown, n_clusters is outside [1, n_samples], n_init is below 1, or X contains NaN or infinity.

predict(X)#

Assign each row of X to a leaf cluster.

As in scikit-learn, each row descends the bisection tree, going to the nearer child center at each split (the left child on a tie). This can differ from the nearest leaf center.

Parameters:

X (array-like of shape (n_samples, n_features)) – Rows to label, converted to float32.

Returns:

labels (Array of shape (n_samples,), int32) – Leaf cluster of each row.

Raises:

RuntimeError – If the model is not fitted.

fit_predict(X, y=None, sample_weight=None)#

Fit the model on X and return the training labels.

Parameters:

  • X (array-like of shape (n_samples, n_features)) – Training rows, converted to float32.

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

  • sample_weight (ignored) – Accepted for scikit-learn compatibility but not passed to the fit. Call fit(X, sample_weight=...) and read labels_ to fit with weights.

Returns:

labels (Array of shape (n_samples,), int32) – The fitted labels_.

fit_transform(X, y=None, sample_weight=None)#

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

Parameters:

  • X (array-like of shape (n_samples, n_features)) – Training rows, converted to float32.

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

  • sample_weight (ignored) – Accepted for scikit-learn compatibility but not passed to the fit.

Returns:

distances (Array of shape (n_samples, n_clusters), float32) – Euclidean distance from each training row to each center.

numeric_mode_used()#

The numeric mode this estimator runs in.

Returns:

str – 'identical' or 'fast', read from the compiled binary the estimator uses, not from the argument it was given.

score(X, y=None, sample_weight=None)#

Opposite of the inertia of X under the fitted centers.

Parameters:

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

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

  • sample_weight (ignored) – Accepted for scikit-learn compatibility; every row counts once.

Returns:

score (float) – Minus the sum of squared distances from each row to its nearest center (larger is better).

Raises:

RuntimeError – If the model is not fitted.

set_params(**params)#

Set constructor parameters. The estimator is rebuilt through its constructor, so every constructor check runs again and any fitted state is dropped, as a new setting invalidates it.

transform(X)#

Distance from each row of X to every cluster center.

Parameters:

X (array-like of shape (n_samples, n_features)) – Rows to transform, converted to float32.

Returns:

distances (Array of shape (n_samples, n_clusters), float32) – Euclidean distance from each row to each center.

Raises:

RuntimeError – If the model is not fitted.

vendor_used()#

The GPU backend this estimator runs on.

Returns:

str – 'metal', 'cuda' or 'hip', read from the compiled binary the estimator uses.