# KMeans ### *class* cuml.cluster.KMeans(, n_clusters=8, max_iter=300, tol=0.0001, verbose=False, random_state=None, init='scalable-k-means++', n_init='auto', oversampling_factor=2.0, max_samples_per_batch=32768, device_buffer_samples=0, init_size=0, output_type=None) KMeans is a basic but powerful clustering method which is optimized via Expectation Maximization. It randomly selects K data points in X, and computes which samples are close to these points. For every cluster of points, a mean is computed (hence the name), and this becomes the new centroid. cuML’s KMeans expects an array-like object or cuDF DataFrame, and supports the scalable KMeans++ initialization method. This method is more stable than randomly selecting K points. * **Parameters:** **n_clusters** : The number of centroids or clusters you want. **max_iter** : The more iterations of EM, the more accurate, but slower. **tol** : Stopping criterion when centroid means do not change much. **verbose** : Sets logging level. It must be one of `cuml.common.logger.level_*`. See [Verbosity Levels](../../cuml/index.html.md#verbosity-levels) for more info. **random_state** : If you want results to be the same when you restart Python, select a state. **init** : - `'scalable-k-means++'` or `'k-means||'`: Uses fast and stable scalable kmeans++ initialization. k-means++ is the constrained case of k-means|| with `oversampling_factor=0` - `'random'`: Choose `n_cluster` observations (rows) at random from data for the initial centroids. - If an ndarray is passed, it should be of shape (`n_clusters`, `n_features`) and gives the initial centers. **n_init: ‘auto’ or int (default = ‘auto’)** : Number of instances the k-means algorithm will be called with different seeds. The final results will be from the instance that produces lowest inertia out of n_init instances.
When `n_init='auto'`, the number of runs depends on the value of `init`: 1 if using `init='"k-means||"` or `init="scalable-k-means++"`; 10 otherwise.
#### Versionadded Added in version 25.02: Added ‘auto’ option for `n_init`.
#### Versionchanged Changed in version 25.04: Default value for `n_init` will change from 1 to `'auto'` in version 25.04. **oversampling_factor** : 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_batch** : 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. **device_buffer_samples** : Number of host samples to buffer to the device per GPU batch when fitting with host-resident inputs. This selects the fit path for host-resident inputs: the out-of-core host fit path is used whenever `device_buffer_samples > 0`. When `device_buffer_samples == 0` (default), host inputs are copied to the device in full and the standard device fit is used. Ignored when the input is already device-resident (e.g. cupy.ndarray, cudf.DataFrame), which always uses the device fit. **init_size** : Number of samples to randomly draw for the KMeansPlusPlus initialization step. A random subset of this size is used for centroid seeding. Only applies when the out-of-core host fit path is actually selected, i.e. when the input is host-resident and `device_buffer_samples > 0`. When set to 0 (default) on that path, `min(3 * n_clusters, n_samples)` is used. It is ignored on the device fit path — device-resident inputs, as well as host inputs that are copied to the device in full (`device_buffer_samples == 0`) — where the full dataset is always used for seeding. **output_type** : Return results and set estimator attributes to the indicated output type. If None, the output type set at the module level (`cuml.global_settings.output_type`) will be used. See [Output Data Type Configuration](../../cuml/index.html.md#output-data-type-configuration) for more info. * **Attributes:** **cluster_centers_** : The coordinates of the final clusters. This represents of “mean” of each data cluster. **labels_** : Which cluster each datapoint belongs to. ### Methods | [`fit`](#cuml.cluster.KMeans.fit)(self, X[, y, sample_weight]) | Compute k-means clustering with X. | |---------------------------------------------------------------------------------------------|--------------------------------------------------------------------| | [`fit_predict`](#cuml.cluster.KMeans.fit_predict)(self, X[, y, sample_weight]) | Compute cluster centers and predict cluster index for each sample. | | [`fit_transform`](#cuml.cluster.KMeans.fit_transform)(self, X[, y, sample_weight]) | Compute clustering and transform X to cluster-distance space. | | [`predict`](#cuml.cluster.KMeans.predict)(self, X) | Predict the closest cluster each sample in X belongs to. | | [`score`](#cuml.cluster.KMeans.score)(self, X[, y, sample_weight]) | Opposite of the value of X on the K-means objective. | | [`transform`](#cuml.cluster.KMeans.transform)(self, X) | Transform X to a cluster-distance space. | ### Notes KMeans requires `n_clusters` to be specified. This means one needs to approximately guess or know how many clusters a dataset has. If one is not sure, one can start with a small number of clusters, and visualize the resulting clusters with PCA, UMAP or T-SNE, and verify that they look appropriate. **Applications of KMeans** > The biggest advantage of KMeans is its speed and simplicity. That is > why KMeans is many practitioner’s first choice of a clustering > algorithm. KMeans has been extensively used when the number of clusters > is approximately known, such as in big data clustering tasks, > image segmentation and medical clustering. For additional docs, see [scikitlearn’s Kmeans](http://scikit-learn.org/stable/modules/generated/sklearn.cluster.KMeans.html). ### Examples ```python >>> # Both import methods supported >>> from cuml import KMeans >>> from cuml.cluster import KMeans >>> import cudf >>> import numpy as np >>> import pandas as pd >>> >>> a = np.asarray([[1.0, 1.0], [1.0, 2.0], [3.0, 2.0], [4.0, 3.0]], ... dtype=np.float32) >>> b = cudf.DataFrame(a) >>> # Input: >>> b 0 1 0 1.0 1.0 1 1.0 2.0 2 3.0 2.0 3 4.0 3.0 >>> >>> # Calling fit >>> kmeans_float = KMeans(n_clusters=2, n_init="auto", random_state=1) >>> kmeans_float.fit(b) KMeans(n_clusters=2, random_state=1) >>> >>> # Labels: >>> kmeans_float.labels_ 0 0 1 0 2 1 3 1 dtype: int32 >>> # cluster_centers: >>> kmeans_float.cluster_centers_ 0 1 0 1.0 1.5 1 3.5 2.5 ``` #### as_sklearn()[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/internals/interop.py#L206) Convert this estimator into an equivalent scikit-learn (or scikit-learn extension) estimator. * **Returns:** sklearn.base.BaseEstimator : A scikit-learn compatible estimator instance that mirrors the trained state of the current estimator. #### fit(self, X, y=None, sample_weight=None) → 'KMeans'[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/cluster/kmeans.pyx#L730) Compute k-means clustering with X. * **Parameters:** **X** : Dense matrix with dtype float32 or float64. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series. **y** : Dense matrix with dtype float32 or float64. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series. **sample_weight** : The weights for each observation in X. If None, all observations are assigned equal weight. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series. #### fit_predict(self, X, y=None, sample_weight=None)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/cluster/kmeans.pyx#L1002) Compute cluster centers and predict cluster index for each sample. * **Parameters:** **X** : Dense matrix with dtype float32 or float64. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series. **y** : Dense matrix with dtype float32 or float64. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series. **sample_weight** : The weights for each observation in X. If None, all observations are assigned equal weight. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series. * **Returns:** **preds** : Cluster indexes
For more information on how to configure cuML’s output type, refer to: [Output Data Type Configuration](../../cuml/index.html.md#output-data-type-configuration). #### fit_transform(self, X, y=None, sample_weight=None)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/cluster/kmeans.pyx#L1188) Compute clustering and transform X to cluster-distance space. * **Parameters:** **X** : Dense matrix with dtype float32 or float64. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series. **y** : Dense matrix with dtype float32 or float64. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series. **sample_weight** : The weights for each observation in X. If None, all observations are assigned equal weight. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series. * **Returns:** **X_new** : Transformed data
For more information on how to configure cuML’s output type, refer to: [Output Data Type Configuration](../../cuml/index.html.md#output-data-type-configuration). #### *classmethod* from_sklearn(model)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/internals/interop.py#L222) Create a cuml estimator from a scikit-learn estimator. * **Parameters:** **model** : A compatible scikit-learn (or scikit-learn extension) estimator. * **Returns:** cls : A new instance of this cuml estimator class that mirrors the state of the input estimator. ### Notes `output_type` of the estimator is set to “numpy” by default, as these cannot be inferred from training arguments. If something different is required, then please use cuml’s output_type configuration utilities. #### get_feature_names_out(input_features=None) Get output feature names for transformation. The feature names out will prefixed by the lowercased class name. For example, if the transformer outputs 3 features, then the feature names out are: `["class_name0", "class_name1", "class_name2"]`. * **Parameters:** **input_features** : Only used to validate feature names with the names seen in [`fit`](#cuml.cluster.KMeans.fit). * **Returns:** **feature_names_out** : Transformed feature names. #### get_params(deep=True)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/internals/base.py#L191) Returns a dict of all params owned by this class. If the child class has appropriately overridden the `_get_param_names` method and does not need anything other than what is there in this method, then it doesn’t have to override this method #### predict(self, X)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/cluster/kmeans.pyx#L1064) Predict the closest cluster each sample in X belongs to. * **Parameters:** **X** : Dense matrix with dtype float32 or float64. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series. * **Returns:** **preds** : Cluster indexes
For more information on how to configure cuML’s output type, refer to: [Output Data Type Configuration](../../cuml/index.html.md#output-data-type-configuration). #### score(self, X, y=None, sample_weight=None)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/cluster/kmeans.pyx#L1173) Opposite of the value of X on the K-means objective. * **Parameters:** **X** : Dense matrix with dtype float32 or float64. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series. **y** : Dense matrix with dtype float32 or float64. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series. **sample_weight** : The weights for each observation in X. If None, all observations are assigned equal weight. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series. * **Returns:** **score** : Opposite of the value of X on the K-means objective. #### set_params(\*\*params)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/internals/base.py#L200) Accepts a dict of params and updates the corresponding ones owned by this class. If the child class has appropriately overridden the `_get_param_names` method and does not need anything other than what is, there in this method, then it doesn’t have to override this method #### transform(self, X)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/cluster/kmeans.pyx#L1077) Transform X to a cluster-distance space. * **Parameters:** **X** : Dense matrix with dtype float32 or float64. Acceptable formats: CUDA array interface compliant objects like CuPy, cuDF DataFrame/Series, NumPy ndarray and Pandas DataFrame/Series. * **Returns:** **X_new** : Transformed data
For more information on how to configure cuML’s output type, refer to: [Output Data Type Configuration](../../cuml/index.html.md#output-data-type-configuration).