成对距离#

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

计算向量数组 X 和可选的 Y 之间的距离矩阵。

此方法接受向量数组或距离矩阵，并返回距离矩阵。如果输入是向量数组，则计算距离；如果输入是距离矩阵，则直接返回该矩阵。如果输入是非数值数据的集合（例如字符串列表或布尔数组），则必须传递自定义度量。

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

如果提供 Y（默认为 None），则返回的矩阵是 X 和 Y 中数组之间的成对距离。

度量 metric 的有效值为：

  • 来自 scikit-learn：['cityblock', 'cosine', 'euclidean', 'l1', 'l2', 'manhattan']。这些度量支持稀疏矩阵输入。['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) 的 {array-like, sparse matrix}

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

Y形状为 (n_samples_Y, n_features) 的 {array-like, sparse matrix}，默认为 None

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

metricstr 或 callable，默认为 'euclidean'

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

n_jobsint，默认为 None

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

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

“euclidean”和“cosine”度量严重依赖于 BLAS，而 BLAS 已经是多线程的。因此，增加 n_jobs 可能会导致过度订阅并迅速降低性能。

force_all_finitebool 或 '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_finitebool 或 '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

计算两个数组中对应元素之间的距离。

示例

>>> 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.]])