成對距離#

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

從向量陣列 X 和可選的 Y 計算距離矩陣。

此方法接受向量陣列或距離矩陣作為輸入，並返回一個距離矩陣。如果輸入是向量陣列，則會計算距離。如果輸入是距離矩陣，則直接返回。如果輸入是非數值資料的集合（例如字串列表或布林陣列），則必須傳遞自訂的度量方式。

此方法提供了一種安全的方式來接受距離矩陣作為輸入，同時保持與許多其他接受向量陣列的演算法的相容性。

如果給定了 Y（預設為 None），則返回的矩陣是 X 和 Y 中陣列之間的成對距離。

有效的度量方式值為：

  • 來自 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{array-like, sparse matrix}，形狀為 (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}，形狀為 (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，使得 D_{i, j} 是給定矩陣 X 的第 i 個和第 j 個向量之間的距離（如果 Y 為 None）。如果 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.]])