pairwise_distances

sklearn.metrics.pairwise_distances(X, Y=None, metric='euclidean', *, n_jobs=None, ensure_all_finite=True, **kwds)[исходный код]

Вычисляет матрицу расстояний по массиву признаков 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 возвращается без изменений.

Если входные данные представляют собой набор нечисловых значений (например, список строк или массив логических значений), необходимо передать пользовательскую метрику.

Этот метод позволяет безопасно передать на вход матрицу расстояний, сохраняя совместимость со многими другими алгоритмами, принимающими векторный массив.

Допустимые значения параметра metric:

• Из 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{array-like, sparse matrix} of shape (n_samples_X, n_samples_X) or (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 — строка, она должна соответствовать одному из значений, допустимых для параметра metric функции scipy.spatial.distance.pdist, либо метрике из списка pairwise.PAIRWISE_DISTANCE_FUNCTIONS. Если metric равно “precomputed”, предполагается, что X — это матрица расстояний. Также в качестве metric можно указать вызываемую функцию: она вызывается для каждой пары объектов (строк), а полученное значение сохраняется. Вызываемая функция должна принимать на вход два массива из X и возвращать значение, указывающее расстояние между ними.

n_jobsint, default=None

Количество заданий для вычисления. Парная матрица разделяется на равные части в количестве n_jobs, которые вычисляются с использованием многопоточности.

None означает 1, если только не используется контекст joblib.parallel_backend. -1 означает использование всех процессоров. Подробнее см. в глоссарии.

Вычисления для метрик “euclidean” и “cosine” активно используют BLAS, который уже поддерживает многопоточность. Поэтому увеличение n_jobs, скорее всего, приведёт к избыточной нагрузке и быстрому снижению производительности.

ensure_all_finitebool or ‘allow-nan’, default=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 of shape (n_samples_X, n_samples_X) or (n_samples_X, n_samples_Y)

Матрица расстояний D, в которой D_{i, j} — расстояние между i-м и j-м векторами заданной матрицы X, если Y равно None. Если Y не равно None, то D_{i, j} — расстояние между i-м массивом из X и j-м массивом из Y.

См. также

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