KMeans

class sklearn.cluster.KMeans(n_clusters=8, *, init='k-means++', n_init='auto', max_iter=300, tol=0.0001, verbose=0, random_state=None, copy_x=True, algorithm='lloyd')

K-Means 聚类。

更多信息请参阅 用户指南 。

Parameters:

n_clustersint, default=8

要形成的聚类数量以及要生成的质心数量。

有关如何选择 n_clusters 的最佳值的示例，请参阅 使用轮廓分析选择KMeans聚类的簇数 。

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

初始化方法：

• ‘k-means++’ : 使用基于经验概率分布的抽样选择初始聚类质心，该分布基于点的总惯性贡献。这种技术加速了收敛。实现的算法是“贪婪 k-means++”。它与普通的 k-means++ 不同之处在于在每次抽样步骤中进行多次试验并选择最佳质心。

• ‘random’: 从数据中随机选择 n_clusters 个观测值（行）作为初始质心。

• 如果传递了一个数组，它应该是形状为 (n_clusters, n_features) 并给出初始中心。

• 如果传递了一个 callable，它应该接受参数 X, n_clusters 和随机状态并返回一个初始化。

有关如何使用不同的 init 策略的示例，请参阅示例 标题为 手写数字数据上的K-Means聚类演示 。

n_init‘auto’ 或 int, default=’auto’

k-means 算法使用不同的质心种子运行的次数。最终结果是 n_init 次连续运行中惯性最好的输出。对于稀疏的高维问题，建议进行多次运行（参见 使用k-means对稀疏数据进行聚类 ）。

当 n_init='auto' 时，运行的次数取决于 init 的值： 如果使用 init='random' 或 init 是一个 callable，则为 10 次； 如果使用 init='k-means++' 或 init 是一个 array-like，则为 1 次。

Added in version 1.2: 添加了 n_init 的 ‘auto’ 选项。

Changed in version 1.4: n_init 的默认值更改为 'auto' 。

max_iterint, default=300

单次运行 k-means 算法的最大迭代次数。

tolfloat, default=1e-4

相对于 Frobenius 范数的相对容差，用于声明两次连续迭代之间的聚类中心差异的收敛。

verboseint, default=0

详细模式。

random_stateint, RandomState 实例或 None, default=None

用于质心初始化的随机数生成。使用 int 使随机性确定。 参见 术语表 。

copy_xbool, default=True

在预计算距离时，首先对数据进行中心化会更准确。如果 copy_x 为 True（默认），则不会修改原始数据。如果为 False，则会修改原始数据，并在函数返回前恢复，但可能会引入小的数值差异。请注意，如果原始数据不是 C-contiguous，即使 copy_x 为 False，也会进行复制。如果原始数据是稀疏的，但不是 CSR 格式，即使 copy_x 为 False，也会进行复制。

algorithm{“lloyd”, “elkan”}, default=”lloyd”

使用的 k-means 算法。经典的 EM 风格算法是 "lloyd" 。 "elkan" 变体在某些具有良好定义的簇的数据集上可以更高效，通过使用三角不等式。然而，由于分配了一个额外的形状为 (n_samples, n_clusters) 的数组，它更占用内存。

Changed in version 0.18: 添加了 Elkan 算法

Changed in version 1.1: 将 “full” 重命名为 “lloyd”，并弃用了 “auto” 和 “full”。 将 “auto” 更改为使用 “lloyd” 而不是 “elkan”。

Attributes:

cluster_centers_ndarray of shape (n_clusters, n_features)

聚类中心的坐标。如果算法在完全收敛之前停止（参见 tol 和 max_iter ），这些将与 labels_ 不一致。

labels_ndarray of shape (n_samples,)

每个点的标签

inertia_float

样本到其最近聚类中心的平方距离之和，如果提供了样本权重，则按样本权重加权。

n_iter_int

运行的迭代次数。

n_features_in_int

在 fit 期间看到的特征数量。

Added in version 0.24.

feature_names_in_ndarray of shape ( n_features_in_ ,)

在 fit 期间看到的特征名称。仅当 X 的特征名称均为字符串时定义。

Added in version 1.0.

See also

MiniBatchKMeans

替代的在线实现，使用小批量增量更新中心位置。对于大规模学习（例如 n_samples > 10k），MiniBatchKMeans 可能比默认的批处理实现快得多。

Notes

k-means 问题通过 Lloyd’s 或 Elkan’s 算法解决。

平均复杂度为 O(k n T)，其中 n 是样本数量，T 是迭代次数。

最坏情况复杂度为 O(n^(k+2/p))，其中 n = n_samples，p = n_features。 更多详细信息请参阅 “How slow is the k-means method?” D. Arthur 和 S. Vassilvitskii - SoCG2006. 。

实际上，k-means 算法非常快（是可用的最快的聚类算法之一），但它会陷入局部最小值。因此，重新启动它几次可能会有所帮助。

如果算法在完全收敛之前停止（因为 tol 或 max_iter ）， labels_ 和 cluster_centers_ 将不一致，即 cluster_centers_ 将不是每个簇中点的均值。此外，估计器将在最后一次迭代后重新分配 labels_ ，以使 labels_ 与训练集上的 predict 一致。

Examples

>>> from sklearn.cluster import KMeans
>>> import numpy as np
>>> X = np.array([[1, 2], [1, 4], [1, 0],
...               [10, 2], [10, 4], [10, 0]])
>>> kmeans = KMeans(n_clusters=2, random_state=0, n_init="auto").fit(X)
>>> kmeans.labels_
array([1, 1, 1, 0, 0, 0], dtype=int32)
>>> kmeans.predict([[0, 0], [12, 3]])
array([1, 0], dtype=int32)
>>> kmeans.cluster_centers_
array([[10.,  2.],
       [ 1.,  2.]])

有关使用 iris 数据集的 K-Means 更详细示例，请参阅 K-means 聚类 。

有关 K-Means 常见问题及其解决方法的示例，请参阅 k-means 假设的演示 。

有关如何使用 K-Means 进行颜色量化的示例，请参阅 使用K均值的颜色量化 。

有关如何使用 K-Means 对文本文档进行聚类的演示，请参阅 使用k-means聚类文本文档 。

有关 K-Means 和 MiniBatchKMeans 之间的比较，请参阅示例 K-Means 和 MiniBatchKMeans 聚类算法的比较 。

fit(X, y=None, sample_weight=None)

计算k-means聚类。

Parameters:

X{array-like, sparse matrix}，形状为 (n_samples, n_features)

要聚类的训练实例。需要注意的是，数据将被转换为C排序，如果给定的数据不是C连续的，这将导致内存拷贝。 如果传递的是稀疏矩阵，如果它不是CSR格式，将进行拷贝。

y忽略

未使用，此处存在是为了通过约定保持API一致性。

sample_weightarray-like，形状为 (n_samples,)，默认=None

X中每个观测值的权重。如果为None，所有观测值将被分配相同的权重。如果 init 是一个可调用对象或用户提供的数组，则在初始化期间不使用 sample_weight 。

Added in version 0.20.

Returns:

selfobject

拟合的估计器。

fit_predict(X, y=None, sample_weight=None)

计算聚类中心并为每个样本预测聚类索引。

便捷方法；等效于调用 fit(X) 后再调用 predict(X)。

Parameters:

X{array-like, sparse matrix}，形状为 (n_samples, n_features)

要转换的新数据。

y忽略

未使用，此处仅为了保持 API 一致性而存在。

sample_weight形状为 (n_samples,) 的 array-like，默认=None

X 中每个观测值的权重。如果为 None，则所有观测值被赋予相同的权重。

Returns:

labels形状为 (n_samples,) 的 ndarray

每个样本所属的聚类索引。

fit_transform(X, y=None, sample_weight=None)

计算聚类并将X转换为聚类距离空间。

等效于fit(X).transform(X)，但实现更高效。

Parameters:

X{array-like, sparse matrix}，形状为 (n_samples, n_features)

要转换的新数据。

y忽略

未使用，此处仅为了API一致性而存在。

sample_weight形状为 (n_samples,) 的array-like，默认=None

X中每个观测值的权重。如果为None，则所有观测值分配相同的权重。

Returns:

X_new形状为 (n_samples, n_clusters) 的ndarray

在新空间中转换的X。

get_feature_names_out(input_features=None)

获取转换后的输出特征名称。

输出特征名称将以小写的类名作为前缀。例如，如果转换器输出3个特征，那么输出特征名称将是： ["class_name0", "class_name1", "class_name2"] 。

Parameters:

input_features类似数组的对象或None，默认为None

仅用于验证特征名称与 fit 中看到的名称。

Returns:

feature_names_outndarray of str对象

转换后的特征名称。

get_metadata_routing()

获取此对象的元数据路由。

请查看 用户指南 以了解路由机制的工作原理。

Returns:

routingMetadataRequest

MetadataRequest 封装的 路由信息。

get_params(deep=True)

获取此估计器的参数。

Parameters:

deepbool, 默认=True

如果为True，将返回此估计器和包含的子对象（也是估计器）的参数。

Returns:

paramsdict

参数名称映射到它们的值。

predict(X)

预测X中每个样本所属的最接近的簇。

在向量量化的文献中， cluster_centers_ 被称为代码簿，而 predict 返回的每个值是代码簿中最接近代码的索引。

Parameters:

X{array-like, sparse matrix} of shape (n_samples, n_features)

新数据以进行预测。

Returns:

labelsndarray of shape (n_samples,)

每个样本所属的簇的索引。

score(X, y=None, sample_weight=None)

X在K-means目标函数上的值的相反数。

X{array-like, sparse matrix} of shape (n_samples, n_features)

新数据。

y忽略

不使用，出现在这里是为了API一致性。

sample_weightarray-like of shape (n_samples,), default=None

X中每个观测值的权重。如果为None，则所有观测值被赋予相同的权重。

scorefloat

X在K-means目标函数上的值的相反数。

set_fit_request(*, sample_weight: bool | None | str = '$UNCHANGED$') → KMeans

Request metadata passed to the fit method.

Note that this method is only relevant if enable_metadata_routing=True (see sklearn.set_config ). Please see User Guide on how the routing mechanism works.

The options for each parameter are:

• True : metadata is requested, and passed to fit if provided. The request is ignored if metadata is not provided.

• False : metadata is not requested and the meta-estimator will not pass it to fit .

• None : metadata is not requested, and the meta-estimator will raise an error if the user provides it.

• str : metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default ( sklearn.utils.metadata_routing.UNCHANGED ) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Note

This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a Pipeline . Otherwise it has no effect.

Parameters:

sample_weightstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for sample_weight parameter in fit .

Returns:

selfobject

The updated object.

set_output(*, transform=None)

设置输出容器。

请参阅 介绍 set_output API 以了解如何使用API的示例。

Parameters:

transform{“default”, “pandas”, “polars”}, 默认=None

配置 transform 和 fit_transform 的输出。

• "default" : 转换器的默认输出格式

• "pandas" : DataFrame 输出

• "polars" : Polars 输出

• None : 转换配置不变

Added in version 1.4: "polars" 选项已添加。

Returns:

self估计器实例

估计器实例。

set_params(**params)

设置此估计器的参数。

该方法适用于简单估计器以及嵌套对象（例如 Pipeline ）。后者具有形式为 <component>__<parameter> 的参数，以便可以更新嵌套对象的每个组件。

Parameters:

**paramsdict

估计器参数。

Returns:

selfestimator instance

估计器实例。

set_score_request(*, sample_weight: bool | None | str = '$UNCHANGED$') → KMeans

Request metadata passed to the score method.

Note that this method is only relevant if enable_metadata_routing=True (see sklearn.set_config ). Please see User Guide on how the routing mechanism works.

The options for each parameter are:

• True : metadata is requested, and passed to score if provided. The request is ignored if metadata is not provided.

• False : metadata is not requested and the meta-estimator will not pass it to score .

• None : metadata is not requested, and the meta-estimator will raise an error if the user provides it.

• str : metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default ( sklearn.utils.metadata_routing.UNCHANGED ) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Note

This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a Pipeline . Otherwise it has no effect.

Parameters:

sample_weightstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for sample_weight parameter in score .

Returns:

selfobject

The updated object.

transform(X)

将X转换为聚类距离空间。

在新空间中，每个维度是到聚类中心的距离。请注意，即使X是稀疏的， transform 返回的数组通常也是稠密的。

Parameters:

X{array-like, sparse matrix}，形状为 (n_samples, n_features)

要转换的新数据。

Returns:

X_newndarray，形状为 (n_samples, n_clusters)

X在新空间中转换后的结果。

Gallery examples

scikit-learn 1.1 版本发布亮点

scikit-learn 1.1 版本发布亮点

scikit-learn 0.23 版本发布亮点

scikit-learn 0.23 版本发布亮点

K-Means 和 MiniBatchKMeans 聚类算法的比较

K-Means 和 MiniBatchKMeans 聚类算法的比较

K-means 聚类

K-means 聚类

k-means 假设的演示

k-means 假设的演示

k-means 初始化影响的经验评估

k-means 初始化影响的经验评估

二分 K-Means 和常规 K-Means 性能比较

二分 K-Means 和常规 K-Means 性能比较

使用K均值的颜色量化

使用K均值的颜色量化

使用轮廓分析选择KMeans聚类的簇数

使用轮廓分析选择KMeans聚类的簇数

手写数字数据上的K-Means聚类演示

手写数字数据上的K-Means聚类演示

使用k-means聚类文本文档

使用k-means聚类文本文档