iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Use scipy.spatial.distance.pdist(X) to calculate distances among rows in one point set, and scipy.spatial.distance.cdist(XA, XB) to calculate every distance between two point sets. pdist returns one value per unique, unordered pair; cdist returns a rectangular matrix. Use squareform when you need to turn a pdist result into a square matrix.
How to choose between pdist and cdist
In SciPy, each row is an observation—a point represented by its feature coordinates—and each column is one coordinate or feature. The functions differ in which observations they compare and how they arrange the result.
| Need | Function | Input shape | Output |
|---|---|---|---|
| Compare points within one set | pdist(X) |
X has shape (m, n) |
A condensed vector of m × (m − 1) / 2 unique pair distances |
| Compare each point in one set with each point in another | cdist(XA, XB) |
XA has shape (mA, n); XB has shape (mB, n) |
A matrix of shape (mA, mB) |
For cdist, both arrays must have the same number of columns: each point must use the same feature coordinates. Its output entry at row i, column j is the distance from XA[i] to XB[j]. The official references describe these APIs in the SciPy v1.18.0 distance computations manual, including pdist and cdist.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Compute within-set and between-set distances
This example uses Euclidean distance, the default metric for both functions. The coordinates are two-dimensional, but the same row-wise arrangement applies to points with more features.
#1 Best Overall
import numpy as np
from scipy.spatial.distance import cdist, pdist, squareform
X = np.array([[0.0, 0.0], [3.0, 4.0], [3.0, 0.0]])
Y = np.array([[1.0, 1.0], [4.0, 4.0]])
within = pdist(X, metric="euclidean")
within_square = squareform(within)
between = cdist(X, Y, metric="euclidean")within contains three distances because three rows create three unique unordered pairs. The condensed representation does not repeat each distance in the opposite direction or include self-distances. within_square is the corresponding symmetric 3-by-3 matrix, with zeros on its diagonal. between is a 3-by-2 matrix: each of its three rows corresponds to a point in X, and each of its two columns corresponds to a point in Y.
Convert a condensed result to a square matrix
Use squareform when later code expects a matrix indexed by both point numbers, for example when displaying or inspecting all within-set distances:
distance_matrix = squareform(within)squareform also converts a square distance matrix back to the condensed representation. The SciPy v1.18.0 squareform reference documents both directions. For cross-set comparisons, cdist already returns a rectangular matrix; it is not the condensed output from pdist.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesChoose a metric that matches what distance means
Both functions accept a metric name or a callable. The appropriate choice depends on what the coordinates represent and what a difference should mean; there is no universally best metric.
- Euclidean: straight-line distance in the feature coordinates; this is the default.
- Cityblock: sums the absolute coordinate-wise differences, also known as Manhattan distance.
- Cosine: compares vector direction rather than treating overall magnitude as the central distinction.
- Correlation: compares centered patterns across vector components.
- Minkowski: a family of distances whose behavior depends on its
pparameter. - Boolean-vector metrics: options such as Jaccard and Hamming can suit Boolean representations when their definitions match the problem.
For example, to calculate cross-set cityblock distances, replace the metric in the call with cdist(X, Y, metric="cityblock"). Consult SciPy’s metric and parameter documentation for cdist or its pdist reference for the supported choices in that release.
Set parameters for weighted or statistical distances
Some metric choices depend on additional data or parameters. Minkowski distance can use p, and weighted Minkowski can use feature weights w. Standardized Euclidean uses a variance vector V; Mahalanobis uses an inverse covariance matrix VI. These values affect the resulting distances, so select them to reflect the feature scales and statistical assumptions of the data rather than treating them as interchangeable tuning switches.
The exact arguments available depend on the metric and function. Check the version-specific pdist or cdist reference before passing metric parameters.
Check array dimensions and output needs
- Make sure each row is one point and columns consistently represent the same features in every input array.
- For
cdist, verify thatXA.shape[1] == XB.shape[1]. - Use
pdistwhen you need only the distinct within-set pairs; convert withsquareformonly when a square representation is useful. - Use
cdistwhen you need all cross-set combinations, and confirm that anmA-by-mBresult fits your workflow. - For large inputs, decide the metric and required output representation alongside the array dimensions and available memory. The API references document an
outparameter but do not establish a universal runtime or memory limit.
The links above target SciPy v1.18.0 documentation. Function signatures and supported metric details can differ across installed releases, so consult the manual for the version in your environment. The broader SciPy spatial algorithms and data structures manual provides context for other spatial APIs.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
