dasf.ml.cluster.kmeans

K-Means algorithm module.

Classes

KMeans

K-Means clustering.

Module Contents

class dasf.ml.cluster.kmeans.KMeans(n_clusters=8, init=None, n_init=None, max_iter=300, tol=0.0001, verbose=0, random_state=None, copy_x=True, algorithm='full', oversampling_factor=2.0, n_jobs=1, init_max_iter=None, max_samples_per_batch=32768, precompute_distances='auto', output_type=None, **kwargs)

Bases: dasf.ml.cluster.classifier.ClusterClassifier

K-Means clustering.

Parameters

n_clustersint, default=8: The number of clusters to form as well as the number of centroids to generate.

init : {‘k-means++’, ‘random’}, callable or array-like of shape (n_clusters, n_features), default=’k-means++’

Method for initialization:

‘k-means++’ : selects initial cluster centers for k-mean clustering in a smart way to speed up convergence. See section Notes in k_init for more details.

‘random’: choose n_clusters observations (rows) at random from data for the initial centroids.

If an array is passed, it should be of shape (n_clusters, n_features) and gives the initial centers.

If a callable is passed, it should take arguments X, n_clusters and a random state and return an initialization.

n_initint, default=10

Number of time the k-means algorithm will be run with different centroid seeds. The final results will be the best output of n_init consecutive runs in terms of inertia.

max_iterint, default=300

Maximum number of iterations of the k-means algorithm for a single run.

tolfloat, default=1e-4

Relative tolerance with regards to Frobenius norm of the difference in the cluster centers of two consecutive iterations to declare convergence.

precompute_distances{‘auto’, True, False}, default=’auto’

Precompute distances (faster but takes more memory).

‘auto’ : do not precompute distances if n_samples * n_clusters > 12 million. This corresponds to about 100MB overhead per job using double precision. IMPORTANT: This is used only in Dask ML version.

True : always precompute distances.

False : never precompute distances.

verboseint, default=0

Verbosity mode.

random_stateint, RandomState instance or None, default=None

Determines random number generation for centroid initialization. Use an int to make the randomness deterministic. See Glossary.

copy_xbool, default=True

When pre-computing distances it is more numerically accurate to center the data first. If copy_x is True (default), then the original data is not modified. If False, the original data is modified, and put back before the function returns, but small numerical differences may be introduced by subtracting and then adding the data mean. Note that if the original data is not C-contiguous, a copy will be made even if copy_x is False. If the original data is sparse, but not in CSR format, a copy will be made even if copy_x is False.

n_jobsint, default=1

The number of OpenMP threads to use for the computation. Parallelism is sample-wise on the main cython loop which assigns each sample to its closest center. IMPORTANT: This is used only in Dask ML version.

None or -1 means using all processors.

init_max_iterint, default=None

Number of iterations for init step.

algorithm{“auto”, “full”, “elkan”}, default=”full”

K-means algorithm to use. The classical EM-style algorithm is “full”. The “elkan” variation is more efficient on data with well-defined clusters, by using the triangle inequality. However it’s more memory intensive due to the allocation of an extra array of shape (n_samples, n_clusters).

For now “auto” (kept for backward compatibiliy) chooses “elkan” but it might change in the future for a better heuristic.

Changed in version 0.18: Added Elkan algorithm

oversampling_factorint, default=2

The amount of points to sample in scalable k-means++ initialization for potential centroids. Increasing this value can lead to better initial centroids at the cost of memory. The total number of centroids sampled in scalable k-means++ is oversampling_factor * n_clusters * 8.

max_samples_per_batchint, default=32768

The number of data samples to use for batches of the pairwise distance computation. This computation is done throughout both fit predict. The default should suit most cases. The total number of elements in the batched pairwise distance computation is max_samples_per_batch * n_clusters. It might become necessary to lower this number when n_clusters becomes prohibitively large.

output_type{‘input’, ‘cudf’, ‘cupy’, ‘numpy’, ‘numba’}, default=None

Variable to control output type of the results and attributes of the estimator. If None, it’ll inherit the output type set at the module level, cuml.global_settings.output_type. See Output Data Type Configuration for more info.

Notes

The k-means problem is solved using either Lloyd’s or Elkan’s algorithm.

The average complexity is given by O(k n T), where n is the number of samples and T is the number of iteration.

The worst case complexity is given by O(n^(k+2/p)) with n = n_samples, p = n_features. (D. Arthur and S. Vassilvitskii, ‘How slow is the k-means method?’ SoCG2006)

In practice, the k-means algorithm is very fast (one of the fastest clustering algorithms available), but it falls in local minima. That’s why it can be useful to restart it several times.

If the algorithm stops before fully converging (because of tol or max_iter), labels_ and cluster_centers_ will not be consistent, i.e. the cluster_centers_ will not be the means of the points in each cluster. Also, the estimator will reassign labels_ after the last iteration to make labels_ consistent with predict on the training set.

Examples

>>> from dasf.ml.cluster import KMeans
>>> import numpy as np
>>> X = np.array([[1, 2], [1, 4], [1, 0],
...               [10, 2], [10, 4], [10, 0]])
>>> kmeans = KMeans(n_clusters=2, random_state=0).fit(X)
>>> kmeans.predict([[0, 0], [12, 3]])
array([1, 0], dtype=int32)

For further informations see: - https://scikit-learn.org/stable/modules/generated/sklearn.cluster.KMeans.html - https://ml.dask.org/modules/generated/dask_ml.cluster.KMeans.html - https://docs.rapids.ai/api/cuml/stable/api.html#k-means-clustering - https://docs.rapids.ai/api/cuml/stable/api.html#cuml.dask.cluster.KMeans

A generic constructor method.

_lazy_fit_cpu(X, y=None, sample_weight=None)

Compute Dask k-means clustering.

Parameters

X{array-like, sparse matrix} of shape (n_samples, n_features): Training instances to cluster. It must be noted that the data will be converted to C ordering, which will cause a memory copy if the given data is not C-contiguous. If a sparse matrix is passed, a copy will be made if it's not in CSR format.
yIgnored: Not used, present here for API consistency by convention.
sample_weightIgnored: Not used, present here for API consistency by convention.

Returns

selfobject: Fitted estimator.

_lazy_fit_gpu(X, y=None, sample_weight=None)

Compute Dask CuML k-means clustering.

Parameters

X{array-like, sparse matrix} of shape (n_samples, n_features): Training instances to cluster. It must be noted that the data will be converted to C ordering, which will cause a memory copy if the given data is not C-contiguous. If a sparse matrix is passed, a copy will be made if it's not in CSR format.
yIgnored: Not used, present here for API consistency by convention.
sample_weightarray-like of shape (n_samples,), default=None: The weights for each observation in X. If None, all observations are assigned equal weight.

Returns

selfobject: Fitted estimator.

_fit_cpu(X, y=None, sample_weight=None)

Compute Scikit Learn k-means clustering.

Parameters

X{array-like, sparse matrix} of shape (n_samples, n_features): Training instances to cluster. It must be noted that the data will be converted to C ordering, which will cause a memory copy if the given data is not C-contiguous. If a sparse matrix is passed, a copy will be made if it's not in CSR format.
yIgnored: Not used, present here for API consistency by convention.
sample_weightarray-like of shape (n_samples,), default=None: The weights for each observation in X. If None, all observations are assigned equal weight.

Returns

selfobject: Fitted estimator.

_fit_gpu(X, y=None, sample_weight=None)

Compute CuML k-means clustering.

Parameters

X{array-like, sparse matrix} of shape (n_samples, n_features): Training instances to cluster. It must be noted that the data will be converted to C ordering, which will cause a memory copy if the given data is not C-contiguous. If a sparse matrix is passed, a copy will be made if it's not in CSR format.
yIgnored: Not used, present here for API consistency by convention.
sample_weightarray-like of shape (n_samples,), default=None: The weights for each observation in X. If None, all observations are assigned equal weight.

Returns

selfobject: Fitted estimator.

_lazy_fit_predict_cpu(X, y=None, sample_weight=None)

Compute cluster centers and predict cluster index for each sample using Dask ML.

Convenience method; equivalent to calling fit(X) followed by predict(X).

Parameters

X{array-like, sparse matrix} of shape (n_samples, n_features): New data to transform.
yIgnored: Not used, present here for API consistency by convention.
sample_weightIgnored: Not used, present here for API consistency by convention.

Returns

labelsndarray of shape (n_samples,): Index of the cluster each sample belongs to.

_lazy_fit_predict_gpu(X, y=None, sample_weight=None)

Compute cluster centers and predict cluster index for each sample using Dask CuML.

Convenience method; equivalent to calling fit(X) followed by predict(X).

Parameters

X{array-like, sparse matrix} of shape (n_samples, n_features): New data to transform.
yIgnored: Not used, present here for API consistency by convention.
sample_weightarray-like of shape (n_samples,), default=None: The weights for each observation in X. If None, all observations are assigned equal weight.

Returns

labelsndarray of shape (n_samples,): Index of the cluster each sample belongs to.

_fit_predict_cpu(X, y=None, sample_weight=None)

Compute cluster centers and predict cluster index for each sample using Scikit Learn.

Convenience method; equivalent to calling fit(X) followed by predict(X).

Parameters

X{array-like, sparse matrix} of shape (n_samples, n_features): New data to transform.
yIgnored: Not used, present here for API consistency by convention.
sample_weightIgnored: Not used, present here for API consistency by convention.

Returns

labelsndarray of shape (n_samples,): Index of the cluster each sample belongs to.

_fit_predict_gpu(X, y=None, sample_weight=None)

Compute cluster centers and predict cluster index for each sample using CuML.

Convenience method; equivalent to calling fit(X) followed by predict(X).

Parameters

X{array-like, sparse matrix} of shape (n_samples, n_features): New data to transform.
yIgnored: Not used, present here for API consistency by convention.
sample_weightarray-like of shape (n_samples,), default=None: The weights for each observation in X. If None, all observations are assigned equal weight.

Returns

labelsndarray of shape (n_samples,): Index of the cluster each sample belongs to.

_lazy_predict_cpu(X, sample_weight=None)

Predict the closest cluster each sample in X belongs to using Dask ML.

In the vector quantization literature, cluster_centers_ is called the code book and each value returned by predict is the index of the closest code in the code book.

Parameters

X{array-like, sparse matrix} of shape (n_samples, n_features): New data to predict.
sample_weightIgnored: Not used, present here for API consistency by convention.

Returns

labelsndarray of shape (n_samples,): Index of the cluster each sample belongs to.

_lazy_predict_gpu(X, sample_weight=None)

Predict the closest cluster each sample in X belongs to using Dask CuML.

In the vector quantization literature, cluster_centers_ is called the code book and each value returned by predict is the index of the closest code in the code book.

Parameters

X{array-like, sparse matrix} of shape (n_samples, n_features): New data to predict.
sample_weightarray-like of shape (n_samples,), default=None: The weights for each observation in X. If None, all observations are assigned equal weight.

Returns

labelsndarray of shape (n_samples,): Index of the cluster each sample belongs to.

_predict_cpu(X, sample_weight=None)

Predict the closest cluster each sample in X belongs to using Scikit Learn.

In the vector quantization literature, cluster_centers_ is called the code book and each value returned by predict is the index of the closest code in the code book.

Parameters

X{array-like, sparse matrix} of shape (n_samples, n_features): New data to predict.
sample_weightarray-like of shape (n_samples,), default=None: The weights for each observation in X. If None, all observations are assigned equal weight.

Returns

labelsndarray of shape (n_samples,): Index of the cluster each sample belongs to.

_predict_gpu(X, sample_weight=None)

Predict the closest cluster each sample in X belongs to using CuML.

In the vector quantization literature, cluster_centers_ is called the code book and each value returned by predict is the index of the closest code in the code book.

Parameters

X{array-like, sparse matrix} of shape (n_samples, n_features): New data to predict.
sample_weightarray-like of shape (n_samples,), default=None: The weights for each observation in X. If None, all observations are assigned equal weight.

Returns

labelsndarray of shape (n_samples,): Index of the cluster each sample belongs to.

_lazy_predict2_cpu(X, sample_weight=None)

A block predict using Scikit Learn variant but for Dask.

In the vector quantization literature, cluster_centers_ is called the code book and each value returned by predict is the index of the closest code in the code book.

Parameters

X{array-like, sparse matrix} of shape (n_samples, n_features): New data to predict.
sample_weightarray-like of shape (n_samples,), default=None: The weights for each observation in X. If None, all observations are assigned equal weight.

Returns

labelsndarray of shape (n_samples,): Index of the cluster each sample belongs to.

_lazy_predict2_gpu(X, sample_weight=None)

A block predict using CuML variant but for Dask.

In the vector quantization literature, cluster_centers_ is called the code book and each value returned by predict is the index of the closest code in the code book.

Parameters

X{array-like, sparse matrix} of shape (n_samples, n_features): New data to predict.
sample_weightarray-like of shape (n_samples,), default=None: The weights for each observation in X. If None, all observations are assigned equal weight.

Returns

labelsndarray of shape (n_samples,): Index of the cluster each sample belongs to.

_predict2_cpu(X, sample_weight=None, compat=True)

A block predict using Scikit Learn variant as a placeholder.

In the vector quantization literature, cluster_centers_ is called the code book and each value returned by predict is the index of the closest code in the code book.

Parameters

X{array-like, sparse matrix} of shape (n_samples, n_features): New data to predict.
sample_weightarray-like of shape (n_samples,), default=None: The weights for each observation in X. If None, all observations are assigned equal weight.
compatbool: There is no version for single CPU/GPU for predict2. This compatibility parameter uses the original predict method. Otherwise, it raises an exception.

Returns

labelsndarray of shape (n_samples,): Index of the cluster each sample belongs to.

_predict2_gpu(X, sample_weight=None, compat=True)

A block predict using CuML variant as a placeholder.

In the vector quantization literature, cluster_centers_ is called the code book and each value returned by predict is the index of the closest code in the code book.

Parameters

X{array-like, sparse matrix} of shape (n_samples, n_features): New data to predict.
sample_weightarray-like of shape (n_samples,), default=None: The weights for each observation in X. If None, all observations are assigned equal weight.
compatbool: There is no version for single CPU/GPU for predict2. This compatibility parameter uses the original predict method. Otherwise, it raises an exception.

Returns

labelsndarray of shape (n_samples,): Index of the cluster each sample belongs to.

predict2(sample_weight=None): Generic predict2 funtion according executor (for some ML methods only).

dasf.ml.cluster.kmeans

Classes

Module Contents

Parameters

See Also

Notes

Examples

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns