DOC Add warning for using `"kmeans++"` init with high-dimensional data
@@ -1188,9 +1188,11 @@ class KMeans(_BaseKMeans):
(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.
+ 'k-means++' : selects initial cluster centroids using sampling based on
+ an empirical probability distribution of the points' contribution to the
+ overall inertia. This technique speeds up convergence, and is
+ theoretically proven to be :math:`\\mathcal{O}(\\log k)`-optimal.
+ See the description of `n_init` for more details.
'random': choose `n_clusters` observations (rows) at random from data
for the initial centroids.
@@ -1202,9 +1204,10 @@ class KMeans(_BaseKMeans):
random state and return an initialization.
n_init : 'auto' or int, 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.
+ Number of times the k-means algorithm is run with different centroid
+ seeds. The final results is the best output of `n_init` consecutive runs
+ in terms of inertia. Several runs are recommended for sparse
+ high-dimensional problems (see :ref:`kmeans_sparse_high_dim`).
When `n_init='auto'`, the number of runs will be 10 if using
`init='random'`, and 1 if using `init='kmeans++'`.
@@ -1663,9 +1666,11 @@ class MiniBatchKMeans(_BaseKMeans):
(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.
+ 'k-means++' : selects initial cluster centroids using sampling based on
+ an empirical probability distribution of the points' contribution to the
+ overall inertia. This technique speeds up convergence, and is
+ theoretically proven to be :math:`\\mathcal{O}(\\log k)`-optimal.
+ See the description of `n_init` for more details.
'random': choose `n_clusters` observations (rows) at random from data
for the initial centroids.
@@ -1729,8 +1734,10 @@ class MiniBatchKMeans(_BaseKMeans):
n_init : 'auto' or int, default=3
Number of random initializations that are tried.
- In contrast to KMeans, the algorithm is only run once, using the
- best of the ``n_init`` initializations as measured by inertia.
+ In contrast to KMeans, the algorithm is only run once, using the best of
+ the `n_init` initializations as measured by inertia. Several runs are
+ recommended for sparse high-dimensional problems (see
+ :ref:`kmeans_sparse_high_dim`).
When `n_init='auto'`, the number of runs will be 3 if using
`init='random'`, and 1 if using `init='kmeans++'`.
