Agglomerative Clustering
Recursively merges the pair of clusters that minimally increases a given linkage distance.
Read more in the User Guide.
The number of clusters to find. It must be None if distance_threshold is not None.
Metric used to compute the linkage. Can be “euclidean”, “l1”, “l2”, “manhattan”, “cosine”, or “precomputed”. If linkage is “ward”, only “euclidean” is accepted. If “precomputed”, a distance matrix (instead of a similarity matrix) is needed as input for the fit method.
Used to cache the output of the computation of the tree. By default, no caching is done. If a string is given, it is the path to the caching directory.
Connectivity matrix. Defines for each sample the neighboring samples following a given structure of the data. This can be a connectivity matrix itself or a callable that transforms the data into a connectivity matrix, such as derived from kneighbors_graph. Default is None, i.e, the hierarchical clustering algorithm is unstructured.
Stop early the construction of the tree at n_clusters. This is useful to decrease computation time if the number of clusters is not small compared to the number of samples. This option is useful only when specifying a connectivity matrix. Note also that when varying the number of clusters and using caching, it may be advantageous to compute the full tree. It must be True if distance_threshold is not None. By default compute_full_tree is “auto”, which is equivalent to True when distance_threshold is not None or that n_clusters is inferior to the maximum between 100 or 0.02 * n_samples. Otherwise, “auto” is equivalent to False.
Which linkage criterion to use. The linkage criterion determines which distance to use between sets of observation. The algorithm will merge the pairs of cluster that minimize this criterion.
New in version 0.20: Added the ‘single’ option
The linkage distance threshold above which, clusters will not be merged. If not None, n_clusters must be None and compute_full_tree must be True.
New in version 0.21.
Computes distances between clusters even if distance_threshold is not used. This can be used to make dendrogram visualization, but introduces a computational and memory overhead.
New in version 0.24.
The number of clusters found by the algorithm. If distance_threshold=None, it will be equal to the given n_clusters.
cluster labels for each point
Number of leaves in the hierarchical tree.
The estimated number of connected components in the graph.
New in version 0.21: n_connected_components_ was added to replace n_components_.
The children of each non-leaf node. Values less than n_samples correspond to leaves of the tree which are the original samples. A node i greater than or equal to n_samples is a non-leaf node and has children children_[i - n_samples]. Alternatively at the i-th iteration, children[i][0] and children[i][1] are merged to form node n_samples + i
Distances between nodes in the corresponding place in children_. Only computed if distance_threshold is used or compute_distances is set to True.
fit(X[, y])
Fit the hierarchical clustering from features, or distance matrix.
fit_predict(X[, y])
Fit the hierarchical clustering from features or distance matrix, and return cluster labels.
get_params([deep])
Get parameters for this estimator.
set_params(**params)
Set the parameters of this estimator.
Fit the hierarchical clustering from features, or distance matrix.
Training instances to cluster, or distances between instances if affinity='precomputed'.
Not used, present here for API consistency by convention.
Fit the hierarchical clustering from features or distance matrix, and return cluster labels.
Training instances to cluster, or distances between instances if affinity='precomputed'.
Not used, present here for API consistency by convention.
Cluster labels.
Get parameters for this estimator.
If True, will return the parameters for this estimator and contained subobjects that are estimators.
Parameter names mapped to their values.
Set the parameters of this estimator.
The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.
Estimator parameters.
Estimator instance.


Agglomerative Clustering
Recursively merges the pair of clusters that minimally increases a given linkage distance.
Read more in the User Guide.
The number of clusters to find. It must be None if distance_threshold is not None.
Metric used to compute the linkage. Can be “euclidean”, “l1”, “l2”, “manhattan”, “cosine”, or “precomputed”. If linkage is “ward”, only “euclidean” is accepted. If “precomputed”, a distance matrix (instead of a similarity matrix) is needed as input for the fit method.
Used to cache the output of the computation of the tree. By default, no caching is done. If a string is given, it is the path to the caching directory.
Connectivity matrix. Defines for each sample the neighboring samples following a given structure of the data. This can be a connectivity matrix itself or a callable that transforms the data into a connectivity matrix, such as derived from kneighbors_graph. Default is None, i.e, the hierarchical clustering algorithm is unstructured.
Stop early the construction of the tree at n_clusters. This is useful to decrease computation time if the number of clusters is not small compared to the number of samples. This option is useful only when specifying a connectivity matrix. Note also that when varying the number of clusters and using caching, it may be advantageous to compute the full tree. It must be True if distance_threshold is not None. By default compute_full_tree is “auto”, which is equivalent to True when distance_threshold is not None or that n_clusters is inferior to the maximum between 100 or 0.02 * n_samples. Otherwise, “auto” is equivalent to False.
Which linkage criterion to use. The linkage criterion determines which distance to use between sets of observation. The algorithm will merge the pairs of cluster that minimize this criterion.
New in version 0.20: Added the ‘single’ option
The linkage distance threshold above which, clusters will not be merged. If not None, n_clusters must be None and compute_full_tree must be True.
New in version 0.21.
Computes distances between clusters even if distance_threshold is not used. This can be used to make dendrogram visualization, but introduces a computational and memory overhead.
New in version 0.24.
The number of clusters found by the algorithm. If distance_threshold=None, it will be equal to the given n_clusters.
cluster labels for each point
Number of leaves in the hierarchical tree.
The estimated number of connected components in the graph.
New in version 0.21: n_connected_components_ was added to replace n_components_.
The children of each non-leaf node. Values less than n_samples correspond to leaves of the tree which are the original samples. A node i greater than or equal to n_samples is a non-leaf node and has children children_[i - n_samples]. Alternatively at the i-th iteration, children[i][0] and children[i][1] are merged to form node n_samples + i
Distances between nodes in the corresponding place in children_. Only computed if distance_threshold is used or compute_distances is set to True.
fit(X[, y])
Fit the hierarchical clustering from features, or distance matrix.
fit_predict(X[, y])
Fit the hierarchical clustering from features or distance matrix, and return cluster labels.
get_params([deep])
Get parameters for this estimator.
set_params(**params)
Set the parameters of this estimator.
Fit the hierarchical clustering from features, or distance matrix.
Training instances to cluster, or distances between instances if affinity='precomputed'.
Not used, present here for API consistency by convention.
Fit the hierarchical clustering from features or distance matrix, and return cluster labels.
Training instances to cluster, or distances between instances if affinity='precomputed'.
Not used, present here for API consistency by convention.
Cluster labels.
Get parameters for this estimator.
If True, will return the parameters for this estimator and contained subobjects that are estimators.
Parameter names mapped to their values.
Set the parameters of this estimator.
The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.
Estimator parameters.
Estimator instance.
Plot Hierarchical Clustering Dendrogram
Agglomerative clustering with and without structure
Various Agglomerative Clustering on a 2D embedding of digits
A demo of structured Ward hierarchical clustering on an image of coins
Hierarchical clustering: structured vs unstructured ward
Agglomerative clustering with different metrics
Inductive Clustering
Comparing different hierarchical linkage methods on toy datasets
Comparing different clustering algorithms on toy datasets


Fit the hierarchical clustering from features, or distance matrix.
Training instances to cluster, or distances between instances if affinity='precomputed'.
Not used, present here for API consistency by convention.


Fit the hierarchical clustering from features or distance matrix, and return cluster labels.
Training instances to cluster, or distances between instances if affinity='precomputed'.
Not used, present here for API consistency by convention.
Cluster labels.


Get parameters for this estimator.
If True, will return the parameters for this estimator and contained subobjects that are estimators.
Parameter names mapped to their values.


Set the parameters of this estimator.
The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.
Estimator parameters.
Estimator instance.


Implements the Birch clustering algorithm.
It is a memory-efficient, online-learning algorithm provided as an alternative to MiniBatchKMeans. It constructs a tree data structure with the cluster centroids being read off the leaf. These can be either the final cluster centroids or can be provided as input to another clustering algorithm such as AgglomerativeClustering.
Read more in the User Guide.
New in version 0.16.
The radius of the subcluster obtained by merging a new sample and the closest subcluster should be lesser than the threshold. Otherwise a new subcluster is started. Setting this value to be very low promotes splitting and vice-versa.
Maximum number of CF subclusters in each node. If a new samples enters such that the number of subclusters exceed the branching_factor then that node is split into two nodes with the subclusters redistributed in each. The parent subcluster of that node is removed and two new subclusters are added as parents of the 2 split nodes.
Number of clusters after the final clustering step, which treats the subclusters from the leaves as new samples.
Whether or not to compute labels for each fit.
Whether or not to make a copy of the given data. If set to False, the initial data will be overwritten.
Root of the CFTree.
Start pointer to all the leaves.
Centroids of all subclusters read directly from the leaves.
Labels assigned to the centroids of the subclusters after they are clustered globally.
Array of labels assigned to the input data. if partial_fit is used instead of fit, they are assigned to the last batch of data.
See also
Alternative implementation that does incremental updates of the centers’ positions using mini-batches.
The tree data structure consists of nodes with each node consisting of a number of subclusters. The maximum number of subclusters in a node is determined by the branching factor. Each subcluster maintains a linear sum, squared sum and the number of samples in that subcluster. In addition, each subcluster can also have a node as its child, if the subcluster is not a member of a leaf node.
For a new point entering the root, it is merged with the subcluster closest to it and the linear sum, squared sum and the number of samples of that subcluster are updated. This is done recursively till the properties of the leaf node are updated.
fit(X[, y])
Build a CF Tree for the input data.
fit_predict(X[, y])
Perform clustering on X and returns cluster labels.
fit_transform(X[, y])
Fit to data, then transform it.
get_params([deep])
Get parameters for this estimator.
partial_fit([X, y])
Online learning.
predict(X)
Predict data using the centroids_ of subclusters.
set_params(**params)
Set the parameters of this estimator.
transform(X)
Transform X into subcluster centroids dimension.
Build a CF Tree for the input data.
Input data.
Not used, present here for API consistency by convention.
Fitted estimator.
Perform clustering on X and returns cluster labels.
Input data.
Not used, present for API consistency by convention.
Cluster labels.
Fit to data, then transform it.
Fits transformer to X and y with optional parameters fit_params and returns a transformed version of X.
Input samples.
Target values (None for unsupervised transformations).
Additional fit parameters.
Transformed array.
Get parameters for this estimator.
If True, will return the parameters for this estimator and contained subobjects that are estimators.
Parameter names mapped to their values.
Online learning. Prevents rebuilding of CFTree from scratch.
Input data. If X is not provided, only the global clustering step is done.
Not used, present here for API consistency by convention.
Fitted estimator.
Predict data using the centroids_ of subclusters.
Avoid computation of the row norms of X.
Input data.
Labelled data.
Set the parameters of this estimator.
The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.
Estimator parameters.
Estimator instance.
Transform X into subcluster centroids dimension.
Each dimension represents the distance from the sample point to each cluster centroid.
Input data.
Transformed data.


Implements the Birch clustering algorithm.
It is a memory-efficient, online-learning algorithm provided as an alternative to MiniBatchKMeans. It constructs a tree data structure with the cluster centroids being read off the leaf. These can be either the final cluster centroids or can be provided as input to another clustering algorithm such as AgglomerativeClustering.
Read more in the User Guide.
New in version 0.16.
The radius of the subcluster obtained by merging a new sample and the closest subcluster should be lesser than the threshold. Otherwise a new subcluster is started. Setting this value to be very low promotes splitting and vice-versa.
Maximum number of CF subclusters in each node. If a new samples enters such that the number of subclusters exceed the branching_factor then that node is split into two nodes with the subclusters redistributed in each. The parent subcluster of that node is removed and two new subclusters are added as parents of the 2 split nodes.
Number of clusters after the final clustering step, which treats the subclusters from the leaves as new samples.
Whether or not to compute labels for each fit.
Whether or not to make a copy of the given data. If set to False, the initial data will be overwritten.
Root of the CFTree.
Start pointer to all the leaves.
Centroids of all subclusters read directly from the leaves.
Labels assigned to the centroids of the subclusters after they are clustered globally.
Array of labels assigned to the input data. if partial_fit is used instead of fit, they are assigned to the last batch of data.
See also
Alternative implementation that does incremental updates of the centers’ positions using mini-batches.
The tree data structure consists of nodes with each node consisting of a number of subclusters. The maximum number of subclusters in a node is determined by the branching factor. Each subcluster maintains a linear sum, squared sum and the number of samples in that subcluster. In addition, each subcluster can also have a node as its child, if the subcluster is not a member of a leaf node.
For a new point entering the root, it is merged with the subcluster closest to it and the linear sum, squared sum and the number of samples of that subcluster are updated. This is done recursively till the properties of the leaf node are updated.
fit(X[, y])
Build a CF Tree for the input data.
fit_predict(X[, y])
Perform clustering on X and returns cluster labels.
fit_transform(X[, y])
Fit to data, then transform it.
get_params([deep])
Get parameters for this estimator.
partial_fit([X, y])
Online learning.
predict(X)
Predict data using the centroids_ of subclusters.
set_params(**params)
Set the parameters of this estimator.
transform(X)
Transform X into subcluster centroids dimension.
Build a CF Tree for the input data.
Input data.
Not used, present here for API consistency by convention.
Fitted estimator.
Perform clustering on X and returns cluster labels.
Input data.
Not used, present for API consistency by convention.
Cluster labels.
Fit to data, then transform it.
Fits transformer to X and y with optional parameters fit_params and returns a transformed version of X.
Input samples.
Target values (None for unsupervised transformations).
Additional fit parameters.
Transformed array.
Get parameters for this estimator.
If True, will return the parameters for this estimator and contained subobjects that are estimators.
Parameter names mapped to their values.
Online learning. Prevents rebuilding of CFTree from scratch.
Input data. If X is not provided, only the global clustering step is done.
Not used, present here for API consistency by convention.
Fitted estimator.
Predict data using the centroids_ of subclusters.
Avoid computation of the row norms of X.
Input data.
Labelled data.
Set the parameters of this estimator.
The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.
Estimator parameters.
Estimator instance.
Transform X into subcluster centroids dimension.
Each dimension represents the distance from the sample point to each cluster centroid.
Input data.
Transformed data.
Compare BIRCH and MiniBatchKMeans
Comparing different clustering algorithms on toy datasets


Build a CF Tree for the input data.
Input data.
Not used, present here for API consistency by convention.
Fitted estimator.


Perform clustering on X and returns cluster labels.
Input data.
Not used, present for API consistency by convention.
Cluster labels.


Fit to data, then transform it.
Fits transformer to X and y with optional parameters fit_params and returns a transformed version of X.
Input samples.
Target values (None for unsupervised transformations).
Additional fit parameters.
Transformed array.


Online learning. Prevents rebuilding of CFTree from scratch.
Input data. If X is not provided, only the global clustering step is done.
Not used, present here for API consistency by convention.
Fitted estimator.


Predict data using the centroids_ of subclusters.
Avoid computation of the row norms of X.
Input data.
Labelled data.


Transform X into subcluster centroids dimension.
Each dimension represents the distance from the sample point to each cluster centroid.
Input data.
Transformed data.


Performs DBSCAN extraction for an arbitrary epsilon.
Extracting the clusters runs in linear time. Note that this results in labels_ which are close to a DBSCAN with similar settings and eps, only if eps is close to max_eps.
Reachability distances calculated by OPTICS (reachability_)
Distances at which points become core (core_distances_)
OPTICS ordered point indices (ordering_)
DBSCAN eps parameter. Must be set to < max_eps. Results will be close to DBSCAN algorithm if eps and max_eps are close to one another.
The estimated labels.


Automatically extract clusters according to the Xi-steep method.
Reachability distances calculated by OPTICS (reachability_)
Predecessors calculated by OPTICS.
OPTICS ordered point indices (ordering_)
The same as the min_samples given to OPTICS. Up and down steep regions can’t have more then min_samples consecutive non-steep points. Expressed as an absolute number or a fraction of the number of samples (rounded to be at least 2).
Minimum number of samples in an OPTICS cluster, expressed as an absolute number or a fraction of the number of samples (rounded to be at least 2). If None, the value of min_samples is used instead.
Determines the minimum steepness on the reachability plot that constitutes a cluster boundary. For example, an upwards point in the reachability plot is defined by the ratio from one point to its successor being at most 1-xi.
Correct clusters based on the calculated predecessors.
The labels assigned to samples. Points which are not included in any cluster are labeled as -1.
The list of clusters in the form of [start, end] in each row, with all indices inclusive. The clusters are ordered according to (end,
-start) (ascending) so that larger clusters encompassing smaller clusters come after such nested smaller clusters. Since labels does not reflect the hierarchy, usually len(clusters) >
np.unique(labels).


Computes the OPTICS reachability graph.
Read more in the User Guide.
A feature array, or array of distances between samples if metric=’precomputed’
The number of samples in a neighborhood for a point to be considered as a core point. Expressed as an absolute number or a fraction of the number of samples (rounded to be at least 2).
The maximum distance between two samples for one to be considered as in the neighborhood of the other. Default value of np.inf will identify clusters across all scales; reducing max_eps will result in shorter run times.
Metric to use for distance computation. Any metric from scikit-learn or scipy.spatial.distance can be used.
If metric is a callable function, it is called on each pair of instances (rows) and the resulting value recorded. The callable should take two arrays as input and return one value indicating the distance between them. This works for Scipy’s metrics, but is less efficient than passing the metric name as a string. If metric is “precomputed”, X is assumed to be a distance matrix and must be square.
Valid values for metric are:
See the documentation for scipy.spatial.distance for details on these metrics.
Parameter for the Minkowski metric from pairwise_distances. When p = 1, this is equivalent to using manhattan_distance (l1), and euclidean_distance (l2) for p = 2. For arbitrary p, minkowski_distance (l_p) is used.
Additional keyword arguments for the metric function.
Algorithm used to compute the nearest neighbors:
Note: fitting on sparse input will override the setting of this parameter, using brute force.
Leaf size passed to BallTree or KDTree. This can affect the speed of the construction and query, as well as the memory required to store the tree. The optimal value depends on the nature of the problem.
The number of parallel jobs to run for neighbors search. None means 1 unless in a joblib.parallel_backend context. -1 means using all processors. See Glossary for more details.
The cluster ordered list of sample indices.
Distance at which each sample becomes a core point, indexed by object order. Points which will never be core have a distance of inf. Use clust.core_distances_[clust.ordering_] to access in cluster order.
Reachability distances per sample, indexed by object order. Use clust.reachability_[clust.ordering_] to access in cluster order.
Point that a sample was reached from, indexed by object order. Seed points have a predecessor of -1.
Ankerst, Mihael, Markus M. Breunig, Hans-Peter Kriegel, and Jörg Sander. “OPTICS: ordering points to identify the clustering structure.” ACM SIGMOD Record 28, no. 2 (1999): 49-60.


Perform DBSCAN clustering from vector array or distance matrix.
DBSCAN - Density-Based Spatial Clustering of Applications with Noise. Finds core samples of high density and expands clusters from them. Good for data which contains clusters of similar density.
Read more in the User Guide.
The maximum distance between two samples for one to be considered as in the neighborhood of the other. This is not a maximum bound on the distances of points within a cluster. This is the most important DBSCAN parameter to choose appropriately for your data set and distance function.
The number of samples (or total weight) in a neighborhood for a point to be considered as a core point. This includes the point itself.
The metric to use when calculating distance between instances in a feature array. If metric is a string or callable, it must be one of the options allowed by sklearn.metrics.pairwise_distances for its metric parameter. If metric is “precomputed”, X is assumed to be a distance matrix and must be square. X may be a Glossary, in which case only “nonzero” elements may be considered neighbors for DBSCAN.
New in version 0.17: metric precomputed to accept precomputed sparse matrix.
Additional keyword arguments for the metric function.
New in version 0.19.
The algorithm to be used by the NearestNeighbors module to compute pointwise distances and find nearest neighbors. See NearestNeighbors module documentation for details.
Leaf size passed to BallTree or cKDTree. This can affect the speed of the construction and query, as well as the memory required to store the tree. The optimal value depends on the nature of the problem.
The power of the Minkowski metric to be used to calculate distance between points. If None, then p=2 (equivalent to the Euclidean distance).
The number of parallel jobs to run. None means 1 unless in a joblib.parallel_backend context. -1 means using all processors. See Glossary for more details.
Indices of core samples.
Copy of each core sample found by training.
Cluster labels for each point in the dataset given to fit(). Noisy samples are given the label -1.
See also
A similar clustering at multiple values of eps. Our implementation is optimized for memory usage.
For an example, see examples/cluster/plot_dbscan.py.
This implementation bulk-computes all neighborhood queries, which increases the memory complexity to O(n.d) where d is the average number of neighbors, while original DBSCAN had memory complexity O(n). It may attract a higher memory complexity when querying these nearest neighborhoods, depending on the algorithm.
One way to avoid the query complexity is to pre-compute sparse neighborhoods in chunks using NearestNeighbors.radius_neighbors_graph with mode='distance', then using metric='precomputed' here.
Another way to reduce memory and computation time is to remove (near-)duplicate points and use sample_weight instead.
cluster.OPTICS provides a similar clustering with lower memory usage.
Ester, M., H. P. Kriegel, J. Sander, and X. Xu, “A Density-Based Algorithm for Discovering Clusters in Large Spatial Databases with Noise”. In: Proceedings of the 2nd International Conference on Knowledge Discovery and Data Mining, Portland, OR, AAAI Press, pp. 226-231. 1996
Schubert, E., Sander, J., Ester, M., Kriegel, H. P., & Xu, X. (2017). DBSCAN revisited, revisited: why and how you should (still) use DBSCAN. ACM Transactions on Database Systems (TODS), 42(3), 19.
fit(X[, y, sample_weight])
Perform DBSCAN clustering from features, or distance matrix.
fit_predict(X[, y, sample_weight])
Perform DBSCAN clustering from features or distance matrix, and return cluster labels.
get_params([deep])
Get parameters for this estimator.
set_params(**params)
Set the parameters of this estimator.
Perform DBSCAN clustering from features, or distance matrix.
Training instances to cluster, or distances between instances if metric='precomputed'. If a sparse matrix is provided, it will be converted into a sparse csr_matrix.
Weight of each sample, such that a sample with a weight of at least min_samples is by itself a core sample; a sample with a negative weight may inhibit its eps-neighbor from being core. Note that weights are absolute, and default to 1.
Not used, present here for API consistency by convention.
Perform DBSCAN clustering from features or distance matrix, and return cluster labels.
Training instances to cluster, or distances between instances if metric='precomputed'. If a sparse matrix is provided, it will be converted into a sparse csr_matrix.
Weight of each sample, such that a sample with a weight of at least min_samples is by itself a core sample; a sample with a negative weight may inhibit its eps-neighbor from being core. Note that weights are absolute, and default to 1.
Not used, present here for API consistency by convention.
Cluster labels. Noisy samples are given the label -1.
Get parameters for this estimator.
If True, will return the parameters for this estimator and contained subobjects that are estimators.
Parameter names mapped to their values.
Set the parameters of this estimator.
The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.
Estimator parameters.
Estimator instance.


Perform DBSCAN clustering from vector array or distance matrix.
DBSCAN - Density-Based Spatial Clustering of Applications with Noise. Finds core samples of high density and expands clusters from them. Good for data which contains clusters of similar density.
Read more in the User Guide.
The maximum distance between two samples for one to be considered as in the neighborhood of the other. This is not a maximum bound on the distances of points within a cluster. This is the most important DBSCAN parameter to choose appropriately for your data set and distance function.
The number of samples (or total weight) in a neighborhood for a point to be considered as a core point. This includes the point itself.
The metric to use when calculating distance between instances in a feature array. If metric is a string or callable, it must be one of the options allowed by sklearn.metrics.pairwise_distances for its metric parameter. If metric is “precomputed”, X is assumed to be a distance matrix and must be square. X may be a Glossary, in which case only “nonzero” elements may be considered neighbors for DBSCAN.
New in version 0.17: metric precomputed to accept precomputed sparse matrix.
Additional keyword arguments for the metric function.
New in version 0.19.
The algorithm to be used by the NearestNeighbors module to compute pointwise distances and find nearest neighbors. See NearestNeighbors module documentation for details.
Leaf size passed to BallTree or cKDTree. This can affect the speed of the construction and query, as well as the memory required to store the tree. The optimal value depends on the nature of the problem.
The power of the Minkowski metric to be used to calculate distance between points. If None, then p=2 (equivalent to the Euclidean distance).
The number of parallel jobs to run. None means 1 unless in a joblib.parallel_backend context. -1 means using all processors. See Glossary for more details.
Indices of core samples.
Copy of each core sample found by training.
Cluster labels for each point in the dataset given to fit(). Noisy samples are given the label -1.
See also
A similar clustering at multiple values of eps. Our implementation is optimized for memory usage.
For an example, see examples/cluster/plot_dbscan.py.
This implementation bulk-computes all neighborhood queries, which increases the memory complexity to O(n.d) where d is the average number of neighbors, while original DBSCAN had memory complexity O(n). It may attract a higher memory complexity when querying these nearest neighborhoods, depending on the algorithm.
One way to avoid the query complexity is to pre-compute sparse neighborhoods in chunks using NearestNeighbors.radius_neighbors_graph with mode='distance', then using metric='precomputed' here.
Another way to reduce memory and computation time is to remove (near-)duplicate points and use sample_weight instead.
cluster.OPTICS provides a similar clustering with lower memory usage.
Ester, M., H. P. Kriegel, J. Sander, and X. Xu, “A Density-Based Algorithm for Discovering Clusters in Large Spatial Databases with Noise”. In: Proceedings of the 2nd International Conference on Knowledge Discovery and Data Mining, Portland, OR, AAAI Press, pp. 226-231. 1996
Schubert, E., Sander, J., Ester, M., Kriegel, H. P., & Xu, X. (2017). DBSCAN revisited, revisited: why and how you should (still) use DBSCAN. ACM Transactions on Database Systems (TODS), 42(3), 19.
fit(X[, y, sample_weight])
Perform DBSCAN clustering from features, or distance matrix.
fit_predict(X[, y, sample_weight])
Perform DBSCAN clustering from features or distance matrix, and return cluster labels.
get_params([deep])
Get parameters for this estimator.
set_params(**params)
Set the parameters of this estimator.
Perform DBSCAN clustering from features, or distance matrix.
Training instances to cluster, or distances between instances if metric='precomputed'. If a sparse matrix is provided, it will be converted into a sparse csr_matrix.
Weight of each sample, such that a sample with a weight of at least min_samples is by itself a core sample; a sample with a negative weight may inhibit its eps-neighbor from being core. Note that weights are absolute, and default to 1.
Not used, present here for API consistency by convention.
Perform DBSCAN clustering from features or distance matrix, and return cluster labels.
Training instances to cluster, or distances between instances if metric='precomputed'. If a sparse matrix is provided, it will be converted into a sparse csr_matrix.
Weight of each sample, such that a sample with a weight of at least min_samples is by itself a core sample; a sample with a negative weight may inhibit its eps-neighbor from being core. Note that weights are absolute, and default to 1.
Not used, present here for API consistency by convention.
Cluster labels. Noisy samples are given the label -1.
Get parameters for this estimator.
If True, will return the parameters for this estimator and contained subobjects that are estimators.
Parameter names mapped to their values.
Set the parameters of this estimator.
The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.
Estimator parameters.
Estimator instance.
Demo of DBSCAN clustering algorithm
Comparing different clustering algorithms on toy datasets


Perform DBSCAN clustering from vector array or distance matrix.
Read more in the User Guide.
A feature array, or array of distances between samples if metric='precomputed'.
The maximum distance between two samples for one to be considered as in the neighborhood of the other. This is not a maximum bound on the distances of points within a cluster. This is the most important DBSCAN parameter to choose appropriately for your data set and distance function.
The number of samples (or total weight) in a neighborhood for a point to be considered as a core point. This includes the point itself.
The metric to use when calculating distance between instances in a feature array. If metric is a string or callable, it must be one of the options allowed by sklearn.metrics.pairwise_distances for its metric parameter. If metric is “precomputed”, X is assumed to be a distance matrix and must be square during fit. X may be a sparse graph, in which case only “nonzero” elements may be considered neighbors.
Additional keyword arguments for the metric function.
New in version 0.19.
The algorithm to be used by the NearestNeighbors module to compute pointwise distances and find nearest neighbors. See NearestNeighbors module documentation for details.
Leaf size passed to BallTree or cKDTree. This can affect the speed of the construction and query, as well as the memory required to store the tree. The optimal value depends on the nature of the problem.
The power of the Minkowski metric to be used to calculate distance between points.
Weight of each sample, such that a sample with a weight of at least min_samples is by itself a core sample; a sample with negative weight may inhibit its eps-neighbor from being core. Note that weights are absolute, and default to 1.
The number of parallel jobs to run for neighbors search. None means 1 unless in a joblib.parallel_backend context. -1 means using all processors. See Glossary for more details. If precomputed distance are used, parallel execution is not available and thus n_jobs will have no effect.
Indices of core samples.
Cluster labels for each point. Noisy samples are given the label -1.
See also
An estimator interface for this clustering algorithm.
A similar estimator interface clustering at multiple values of eps. Our implementation is optimized for memory usage.
For an example, see examples/cluster/plot_dbscan.py.
This implementation bulk-computes all neighborhood queries, which increases the memory complexity to O(n.d) where d is the average number of neighbors, while original DBSCAN had memory complexity O(n). It may attract a higher memory complexity when querying these nearest neighborhoods, depending on the algorithm.
One way to avoid the query complexity is to pre-compute sparse neighborhoods in chunks using NearestNeighbors.radius_neighbors_graph with mode='distance', then using metric='precomputed' here.
Another way to reduce memory and computation time is to remove (near-)duplicate points and use sample_weight instead.
cluster.optics provides a similar clustering with lower memory usage.
Ester, M., H. P. Kriegel, J. Sander, and X. Xu, “A Density-Based Algorithm for Discovering Clusters in Large Spatial Databases with Noise”. In: Proceedings of the 2nd International Conference on Knowledge Discovery and Data Mining, Portland, OR, AAAI Press, pp. 226-231. 1996
Schubert, E., Sander, J., Ester, M., Kriegel, H. P., & Xu, X. (2017). DBSCAN revisited, revisited: why and how you should (still) use DBSCAN. ACM Transactions on Database Systems (TODS), 42(3), 19.


Perform DBSCAN clustering from features, or distance matrix.
Training instances to cluster, or distances between instances if metric='precomputed'. If a sparse matrix is provided, it will be converted into a sparse csr_matrix.
Weight of each sample, such that a sample with a weight of at least min_samples is by itself a core sample; a sample with a negative weight may inhibit its eps-neighbor from being core. Note that weights are absolute, and default to 1.
Not used, present here for API consistency by convention.


Perform DBSCAN clustering from features or distance matrix, and return cluster labels.
Training instances to cluster, or distances between instances if metric='precomputed'. If a sparse matrix is provided, it will be converted into a sparse csr_matrix.
Weight of each sample, such that a sample with a weight of at least min_samples is by itself a core sample; a sample with a negative weight may inhibit its eps-neighbor from being core. Note that weights are absolute, and default to 1.
Not used, present here for API consistency by convention.
Cluster labels. Noisy samples are given the label -1.


Get parameters for this estimator.
If True, will return the parameters for this estimator and contained subobjects that are estimators.
Parameter names mapped to their values.


Set the parameters of this estimator.
The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.
Estimator parameters.
Estimator instance.


Estimate the bandwidth to use with the mean-shift algorithm.
That this function takes time at least quadratic in n_samples. For large datasets, it’s wise to set that parameter to a small value.
Input points.
should be between [0, 1] 0.5 means that the median of all pairwise distances is used.
The number of samples to use. If not given, all samples are used.
The generator used to randomly select the samples from input points for bandwidth estimation. Use an int to make the randomness deterministic. See Glossary.
The number of parallel jobs to run for neighbors search. None means 1 unless in a joblib.parallel_backend context. -1 means using all processors. See Glossary for more details.
The bandwidth parameter.


Agglomerate features.
Similar to AgglomerativeClustering, but recursively merges features instead of samples.
Read more in the User Guide.
The number of clusters to find. It must be None if distance_threshold is not None.
Metric used to compute the linkage. Can be “euclidean”, “l1”, “l2”, “manhattan”, “cosine”, or ‘precomputed’. If linkage is “ward”, only “euclidean” is accepted.
Used to cache the output of the computation of the tree. By default, no caching is done. If a string is given, it is the path to the caching directory.
Connectivity matrix. Defines for each feature the neighboring features following a given structure of the data. This can be a connectivity matrix itself or a callable that transforms the data into a connectivity matrix, such as derived from kneighbors_graph. Default is None, i.e, the hierarchical clustering algorithm is unstructured.
Stop early the construction of the tree at n_clusters. This is useful to decrease computation time if the number of clusters is not small compared to the number of features. This option is useful only when specifying a connectivity matrix. Note also that when varying the number of clusters and using caching, it may be advantageous to compute the full tree. It must be True if distance_threshold is not None. By default compute_full_tree is “auto”, which is equivalent to True when distance_threshold is not None or that n_clusters is inferior to the maximum between 100 or 0.02 * n_samples. Otherwise, “auto” is equivalent to False.
Which linkage criterion to use. The linkage criterion determines which distance to use between sets of features. The algorithm will merge the pairs of cluster that minimize this criterion.
This combines the values of agglomerated features into a single value, and should accept an array of shape [M, N] and the keyword argument axis=1, and reduce it to an array of size [M].
The linkage distance threshold above which, clusters will not be merged. If not None, n_clusters must be None and compute_full_tree must be True.
New in version 0.21.
Computes distances between clusters even if distance_threshold is not used. This can be used to make dendrogram visualization, but introduces a computational and memory overhead.
New in version 0.24.
The number of clusters found by the algorithm. If distance_threshold=None, it will be equal to the given n_clusters.
cluster labels for each feature.
Number of leaves in the hierarchical tree.
The estimated number of connected components in the graph.
New in version 0.21: n_connected_components_ was added to replace n_components_.
The children of each non-leaf node. Values less than n_features correspond to leaves of the tree which are the original samples. A node i greater than or equal to n_features is a non-leaf node and has children children_[i - n_features]. Alternatively at the i-th iteration, children[i][0] and children[i][1] are merged to form node n_features + i
Distances between nodes in the corresponding place in children_. Only computed if distance_threshold is used or compute_distances is set to True.
fit(X[, y])
Fit the hierarchical clustering on the data
fit_transform(X[, y])
Fit to data, then transform it.
get_params([deep])
Get parameters for this estimator.
inverse_transform(Xred)
Inverse the transformation.
set_params(**params)
Set the parameters of this estimator.
transform(X)
Transform a new matrix using the built clustering
Fit the hierarchical clustering on the data
The data
Fit the hierarchical clustering from features or distance matrix, and return cluster labels.
Training instances to cluster, or distances between instances if affinity='precomputed'.
Not used, present here for API consistency by convention.
Cluster labels.
Fit to data, then transform it.
Fits transformer to X and y with optional parameters fit_params and returns a transformed version of X.
Input samples.
Target values (None for unsupervised transformations).
Additional fit parameters.
Transformed array.
Get parameters for this estimator.
If True, will return the parameters for this estimator and contained subobjects that are estimators.
Parameter names mapped to their values.
Inverse the transformation. Return a vector of size nb_features with the values of Xred assigned to each group of features
The values to be assigned to each cluster of samples
A vector of size n_samples with the values of Xred assigned to each of the cluster of samples.
Set the parameters of this estimator.
The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.
Estimator parameters.
Estimator instance.
Transform a new matrix using the built clustering
A M by N array of M observations in N dimensions or a length M array of M one-dimensional observations.
The pooled values for each feature cluster.


Agglomerate features.
Similar to AgglomerativeClustering, but recursively merges features instead of samples.
Read more in the User Guide.
The number of clusters to find. It must be None if distance_threshold is not None.
Metric used to compute the linkage. Can be “euclidean”, “l1”, “l2”, “manhattan”, “cosine”, or ‘precomputed’. If linkage is “ward”, only “euclidean” is accepted.
Used to cache the output of the computation of the tree. By default, no caching is done. If a string is given, it is the path to the caching directory.
Connectivity matrix. Defines for each feature the neighboring features following a given structure of the data. This can be a connectivity matrix itself or a callable that transforms the data into a connectivity matrix, such as derived from kneighbors_graph. Default is None, i.e, the hierarchical clustering algorithm is unstructured.
Stop early the construction of the tree at n_clusters. This is useful to decrease computation time if the number of clusters is not small compared to the number of features. This option is useful only when specifying a connectivity matrix. Note also that when varying the number of clusters and using caching, it may be advantageous to compute the full tree. It must be True if distance_threshold is not None. By default compute_full_tree is “auto”, which is equivalent to True when distance_threshold is not None or that n_clusters is inferior to the maximum between 100 or 0.02 * n_samples. Otherwise, “auto” is equivalent to False.
Which linkage criterion to use. The linkage criterion determines which distance to use between sets of features. The algorithm will merge the pairs of cluster that minimize this criterion.
This combines the values of agglomerated features into a single value, and should accept an array of shape [M, N] and the keyword argument axis=1, and reduce it to an array of size [M].
The linkage distance threshold above which, clusters will not be merged. If not None, n_clusters must be None and compute_full_tree must be True.
New in version 0.21.
Computes distances between clusters even if distance_threshold is not used. This can be used to make dendrogram visualization, but introduces a computational and memory overhead.
New in version 0.24.
The number of clusters found by the algorithm. If distance_threshold=None, it will be equal to the given n_clusters.
cluster labels for each feature.
Number of leaves in the hierarchical tree.
The estimated number of connected components in the graph.
New in version 0.21: n_connected_components_ was added to replace n_components_.
The children of each non-leaf node. Values less than n_features correspond to leaves of the tree which are the original samples. A node i greater than or equal to n_features is a non-leaf node and has children children_[i - n_features]. Alternatively at the i-th iteration, children[i][0] and children[i][1] are merged to form node n_features + i
Distances between nodes in the corresponding place in children_. Only computed if distance_threshold is used or compute_distances is set to True.
fit(X[, y])
Fit the hierarchical clustering on the data
fit_transform(X[, y])
Fit to data, then transform it.
get_params([deep])
Get parameters for this estimator.
inverse_transform(Xred)
Inverse the transformation.
set_params(**params)
Set the parameters of this estimator.
transform(X)
Transform a new matrix using the built clustering
Fit the hierarchical clustering on the data
The data
Fit the hierarchical clustering from features or distance matrix, and return cluster labels.
Training instances to cluster, or distances between instances if affinity='precomputed'.
Not used, present here for API consistency by convention.
Cluster labels.
Fit to data, then transform it.
Fits transformer to X and y with optional parameters fit_params and returns a transformed version of X.
Input samples.
Target values (None for unsupervised transformations).
Additional fit parameters.
Transformed array.
Get parameters for this estimator.
If True, will return the parameters for this estimator and contained subobjects that are estimators.
Parameter names mapped to their values.
Inverse the transformation. Return a vector of size nb_features with the values of Xred assigned to each group of features
The values to be assigned to each cluster of samples
A vector of size n_samples with the values of Xred assigned to each of the cluster of samples.
Set the parameters of this estimator.
The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.
Estimator parameters.
Estimator instance.
Transform a new matrix using the built clustering
A M by N array of M observations in N dimensions or a length M array of M one-dimensional observations.
The pooled values for each feature cluster.
Feature agglomeration
Feature agglomeration vs. univariate selection


Fit the hierarchical clustering on the data
The data


Fit the hierarchical clustering from features or distance matrix, and return cluster labels.
Training instances to cluster, or distances between instances if affinity='precomputed'.
Not used, present here for API consistency by convention.
Cluster labels.


Fit to data, then transform it.
Fits transformer to X and y with optional parameters fit_params and returns a transformed version of X.
Input samples.
Target values (None for unsupervised transformations).
Additional fit parameters.
Transformed array.


Inverse the transformation. Return a vector of size nb_features with the values of Xred assigned to each group of features
The values to be assigned to each cluster of samples
A vector of size n_samples with the values of Xred assigned to each of the cluster of samples.


Transform a new matrix using the built clustering
A M by N array of M observations in N dimensions or a length M array of M one-dimensional observations.
The pooled values for each feature cluster.


K-Means clustering.
Read more in the User Guide.
The number of clusters to form as well as the number of centroids to generate.
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.
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.
Maximum number of iterations of the k-means algorithm for a single run.
Relative tolerance with regards to Frobenius norm of the difference in the cluster centers of two consecutive iterations to declare convergence.
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.
True : always precompute distances.
False : never precompute distances.
Deprecated since version 0.23: ‘precompute_distances’ was deprecated in version 0.22 and will be removed in 1.0 (renaming of 0.25). It has no effect.
Verbosity mode.
Determines random number generation for centroid initialization. Use an int to make the randomness deterministic. See Glossary.
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.
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.
None or -1 means using all processors.
Deprecated since version 0.23: n_jobs was deprecated in version 0.23 and will be removed in 1.0 (renaming of 0.25).
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
Coordinates of cluster centers. If the algorithm stops before fully converging (see tol and max_iter), these will not be consistent with labels_.
Labels of each point
Sum of squared distances of samples to their closest cluster center.
Number of iterations run.
See also
Alternative online implementation that does incremental updates of the centers positions using mini-batches. For large scale learning (say n_samples > 10k) MiniBatchKMeans is probably much faster than the default batch implementation.
The k-means problem is solved using either Lloyd’s or Elkan’s algorithm.
The average complexity is given by O(k n T), were 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.
fit(X[, y, sample_weight])
Compute k-means clustering.
fit_predict(X[, y, sample_weight])
Compute cluster centers and predict cluster index for each sample.
fit_transform(X[, y, sample_weight])
Compute clustering and transform X to cluster-distance space.
get_params([deep])
Get parameters for this estimator.
predict(X[, sample_weight])
Predict the closest cluster each sample in X belongs to.
score(X[, y, sample_weight])
Opposite of the value of X on the K-means objective.
set_params(**params)
Set the parameters of this estimator.
transform(X)
Transform X to a cluster-distance space.
Compute k-means clustering.
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.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight.
New in version 0.20.
Fitted estimator.
Compute cluster centers and predict cluster index for each sample.
Convenience method; equivalent to calling fit(X) followed by predict(X).
New data to transform.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight.
Index of the cluster each sample belongs to.
Compute clustering and transform X to cluster-distance space.
Equivalent to fit(X).transform(X), but more efficiently implemented.
New data to transform.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight.
X transformed in the new space.
Get parameters for this estimator.
If True, will return the parameters for this estimator and contained subobjects that are estimators.
Parameter names mapped to their values.
Predict the closest cluster each sample in X belongs to.
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.
New data to predict.
The weights for each observation in X. If None, all observations are assigned equal weight.
Index of the cluster each sample belongs to.
Opposite of the value of X on the K-means objective.
New data.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight.
Opposite of the value of X on the K-means objective.
Set the parameters of this estimator.
The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.
Estimator parameters.
Estimator instance.
Transform X to a cluster-distance space.
In the new space, each dimension is the distance to the cluster centers. Note that even if X is sparse, the array returned by transform will typically be dense.
New data to transform.
X transformed in the new space.


K-Means clustering.
Read more in the User Guide.
The number of clusters to form as well as the number of centroids to generate.
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.
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.
Maximum number of iterations of the k-means algorithm for a single run.
Relative tolerance with regards to Frobenius norm of the difference in the cluster centers of two consecutive iterations to declare convergence.
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.
True : always precompute distances.
False : never precompute distances.
Deprecated since version 0.23: ‘precompute_distances’ was deprecated in version 0.22 and will be removed in 1.0 (renaming of 0.25). It has no effect.
Verbosity mode.
Determines random number generation for centroid initialization. Use an int to make the randomness deterministic. See Glossary.
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.
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.
None or -1 means using all processors.
Deprecated since version 0.23: n_jobs was deprecated in version 0.23 and will be removed in 1.0 (renaming of 0.25).
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
Coordinates of cluster centers. If the algorithm stops before fully converging (see tol and max_iter), these will not be consistent with labels_.
Labels of each point
Sum of squared distances of samples to their closest cluster center.
Number of iterations run.
See also
Alternative online implementation that does incremental updates of the centers positions using mini-batches. For large scale learning (say n_samples > 10k) MiniBatchKMeans is probably much faster than the default batch implementation.
The k-means problem is solved using either Lloyd’s or Elkan’s algorithm.
The average complexity is given by O(k n T), were 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.
fit(X[, y, sample_weight])
Compute k-means clustering.
fit_predict(X[, y, sample_weight])
Compute cluster centers and predict cluster index for each sample.
fit_transform(X[, y, sample_weight])
Compute clustering and transform X to cluster-distance space.
get_params([deep])
Get parameters for this estimator.
predict(X[, sample_weight])
Predict the closest cluster each sample in X belongs to.
score(X[, y, sample_weight])
Opposite of the value of X on the K-means objective.
set_params(**params)
Set the parameters of this estimator.
transform(X)
Transform X to a cluster-distance space.
Compute k-means clustering.
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.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight.
New in version 0.20.
Fitted estimator.
Compute cluster centers and predict cluster index for each sample.
Convenience method; equivalent to calling fit(X) followed by predict(X).
New data to transform.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight.
Index of the cluster each sample belongs to.
Compute clustering and transform X to cluster-distance space.
Equivalent to fit(X).transform(X), but more efficiently implemented.
New data to transform.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight.
X transformed in the new space.
Get parameters for this estimator.
If True, will return the parameters for this estimator and contained subobjects that are estimators.
Parameter names mapped to their values.
Predict the closest cluster each sample in X belongs to.
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.
New data to predict.
The weights for each observation in X. If None, all observations are assigned equal weight.
Index of the cluster each sample belongs to.
Opposite of the value of X on the K-means objective.
New data.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight.
Opposite of the value of X on the K-means objective.
Set the parameters of this estimator.
The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.
Estimator parameters.
Estimator instance.
Transform X to a cluster-distance space.
In the new space, each dimension is the distance to the cluster centers. Note that even if X is sparse, the array returned by transform will typically be dense.
New data to transform.
X transformed in the new space.
Release Highlights for scikit-learn 0.23
Demonstration of k-means assumptions
Vector Quantization Example
K-means Clustering
Color Quantization using K-Means
Empirical evaluation of the impact of k-means initialization
Comparison of the K-Means and MiniBatchKMeans clustering algorithms
A demo of K-Means clustering on the handwritten digits data
Selecting the number of clusters with silhouette analysis on KMeans clustering
Clustering text documents using k-means


Compute k-means clustering.
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.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight.
New in version 0.20.
Fitted estimator.


Compute cluster centers and predict cluster index for each sample.
Convenience method; equivalent to calling fit(X) followed by predict(X).
New data to transform.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight.
Index of the cluster each sample belongs to.


Compute clustering and transform X to cluster-distance space.
Equivalent to fit(X).transform(X), but more efficiently implemented.
New data to transform.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight.
X transformed in the new space.


Predict the closest cluster each sample in X belongs to.
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.
New data to predict.
The weights for each observation in X. If None, all observations are assigned equal weight.
Index of the cluster each sample belongs to.


Opposite of the value of X on the K-means objective.
New data.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight.
Opposite of the value of X on the K-means objective.


Transform X to a cluster-distance space.
In the new space, each dimension is the distance to the cluster centers. Note that even if X is sparse, the array returned by transform will typically be dense.
New data to transform.
X transformed in the new space.


Init n_clusters seeds according to k-means++
New in version 0.24.
The data to pick seeds from.
The number of centroids to initialize
Squared Euclidean norm of each data point.
Determines random number generation for centroid initialization. Pass an int for reproducible output across multiple function calls. See Glossary.
The number of seeding trials for each center (except the first), of which the one reducing inertia the most is greedily chosen. Set to None to make the number of trials depend logarithmically on the number of seeds (2+log(k)).
The inital centers for k-means.
The index location of the chosen centers in the data array X. For a given index and center, X[index] = center.
Selects initial cluster centers for k-mean clustering in a smart way to speed up convergence. see: Arthur, D. and Vassilvitskii, S. “k-means++: the advantages of careful seeding”. ACM-SIAM symposium on Discrete algorithms. 2007


K-means clustering algorithm.
Read more in the User Guide.
The observations 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.
The number of clusters to form as well as the number of centroids to generate.
The weights for each observation in X. If None, all observations are assigned equal weight.
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.
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.
True : always precompute distances
False : never precompute distances
Deprecated since version 0.23: ‘precompute_distances’ was deprecated in version 0.23 and will be removed in 1.0 (renaming of 0.25). It has no effect.
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.
Maximum number of iterations of the k-means algorithm to run.
Verbosity mode.
Relative tolerance with regards to Frobenius norm of the difference in the cluster centers of two consecutive iterations to declare convergence.
Determines random number generation for centroid initialization. Use an int to make the randomness deterministic. See Glossary.
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.
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.
None or -1 means using all processors.
Deprecated since version 0.23: n_jobs was deprecated in version 0.23 and will be removed in 1.0 (renaming of 0.25).
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.
Whether or not to return the number of iterations.
Centroids found at the last iteration of k-means.
label[i] is the code or index of the centroid the i’th observation is closest to.
The final value of the inertia criterion (sum of squared distances to the closest centroid for all observations in the training set).
Number of iterations corresponding to the best results. Returned only if return_n_iter is set to True.


Mean shift clustering using a flat kernel.
Mean shift clustering aims to discover “blobs” in a smooth density of samples. It is a centroid-based algorithm, which works by updating candidates for centroids to be the mean of the points within a given region. These candidates are then filtered in a post-processing stage to eliminate near-duplicates to form the final set of centroids.
Seeding is performed using a binning technique for scalability.
Read more in the User Guide.
Bandwidth used in the RBF kernel.
If not given, the bandwidth is estimated using sklearn.cluster.estimate_bandwidth; see the documentation for that function for hints on scalability (see also the Notes, below).
Seeds used to initialize kernels. If not set, the seeds are calculated by clustering.get_bin_seeds with bandwidth as the grid size and default values for other parameters.
If true, initial kernel locations are not locations of all points, but rather the location of the discretized version of points, where points are binned onto a grid whose coarseness corresponds to the bandwidth. Setting this option to True will speed up the algorithm because fewer seeds will be initialized. The default value is False. Ignored if seeds argument is not None.
To speed up the algorithm, accept only those bins with at least min_bin_freq points as seeds.
If true, then all points are clustered, even those orphans that are not within any kernel. Orphans are assigned to the nearest kernel. If false, then orphans are given cluster label -1.
The number of jobs to use for the computation. This works by computing each of the n_init runs in parallel.
None means 1 unless in a joblib.parallel_backend context. -1 means using all processors. See Glossary for more details.
Maximum number of iterations, per seed point before the clustering operation terminates (for that seed point), if has not converged yet.
New in version 0.22.
Coordinates of cluster centers.
Labels of each point.
Maximum number of iterations performed on each seed.
New in version 0.22.
Scalability:
Because this implementation uses a flat kernel and a Ball Tree to look up members of each kernel, the complexity will tend towards O(T*n*log(n)) in lower dimensions, with n the number of samples and T the number of points. In higher dimensions the complexity will tend towards O(T*n^2).
Scalability can be boosted by using fewer seeds, for example by using a higher value of min_bin_freq in the get_bin_seeds function.
Note that the estimate_bandwidth function is much less scalable than the mean shift algorithm and will be the bottleneck if it is used.
Dorin Comaniciu and Peter Meer, “Mean Shift: A robust approach toward feature space analysis”. IEEE Transactions on Pattern Analysis and Machine Intelligence. 2002. pp. 603-619.
fit(X[, y])
Perform clustering.
fit_predict(X[, y])
Perform clustering on X and returns cluster labels.
get_params([deep])
Get parameters for this estimator.
predict(X)
Predict the closest cluster each sample in X belongs to.
set_params(**params)
Set the parameters of this estimator.
Perform clustering.
Samples to cluster.
Perform clustering on X and returns cluster labels.
Input data.
Not used, present for API consistency by convention.
Cluster labels.
Get parameters for this estimator.
If True, will return the parameters for this estimator and contained subobjects that are estimators.
Parameter names mapped to their values.
Predict the closest cluster each sample in X belongs to.
New data to predict.
Index of the cluster each sample belongs to.
Set the parameters of this estimator.
The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.
Estimator parameters.
Estimator instance.


Mean shift clustering using a flat kernel.
Mean shift clustering aims to discover “blobs” in a smooth density of samples. It is a centroid-based algorithm, which works by updating candidates for centroids to be the mean of the points within a given region. These candidates are then filtered in a post-processing stage to eliminate near-duplicates to form the final set of centroids.
Seeding is performed using a binning technique for scalability.
Read more in the User Guide.
Bandwidth used in the RBF kernel.
If not given, the bandwidth is estimated using sklearn.cluster.estimate_bandwidth; see the documentation for that function for hints on scalability (see also the Notes, below).
Seeds used to initialize kernels. If not set, the seeds are calculated by clustering.get_bin_seeds with bandwidth as the grid size and default values for other parameters.
If true, initial kernel locations are not locations of all points, but rather the location of the discretized version of points, where points are binned onto a grid whose coarseness corresponds to the bandwidth. Setting this option to True will speed up the algorithm because fewer seeds will be initialized. The default value is False. Ignored if seeds argument is not None.
To speed up the algorithm, accept only those bins with at least min_bin_freq points as seeds.
If true, then all points are clustered, even those orphans that are not within any kernel. Orphans are assigned to the nearest kernel. If false, then orphans are given cluster label -1.
The number of jobs to use for the computation. This works by computing each of the n_init runs in parallel.
None means 1 unless in a joblib.parallel_backend context. -1 means using all processors. See Glossary for more details.
Maximum number of iterations, per seed point before the clustering operation terminates (for that seed point), if has not converged yet.
New in version 0.22.
Coordinates of cluster centers.
Labels of each point.
Maximum number of iterations performed on each seed.
New in version 0.22.
Scalability:
Because this implementation uses a flat kernel and a Ball Tree to look up members of each kernel, the complexity will tend towards O(T*n*log(n)) in lower dimensions, with n the number of samples and T the number of points. In higher dimensions the complexity will tend towards O(T*n^2).
Scalability can be boosted by using fewer seeds, for example by using a higher value of min_bin_freq in the get_bin_seeds function.
Note that the estimate_bandwidth function is much less scalable than the mean shift algorithm and will be the bottleneck if it is used.
Dorin Comaniciu and Peter Meer, “Mean Shift: A robust approach toward feature space analysis”. IEEE Transactions on Pattern Analysis and Machine Intelligence. 2002. pp. 603-619.
fit(X[, y])
Perform clustering.
fit_predict(X[, y])
Perform clustering on X and returns cluster labels.
get_params([deep])
Get parameters for this estimator.
predict(X)
Predict the closest cluster each sample in X belongs to.
set_params(**params)
Set the parameters of this estimator.
Perform clustering.
Samples to cluster.
Perform clustering on X and returns cluster labels.
Input data.
Not used, present for API consistency by convention.
Cluster labels.
Get parameters for this estimator.
If True, will return the parameters for this estimator and contained subobjects that are estimators.
Parameter names mapped to their values.
Predict the closest cluster each sample in X belongs to.
New data to predict.
Index of the cluster each sample belongs to.
Set the parameters of this estimator.
The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.
Estimator parameters.
Estimator instance.
A demo of the mean-shift clustering algorithm
Comparing different clustering algorithms on toy datasets


Perform clustering on X and returns cluster labels.
Input data.
Not used, present for API consistency by convention.
Cluster labels.


Get parameters for this estimator.
If True, will return the parameters for this estimator and contained subobjects that are estimators.
Parameter names mapped to their values.


Predict the closest cluster each sample in X belongs to.
New data to predict.
Index of the cluster each sample belongs to.


Set the parameters of this estimator.
The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.
Estimator parameters.
Estimator instance.


Perform mean shift clustering of data using a flat kernel.
Read more in the User Guide.
Input data.
Kernel bandwidth.
If bandwidth is not given, it is determined using a heuristic based on the median of all pairwise distances. This will take quadratic time in the number of samples. The sklearn.cluster.estimate_bandwidth function can be used to do this more efficiently.
Point used as initial kernel locations. If None and bin_seeding=False, each data point is used as a seed. If None and bin_seeding=True, see bin_seeding.
If true, initial kernel locations are not locations of all points, but rather the location of the discretized version of points, where points are binned onto a grid whose coarseness corresponds to the bandwidth. Setting this option to True will speed up the algorithm because fewer seeds will be initialized. Ignored if seeds argument is not None.
To speed up the algorithm, accept only those bins with at least min_bin_freq points as seeds.
If true, then all points are clustered, even those orphans that are not within any kernel. Orphans are assigned to the nearest kernel. If false, then orphans are given cluster label -1.
Maximum number of iterations, per seed point before the clustering operation terminates (for that seed point), if has not converged yet.
The number of jobs to use for the computation. This works by computing each of the n_init runs in parallel.
None means 1 unless in a joblib.parallel_backend context. -1 means using all processors. See Glossary for more details.
New in version 0.17: Parallel Execution using n_jobs.
Coordinates of cluster centers.
Cluster labels for each point.
For an example, see examples/cluster/plot_mean_shift.py.


Mini-Batch K-Means clustering.
Read more in the User Guide.
The number of clusters to form as well as the number of centroids to generate.
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.
Maximum number of iterations over the complete dataset before stopping independently of any early stopping criterion heuristics.
Size of the mini batches.
Verbosity mode.
Compute label assignment and inertia for the complete dataset once the minibatch optimization has converged in fit.
Determines random number generation for centroid initialization and random reassignment. Use an int to make the randomness deterministic. See Glossary.
Control early stopping based on the relative center changes as measured by a smoothed, variance-normalized of the mean center squared position changes. This early stopping heuristics is closer to the one used for the batch variant of the algorithms but induces a slight computational and memory overhead over the inertia heuristic.
To disable convergence detection based on normalized center change, set tol to 0.0 (default).
Control early stopping based on the consecutive number of mini batches that does not yield an improvement on the smoothed inertia.
To disable convergence detection based on inertia, set max_no_improvement to None.
Number of samples to randomly sample for speeding up the initialization (sometimes at the expense of accuracy): the only algorithm is initialized by running a batch KMeans on a random subset of the data. This needs to be larger than n_clusters.
If None, init_size= 3 * batch_size.
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.
Control the fraction of the maximum number of counts for a center to be reassigned. A higher value means that low count centers are more easily reassigned, which means that the model will take longer to converge, but should converge in a better clustering.
Coordinates of cluster centers.
Labels of each point (if compute_labels is set to True).
The value of the inertia criterion associated with the chosen partition (if compute_labels is set to True). The inertia is defined as the sum of square distances of samples to their nearest neighbor.
Number of batches processed.
Weigth sum of each cluster.
Deprecated since version 0.24: This attribute is deprecated in 0.24 and will be removed in 1.1 (renaming of 0.26).
The effective number of samples used for the initialization.
Deprecated since version 0.24: This attribute is deprecated in 0.24 and will be removed in 1.1 (renaming of 0.26).
See also
The classic implementation of the clustering method based on the Lloyd’s algorithm. It consumes the whole set of input data at each iteration.
See https://www.eecs.tufts.edu/~dsculley/papers/fastkmeans.pdf
fit(X[, y, sample_weight])
Compute the centroids on X by chunking it into mini-batches.
fit_predict(X[, y, sample_weight])
Compute cluster centers and predict cluster index for each sample.
fit_transform(X[, y, sample_weight])
Compute clustering and transform X to cluster-distance space.
get_params([deep])
Get parameters for this estimator.
partial_fit(X[, y, sample_weight])
Update k means estimate on a single mini-batch X.
predict(X[, sample_weight])
Predict the closest cluster each sample in X belongs to.
score(X[, y, sample_weight])
Opposite of the value of X on the K-means objective.
set_params(**params)
Set the parameters of this estimator.
transform(X)
Transform X to a cluster-distance space.
Compute the centroids on X by chunking it into mini-batches.
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.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight (default: None).
New in version 0.20.
Compute cluster centers and predict cluster index for each sample.
Convenience method; equivalent to calling fit(X) followed by predict(X).
New data to transform.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight.
Index of the cluster each sample belongs to.
Compute clustering and transform X to cluster-distance space.
Equivalent to fit(X).transform(X), but more efficiently implemented.
New data to transform.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight.
X transformed in the new space.
Get parameters for this estimator.
If True, will return the parameters for this estimator and contained subobjects that are estimators.
Parameter names mapped to their values.
Update k means estimate on a single mini-batch X.
Coordinates of the data points to cluster. It must be noted that X will be copied if it is not C-contiguous.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight (default: None).
Predict the closest cluster each sample in X belongs to.
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.
New data to predict.
The weights for each observation in X. If None, all observations are assigned equal weight (default: None).
Index of the cluster each sample belongs to.
Opposite of the value of X on the K-means objective.
New data.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight.
Opposite of the value of X on the K-means objective.
Set the parameters of this estimator.
The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.
Estimator parameters.
Estimator instance.
Transform X to a cluster-distance space.
In the new space, each dimension is the distance to the cluster centers. Note that even if X is sparse, the array returned by transform will typically be dense.
New data to transform.
X transformed in the new space.


Mini-Batch K-Means clustering.
Read more in the User Guide.
The number of clusters to form as well as the number of centroids to generate.
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.
Maximum number of iterations over the complete dataset before stopping independently of any early stopping criterion heuristics.
Size of the mini batches.
Verbosity mode.
Compute label assignment and inertia for the complete dataset once the minibatch optimization has converged in fit.
Determines random number generation for centroid initialization and random reassignment. Use an int to make the randomness deterministic. See Glossary.
Control early stopping based on the relative center changes as measured by a smoothed, variance-normalized of the mean center squared position changes. This early stopping heuristics is closer to the one used for the batch variant of the algorithms but induces a slight computational and memory overhead over the inertia heuristic.
To disable convergence detection based on normalized center change, set tol to 0.0 (default).
Control early stopping based on the consecutive number of mini batches that does not yield an improvement on the smoothed inertia.
To disable convergence detection based on inertia, set max_no_improvement to None.
Number of samples to randomly sample for speeding up the initialization (sometimes at the expense of accuracy): the only algorithm is initialized by running a batch KMeans on a random subset of the data. This needs to be larger than n_clusters.
If None, init_size= 3 * batch_size.
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.
Control the fraction of the maximum number of counts for a center to be reassigned. A higher value means that low count centers are more easily reassigned, which means that the model will take longer to converge, but should converge in a better clustering.
Coordinates of cluster centers.
Labels of each point (if compute_labels is set to True).
The value of the inertia criterion associated with the chosen partition (if compute_labels is set to True). The inertia is defined as the sum of square distances of samples to their nearest neighbor.
Number of batches processed.
Weigth sum of each cluster.
Deprecated since version 0.24: This attribute is deprecated in 0.24 and will be removed in 1.1 (renaming of 0.26).
The effective number of samples used for the initialization.
Deprecated since version 0.24: This attribute is deprecated in 0.24 and will be removed in 1.1 (renaming of 0.26).
See also
The classic implementation of the clustering method based on the Lloyd’s algorithm. It consumes the whole set of input data at each iteration.
See https://www.eecs.tufts.edu/~dsculley/papers/fastkmeans.pdf
fit(X[, y, sample_weight])
Compute the centroids on X by chunking it into mini-batches.
fit_predict(X[, y, sample_weight])
Compute cluster centers and predict cluster index for each sample.
fit_transform(X[, y, sample_weight])
Compute clustering and transform X to cluster-distance space.
get_params([deep])
Get parameters for this estimator.
partial_fit(X[, y, sample_weight])
Update k means estimate on a single mini-batch X.
predict(X[, sample_weight])
Predict the closest cluster each sample in X belongs to.
score(X[, y, sample_weight])
Opposite of the value of X on the K-means objective.
set_params(**params)
Set the parameters of this estimator.
transform(X)
Transform X to a cluster-distance space.
Compute the centroids on X by chunking it into mini-batches.
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.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight (default: None).
New in version 0.20.
Compute cluster centers and predict cluster index for each sample.
Convenience method; equivalent to calling fit(X) followed by predict(X).
New data to transform.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight.
Index of the cluster each sample belongs to.
Compute clustering and transform X to cluster-distance space.
Equivalent to fit(X).transform(X), but more efficiently implemented.
New data to transform.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight.
X transformed in the new space.
Get parameters for this estimator.
If True, will return the parameters for this estimator and contained subobjects that are estimators.
Parameter names mapped to their values.
Update k means estimate on a single mini-batch X.
Coordinates of the data points to cluster. It must be noted that X will be copied if it is not C-contiguous.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight (default: None).
Predict the closest cluster each sample in X belongs to.
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.
New data to predict.
The weights for each observation in X. If None, all observations are assigned equal weight (default: None).
Index of the cluster each sample belongs to.
Opposite of the value of X on the K-means objective.
New data.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight.
Opposite of the value of X on the K-means objective.
Set the parameters of this estimator.
The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.
Estimator parameters.
Estimator instance.
Transform X to a cluster-distance space.
In the new space, each dimension is the distance to the cluster centers. Note that even if X is sparse, the array returned by transform will typically be dense.
New data to transform.
X transformed in the new space.
Biclustering documents with the Spectral Co-clustering algorithm
Online learning of a dictionary of parts of faces
Compare BIRCH and MiniBatchKMeans
Empirical evaluation of the impact of k-means initialization
Comparison of the K-Means and MiniBatchKMeans clustering algorithms
Comparing different clustering algorithms on toy datasets
Faces dataset decompositions
Clustering text documents using k-means


Compute the centroids on X by chunking it into mini-batches.
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.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight (default: None).
New in version 0.20.


Compute cluster centers and predict cluster index for each sample.
Convenience method; equivalent to calling fit(X) followed by predict(X).
New data to transform.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight.
Index of the cluster each sample belongs to.


Compute clustering and transform X to cluster-distance space.
Equivalent to fit(X).transform(X), but more efficiently implemented.
New data to transform.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight.
X transformed in the new space.


Update k means estimate on a single mini-batch X.
Coordinates of the data points to cluster. It must be noted that X will be copied if it is not C-contiguous.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight (default: None).


Predict the closest cluster each sample in X belongs to.
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.
New data to predict.
The weights for each observation in X. If None, all observations are assigned equal weight (default: None).
Index of the cluster each sample belongs to.


Opposite of the value of X on the K-means objective.
New data.
Not used, present here for API consistency by convention.
The weights for each observation in X. If None, all observations are assigned equal weight.
Opposite of the value of X on the K-means objective.