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')[source]#

Bases: _CentersMixin, _XCluster

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)
__init__(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')[source]#

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)[source]#

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)[source]#

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.