# KMeans

### *class* cuml.dask.cluster.KMeans(, client=None, verbose=False, n_clusters=8, \*\*kwargs)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/dask/cluster/kmeans.py#L46)

Multi-Node Multi-GPU implementation of KMeans.

This version minimizes data transfer by sharing only
the centroids between workers in each iteration.

Predictions are done embarrassingly parallel, using cuML’s
single-GPU version.

For more information on this implementation, refer to the
documentation for single-GPU K-Means.

* **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.
    ‘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.

  **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.
* **Attributes:**
  **cluster_centers_**
  : The coordinates of the final clusters. This represents of “mean” of
    each data cluster.

### Methods

| [`fit`](#cuml.dask.cluster.KMeans.fit)(X[, sample_weight])                    | Fit a multi-node multi-GPU KMeans model                            |
|---------------------------------------------------------------------------------------------|--------------------------------------------------------------------|
| [`fit_predict`](#cuml.dask.cluster.KMeans.fit_predict)(X[, sample_weight, delayed])   | Compute cluster centers and predict cluster index for each sample. |
| [`fit_transform`](#cuml.dask.cluster.KMeans.fit_transform)(X[, sample_weight, delayed]) | Calls fit followed by transform using a distributed KMeans model   |
| [`predict`](#cuml.dask.cluster.KMeans.predict)(X[, delayed])                      | Predict labels for the input                                       |
| [`score`](#cuml.dask.cluster.KMeans.score)(X[, sample_weight])                  | Computes the inertia score for the trained KMeans centroids.       |
| [`transform`](#cuml.dask.cluster.KMeans.transform)(X[, delayed])                    | Transforms the input into the learned centroid space               |
<!-- !! processed by numpydoc !! -->

#### fit(X, sample_weight=None)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/dask/cluster/kmeans.py#L146)

Fit a multi-node multi-GPU KMeans model

* **Parameters:**
  **X**

  **Training data to cluster.**

  **sample_weight**
  : The weights for each observation in X. If None, all observations
    are assigned equal weight.
    Acceptable formats: cuDF DataFrame, NumPy ndarray, Numba device
    ndarray, cuda array interface compliant array like CuPy

<!-- !! processed by numpydoc !! -->

#### fit_predict(X, sample_weight=None, delayed=True)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/dask/cluster/kmeans.py#L283)

Compute cluster centers and predict cluster index for each sample.

* **Parameters:**
  **X**
  : Data to predict
* **Returns:**
  result: Dask cuDF DataFrame or CuPy backed Dask Array
  : Distributed object containing predictions

<!-- !! processed by numpydoc !! -->

#### fit_transform(X, sample_weight=None, delayed=True)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/dask/cluster/kmeans.py#L321)

Calls fit followed by transform using a distributed KMeans model

* **Parameters:**
  **X**
  : Data to predict

  **delayed**
  : Whether to execute as a delayed task or eager.
* **Returns:**
  result: Dask cuDF DataFrame or CuPy backed Dask Array
  : Distributed object containing the transformed data

<!-- !! processed by numpydoc !! -->

#### get_combined_model()[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/dask/common/base.py#L57)

Return single-GPU model for serialization

* **Returns:**
  **model**
  : yet been trained.

<!-- !! processed by numpydoc !! -->

#### predict(X, delayed=True)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/dask/cluster/kmeans.py#L301)

Predict labels for the input

* **Parameters:**
  **X**
  : Data to predict

  **delayed**
  : Whether to do a lazy prediction (and return Delayed objects) or an
    eagerly executed one.
* **Returns:**
  result: Dask cuDF DataFrame or CuPy backed Dask Array
  : Distributed object containing predictions

<!-- !! processed by numpydoc !! -->

#### score(X, sample_weight=None)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/dask/cluster/kmeans.py#L361)

Computes the inertia score for the trained KMeans centroids.

* **Parameters:**
  **X**
  : Data to score.

  **sample_weight**
  : The weight for each observation. It must have the same row
    partitioning as `X`.
* **Returns:**
  Inertial score

<!-- !! processed by numpydoc !! -->

#### transform(X, delayed=True)[[source]](https://github.com/NVIDIA/cuml/blob/93418baf5/python/cuml/cuml/dask/cluster/kmeans.py#L342)

Transforms the input into the learned centroid space

* **Parameters:**
  **X**
  : Data to predict

  **delayed**
  : Whether to execute as a delayed task or eager.
* **Returns:**
  result: Dask cuDF DataFrame or CuPy backed Dask Array
  : Distributed object containing the transformed data

<!-- !! processed by numpydoc !! -->