pairwise_distances#

sklearn.metrics.pairwise_distances(X, Y=None, metric='euclidean', *, n_jobs=None, ensure_all_finite=True, **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’]。这些度量不支持稀疏矩阵输入。

注意

'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{array-like, sparse matrix} of shape (n_samples_Y, n_features), default=None

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

metricstr or callable, default=’euclidean’

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

n_jobsint, default=None

用于计算的作业数。这通过将成对矩阵分解为 n_jobs 个均匀的块，然后使用多线程计算它们来实现。

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

“euclidean” 和 “cosine” 度量高度依赖于 BLAS，而 BLAS 已经进行了多线程处理。因此，增加 n_jobs 可能会导致过度订阅并迅速降低性能。

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。

**kwdsoptional keyword parameters

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

返回:
Dndarray，形状为 (n_samples_X, n_samples_X) 或 (n_samples_X, n_samples_Y)

如果 Y 为 None，则 D 是一个距离矩阵，其中 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.]])