pairwise_distances#

sklearn.metrics.pairwise_distances(X, Y=None, metric='euclidean', *, n_jobs=None, force_all_finite='deprecated', ensure_all_finite=None, **kwds)[source]#

从特征数组 X 和可选的 Y 计算距离矩阵。

此函数接受一个或两个特征数组或一个距离矩阵，并返回一个距离矩阵。

如果 X 是一个形状为 (n_samples_X, n_features) 的特征数组，并且
- Y 为 None 且 metric 不是 ‘precomputed’，则返回 X 自身之间的对偶距离。
- 如果 Y 是一个形状为 (n_samples_Y, n_features) 的特征数组，则返回 X 和 Y 之间的对偶距离。
如果 X 是一个形状为 (n_samples_X, n_samples_X) 的距离矩阵，则 metric 应为 ‘precomputed’。此时 Y 被忽略，X 将原样返回。

如果输入是非数值数据（例如字符串列表或布尔数组），则必须传入自定义度量。

此方法提供了一种安全的方式来将距离矩阵作为输入，同时保留与许多其他接受向量数组的算法的兼容性。

度量的有效值有

来自 scikit-learn：[‘cityblock’, ‘cosine’, ‘euclidean’, ‘l1’, ‘l2’, ‘manhattan’, ‘nan_euclidean’]。除 ‘nan_euclidean’ 外，所有度量都支持稀疏矩阵输入。
来自 scipy.spatial.distance：[‘braycurtis’, ‘canberra’, ‘chebyshev’, ‘correlation’, ‘dice’, ‘hamming’, ‘jaccard’, ‘kulsinski’, ‘mahalanobis’, ‘minkowski’, ‘rogerstanimoto’, ‘russellrao’, ‘seuclidean’, ‘sokalmichener’, ‘sokalsneath’, ‘sqeuclidean’, ‘yule’] 有关这些度量的详细信息，请参阅 scipy.spatial.distance 的文档。这些度量不支持稀疏矩阵输入。

注意

'kulsinski' 已在 SciPy 1.9 中弃用，并将在 SciPy 1.11 中移除。

注意

'matching' 已在 SciPy 1.9 中移除（请改用 'hamming'）。

请注意，对于 ‘cityblock’、‘cosine’ 和 ‘euclidean’（它们是有效的 scipy.spatial.distance 度量），将使用 scikit-learn 的实现，它速度更快且支持稀疏矩阵（‘cityblock’ 除外）。有关 scikit-learn 中度量的详细描述，请参阅 sklearn.metrics.pairwise.distance_metrics 函数。

在用户指南中了解更多。

参数:

X{类数组, 稀疏矩阵} 形状为 (n_samples_X, n_samples_X) 或 (n_samples_X, n_features)

样本间的对偶距离数组，或特征数组。如果 metric == “precomputed”，则数组形状应为 (n_samples_X, n_samples_X)，否则为 (n_samples_X, n_features)。

Y{类数组, 稀疏矩阵} 形状为 (n_samples_Y, n_features)，默认值=None

可选的第二个特征数组。仅当 metric != “precomputed” 时允许。

metric字符串或可调用对象，默认值='euclidean'

在计算特征数组中实例间距离时使用的度量。如果 metric 是字符串，它必须是 scipy.spatial.distance.pdist 的 metric 参数所允许的选项之一，或 pairwise.PAIRWISE_DISTANCE_FUNCTIONS 中列出的度量。如果 metric 为 “precomputed”，则 X 被假定为距离矩阵。此外，如果 metric 是一个可调用函数，它将作用于每一对实例（行），并记录结果值。该可调用函数应接受 X 中的两个数组作为输入，并返回表示它们之间距离的值。

n_jobs整型，默认值=None

用于计算的作业数量。这通过将对偶矩阵分解为 n_jobs 个均匀切片并使用多线程计算来实现。

None 表示 1，除非在 joblib.parallel_backend 上下文中。 -1 表示使用所有处理器。有关更多详细信息，请参阅术语表。

“euclidean” 和 “cosine” 度量严重依赖已多线程的 BLAS。因此，增加 n_jobs 可能会导致资源过度占用并迅速降低性能。

force_all_finite布尔值或 ‘allow-nan’，默认值=True

是否对数组中的 np.inf、np.nan、pd.NA 抛出错误。对于 pairwise.PAIRWISE_DISTANCE_FUNCTIONS 中列出的度量，此参数将被忽略。可能的选项有

True：强制数组的所有值为有限值。
False：接受数组中的 np.inf、np.nan、pd.NA。
‘allow-nan’：仅接受数组中的 np.nan 和 pd.NA 值。值不能为无限大。

0.22 版本新增：force_all_finite 接受字符串 'allow-nan'。

0.23 版本变更：接受 pd.NA 并将其转换为 np.nan。

自 1.6 版本弃用：force_all_finite 已重命名为 ensure_all_finite，并将在 1.8 版本中移除。

ensure_all_finite布尔值或 ‘allow-nan’，默认值=True

是否对数组中的 np.inf、np.nan、pd.NA 抛出错误。对于 pairwise.PAIRWISE_DISTANCE_FUNCTIONS 中列出的度量，此参数将被忽略。可能的选项有

True：强制数组的所有值为有限值。
False：接受数组中的 np.inf、np.nan、pd.NA。
‘allow-nan’：仅接受数组中的 np.nan 和 pd.NA 值。值不能为无限大。

1.6 版本新增：force_all_finite 已重命名为 ensure_all_finite。

**kwds可选关键字参数

任何其他参数将直接传递给距离函数。如果使用 scipy.spatial.distance 度量，参数仍依赖于度量。请参阅 scipy 文档以获取使用示例。

返回:

D形状为 (n_samples_X, n_samples_X) 或 (n_samples_X, n_samples_Y) 的 ndarray: 一个距离矩阵 D，如果 Y 为 None，则 D_{i, j} 是给定矩阵 X 中第 i 个向量和第 j 个向量之间的距离。如果 Y 不为 None，则 D_{i, j} 是 X 中第 i 个数组和 Y 中第 j 个数组之间的距离。

另请参阅

pairwise_distances_chunked: 执行与此函数相同的计算，但返回距离矩阵块的生成器，以限制内存使用。
sklearn.metrics.pairwise.paired_distances: 计算两个数组中对应元素之间的距离。

备注

如果 metric 是可调用对象，则对 X 和 Y 的维度没有限制。

示例

>>> from sklearn.metrics.pairwise import pairwise_distances
>>> X = [[0, 0, 0], [1, 1, 1]]
>>> Y = [[1, 0, 0], [1, 1, 0]]
>>> pairwise_distances(X, Y, metric='sqeuclidean')
array([[1., 2.],
       [2., 1.]])

画廊示例#

使用不同度量的层次聚类

scikit-learn 1.5 发布亮点

pairwise_distances#

画廊示例#

本页