Note: This page has been translated by MathWorks. Click here to see

To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

**MathWorks Machine Translation**

The automated translation of this page is provided by a general purpose third party translator tool.

MathWorks does not warrant, and disclaims all liability for, the accuracy, suitability, or fitness for purpose of the translation.

Pairwise distance between two sets of observations

`D = pdist2(X,Y,Distance)`

`D = pdist2(X,Y,Distance,DistParameter)`

`D = pdist2(___,Name,Value)`

`[D,I] = pdist2(___,Name,Value)`

returns the distance using the metric specified by `D`

= pdist2(`X`

,`Y`

,`Distance`

,`DistParameter`

)`Distance`

and `DistParameter`

. You can specify
`DistParameter`

only when `Distance`

is `'seuclidean'`

, `'minkowski'`

, or
`'mahalanobis'`

.

specifies an additional option using one of the name-value pair arguments
`D`

= pdist2(___,`Name,Value`

)`'Smallest'`

or `'Largest'`

in
addition to any of the arguments in the previous syntaxes.

For example,

`D = pdist2(X,Y,Distance,'Smallest',K)`

computes the distance using the metric specified by`Distance`

and returns the`K`

smallest pairwise distances to observations in`X`

for each observation in`Y`

in ascending order.`D = pdist2(X,Y,Distance,DistParameter,'Largest',K)`

computes the distance using the metric specified by`Distance`

and`DistParameter`

and returns the`K`

largest pairwise distances in descending order.

`[`

also returns the matrix `D`

,`I`

] = pdist2(___,`Name,Value`

)`I`

using any of the arguments in the
previous syntaxes. The matrix `I`

contains the indices of the
observations in `X`

corresponding to the distances in
`D`

.

Create two matrices with three observations and two variables.

rng('default') % For reproducibility X = rand(3,2); Y = rand(3,2);

Compute the Euclidean distance. The default value of the input argument `Distance`

is `'euclidean'`

. When computing the Euclidean distance without using a name-value pair argument, you do not need to specify `Distance`

.

D = pdist2(X,Y)

`D = `*3×3*
0.5387 0.8018 0.1538
0.7100 0.5951 0.3422
0.8805 0.4242 1.2050

`D(i,j)`

corresponds to the pairwise distance between observation `i`

in `X`

and observation `j`

in `Y`

.

Create two matrices with three observations and two variables.

rng('default') % For reproducibility X = rand(3,2); Y = rand(3,2);

Compute the Minkowski distance with the default exponent 2.

`D1 = pdist2(X,Y,'minkowski')`

`D1 = `*3×3*
0.5387 0.8018 0.1538
0.7100 0.5951 0.3422
0.8805 0.4242 1.2050

Compute the Minkowski distance with an exponent of 1, which is equal to the city block distance.

`D2 = pdist2(X,Y,'minkowski',1)`

`D2 = `*3×3*
0.5877 1.0236 0.2000
0.9598 0.8337 0.3899
1.0189 0.4800 1.7036

`D3 = pdist2(X,Y,'cityblock')`

`D3 = `*3×3*
0.5877 1.0236 0.2000
0.9598 0.8337 0.3899
1.0189 0.4800 1.7036

Create two matrices with three observations and two variables.

rng('default') % For reproducibility X = rand(3,2); Y = rand(3,2);

Find the two smallest pairwise Euclidean distances to observations in `X`

for each observation in `Y`

.

[D,I] = pdist2(X,Y,'euclidean','Smallest',2)

`D = `*2×3*
0.5387 0.4242 0.1538
0.7100 0.5951 0.3422

`I = `*2×3*
1 3 1
2 2 2

For each observation in `Y`

, `pdist2`

finds the two smallest distances by computing and comparing the distance values to all the observations in `X`

. The function then sorts the distances in each column of `D`

in ascending order. `I`

contains the indices of the observations in `X`

corresponding to the distances in `D`

.

Define a custom distance function that ignores coordinates with `NaN`

values, and compute pairwise distance by using the custom distance function.

Create two matrices with three observations and three variables.

rng('default') % For reproducibility X = rand(3,3) Y = [X(:,1:2) rand(3,1)]

X = 0.8147 0.9134 0.2785 0.9058 0.6324 0.5469 0.1270 0.0975 0.9575 Y = 0.8147 0.9134 0.9649 0.9058 0.6324 0.1576 0.1270 0.0975 0.9706

The first two columns of X and Y are identical. Assume that `X(1,1)`

is missing.

X(1,1) = NaN

X = NaN 0.9134 0.2785 0.9058 0.6324 0.5469 0.1270 0.0975 0.9575

Compute the Hamming distance.

```
D1 = pdist2(X,Y,'hamming')
```

D1 = NaN NaN NaN 1.0000 0.3333 1.0000 1.0000 1.0000 0.3333

If observation `i`

in `X`

or observation `j`

in `Y`

contains `NaN`

values, the function `pdist2`

returns `NaN`

for the pairwise distance between `i`

and `j`

. Therefore, D1(1,1), D1(1,2), and D1(1,3) are `NaN`

values.

Define a custom distance function `nanhamdist`

that ignores coordinates with `NaN`

values and computes the Hamming distance. When working with a large number of observations, you can compute the distance more quickly by looping over coordinates of the data.

function D2 = nanhamdist(XI,XJ) %NANHAMDIST Hamming distance ignoring coordinates with NaNs [m,p] = size(XJ); nesum = zeros(m,1); pstar = zeros(m,1); for q = 1:p notnan = ~(isnan(XI(q)) | isnan(XJ(:,q))); nesum = nesum + ((XI(q) ~= XJ(:,q)) & notnan); pstar = pstar + notnan; end D2 = nesum./pstar;

Compute the distance with `nanhamdist`

by passing the function handle as an input argument of `pdist2`

.

D2 = pdist2(X,Y,@nanhamdist)

D2 = 0.5000 1.0000 1.0000 1.0000 0.3333 1.0000 1.0000 1.0000 0.3333

`X,Y`

— Input datanumeric matrix

Input data, specified as a numeric matrix. `X`

is an
*mx*-by-*n* matrix and
`Y`

is an
*my*-by-*n* matrix. Rows correspond to
individual observations, and columns correspond to individual
variables.

**Data Types: **`single`

| `double`

`Distance`

— Distance metriccharacter vector | string scalar | function handle

Distance metric, specified as a character vector, string scalar, or function handle, as described in the following table.

Value | Description |
---|---|

`'euclidean'` | Euclidean distance (default). |

`'squaredeuclidean'` | Squared Euclidean distance. (This option is provided for efficiency only. It does not satisfy the triangle inequality.) |

`'seuclidean'` | Standardized Euclidean distance. Each coordinate difference between observations is scaled by
dividing by the corresponding element of the standard deviation, |

`'mahalanobis'` |
Mahalanobis distance using the sample covariance of |

`'cityblock'` | City block distance. |

`'minkowski'` | Minkowski distance. The default exponent is 2. Use |

`'chebychev'` | Chebychev distance (maximum coordinate difference). |

`'cosine'` | One minus the cosine of the included angle between points (treated as vectors). |

`'correlation'` | One minus the sample correlation between points (treated as sequences of values). |

`'hamming'` | Hamming distance, which is the percentage of coordinates that differ. |

`'jaccard'` | One minus the Jaccard coefficient, which is the percentage of nonzero coordinates that differ. |

`'spearman'` |
One minus the sample Spearman's rank correlation between observations (treated as sequences of values). |

`@` |
Custom distance function handle. A distance function has the form function D2 = DISTFUN(ZI,ZJ) % calculation of distance ... `ZI` is a`1` -by-`n` vector containing a single observation.`ZJ` is an`m2` -by-`n` matrix containing multiple observations.`distfun` must accept a matrix`ZJ` with an arbitrary number of observations.`D2` is an`m2` -by-`1` vector of distances, and`D2(k)` is the distance between observations`ZI` and`ZJ(k,:)` .
If your data is not sparse, you can generally compute distance more quickly by using a built-in distance instead of a function handle. |

For definitions, see Distance Metrics.

When you use `'seuclidean'`

,
`'minkowski'`

, or `'mahalanobis'`

, you
can specify an additional input argument `DistParameter`

to control these metrics. You can also use these metrics in the same way as
the other metrics with a default value of
`DistParameter`

.

**Example: **
`'minkowski'`

`DistParameter`

— Distance metric parameter valuespositive scalar | numeric vector | numeric matrix

Distance metric parameter values, specified as a positive scalar, numeric vector, or
numeric matrix. This argument is valid only when you specify
`Distance`

as `'seuclidean'`

,
`'minkowski'`

, or `'mahalanobis'`

.

If

`Distance`

is`'seuclidean'`

,`DistParameter`

is a vector of scaling factors for each dimension, specified as a positive vector. The default value is`nanstd(`

.`X`

)If

`Distance`

is`'minkowski'`

,`DistParameter`

is the exponent of Minkowski distance, specified as a positive scalar. The default value is 2.If

`Distance`

is`'mahalanobis'`

,`DistParameter`

is a covariance matrix, specified as a numeric matrix. The default value is`nancov(X)`

.`DistParameter`

must be symmetric and positive definite.

**Example: **
`'minkowski',3`

**Data Types: **`single`

| `double`

Specify optional
comma-separated pairs of `Name,Value`

arguments. `Name`

is
the argument name and `Value`

is the corresponding value.
`Name`

must appear inside single quotes (`' '`

). You can
specify several name and value pair arguments in any order as
`Name1,Value1,...,NameN,ValueN`

.

`'Smallest',K`

or `'Largest',K`

.
You cannot use both `'Smallest'`

and
`'Largest'`

.`'Smallest'`

— Number of smallest distances to findpositive integer

Number of smallest distances to find, specified as the comma-separated
pair consisting of `'Smallest'`

and a positive integer.
If you specify `'Smallest'`

, then
`pdist2`

sorts the distances in each column of
`D`

in ascending order.

**Example: **`'Smallest',3`

**Data Types: **`single`

| `double`

`'Largest'`

— Number of largest distances to findpositive integer

Number of largest distances to find, specified as the comma-separated
pair consisting of `'Largest'`

and a positive integer.
If you specify `'Largest'`

, then
`pdist2`

sorts the distances in each column of
`D`

in descending order.

**Example: **`'Largest',3`

**Data Types: **`single`

| `double`

`D`

— Pairwise distancesnumeric matrix

Pairwise distances, returned as a numeric matrix.

If you do not specify either `'Smallest'`

or
`'Largest'`

, then `D`

is an
*mx*-by-*my* matrix, where
*mx* and *my* are the number of
observations in `X`

and `Y`

,
respectively. `D(i,j)`

is the distance between observation
`i`

in `X`

and observation
`j`

in `Y`

. If observation
*i* in `X`

or observation
*j* in `Y`

contains
`NaN`

, then `D(i,j)`

is
`NaN`

for the built-in distance functions.

If you specify either `'Smallest'`

or
`'Largest'`

as `K`

, then
`D`

is a
`K`

-by-*my* matrix.
`D`

contains either the `K`

smallest
or `K`

largest pairwise distances to observations in
`X`

for each observation in `Y`

.
For each observation in `Y`

, `pdist2`

finds the `K`

smallest or largest distances by computing
and comparing the distance values to all the observations in
`X`

. If `K`

is greater than
*mx*, `pdist2`

returns an
*mx*-by-*my* matrix.

`I`

— Sort indexpositive integer matrix

Sort index, returned as a positive integer matrix. `I`

is the same size as `D`

. `I`

contains
the indices of the observations in `X`

corresponding to
the distances in `D`

.

A distance metric is a function that defines a distance between
two observations. `pdist2`

supports various distance
metrics: Euclidean distance, standardized Euclidean distance, Mahalanobis distance,
city block distance, Minkowski distance, Chebychev distance, cosine distance,
correlation distance, Hamming distance, Jaccard distance, and Spearman
distance.

Given an *mx*-by-*n* data
matrix *X*, which is treated as *mx*
(1-by-*n*) row vectors *x _{1}*,

Euclidean distance

$${d}_{st}^{2}=({x}_{s}-{y}_{t})({x}_{s}-{y}_{t}{)}^{\prime}.$$

The Euclidean distance is a special case of the Minkowski distance, where

*p*= 2.Standardized Euclidean distance

$${d}_{st}^{2}=({x}_{s}-{y}_{t}){V}^{-1}({x}_{s}-{y}_{t}{)}^{\prime},$$

where

*V*is the*n*-by-*n*diagonal matrix whose*j*th diagonal element is (*S*(*j*))^{2}, where*S*is a vector of scaling factors for each dimension.Mahalanobis distance

$${d}_{st}^{2}=({x}_{s}-{y}_{t}){C}^{-1}({x}_{s}-{y}_{t}{)}^{\prime},$$

where

*C*is the covariance matrix.City block distance

$${d}_{st}={\displaystyle \sum _{j=1}^{n}\left|{x}_{sj}-{y}_{tj}\right|}.$$

The city block distance is a special case of the Minkowski distance, where

*p*= 1.Minkowski distance

$${d}_{st}=\sqrt[p]{{\displaystyle \sum _{j=1}^{n}{\left|{x}_{sj}-{y}_{tj}\right|}^{p}}}.$$

For the special case of

*p*= 1, the Minkowski distance gives the city block distance. For the special case of*p*= 2, the Minkowski distance gives the Euclidean distance. For the special case of*p*= ∞, the Minkowski distance gives the Chebychev distance.Chebychev distance

$${d}_{st}={\mathrm{max}}_{j}\left\{\left|{x}_{sj}-{y}_{tj}\right|\right\}.$$

The Chebychev distance is a special case of the Minkowski distance, where

*p*= ∞.Cosine distance

$${d}_{st}=\left(1-\frac{{x}_{s}{{y}^{\prime}}_{t}}{\sqrt{\left({x}_{s}{{x}^{\prime}}_{s}\right)\left({y}_{t}{{y}^{\prime}}_{t}\right)}}\right).$$

Correlation distance

$${d}_{st}=1-\frac{\left({x}_{s}-{\overline{x}}_{s}\right){\left({y}_{t}-{\overline{y}}_{t}\right)}^{\prime}}{\sqrt{\left({x}_{s}-{\overline{x}}_{s}\right){\left({x}_{s}-{\overline{x}}_{s}\right)}^{\prime}}\sqrt{\left({y}_{t}-{\overline{y}}_{t}\right){\left({y}_{t}-{\overline{y}}_{t}\right)}^{\prime}}},$$

where

$${\overline{x}}_{s}=\frac{1}{n}{\displaystyle \sum _{j}{x}_{sj}}$$

and

$${\overline{y}}_{t}=\frac{1}{n}{\displaystyle \sum _{j}{y}_{tj}}.$$

Hamming distance

$${d}_{st}=(\#({x}_{sj}\ne {y}_{tj})/n).$$

Jaccard distance

$${d}_{st}=\frac{\#\left[\left({x}_{sj}\ne {y}_{tj}\right)\cap \left(\left({x}_{sj}\ne 0\right)\cup \left({y}_{tj}\ne 0\right)\right)\right]}{\#\left[\left({x}_{sj}\ne 0\right)\cup \left({y}_{tj}\ne 0\right)\right]}.$$

Spearman distance

$${d}_{st}=1-\frac{\left({r}_{s}-{\overline{r}}_{s}\right){\left({r}_{t}-{\overline{r}}_{t}\right)}^{\prime}}{\sqrt{\left({r}_{s}-{\overline{r}}_{s}\right){\left({r}_{s}-{\overline{r}}_{s}\right)}^{\prime}}\sqrt{\left({r}_{t}-{\overline{r}}_{t}\right){\left({r}_{t}-{\overline{r}}_{t}\right)}^{\prime}}},$$

where

*r*is the rank of_{sj}*x*taken over_{sj}*x*_{1j},*x*_{2j}, ...*x*, as computed by_{mx,j}`tiedrank`

.*r*is the rank of_{tj}*y*taken over_{tj}*y*_{1j},*y*_{2j}, ...*y*, as computed by_{my,j}`tiedrank`

.*r*and_{s}*r*are the coordinate-wise rank vectors of_{t}*x*and_{s}*y*, i.e.,_{t}*r*= (_{s}*r*_{s}_{1},*r*_{s}_{2}, ...*r*) and_{sn}*r*= (_{t}*r*_{t1},*r*_{t2}, ...*r*)._{tn}$${\overline{r}}_{s}=\frac{1}{n}{\displaystyle \sum _{j}{r}_{sj}}=\frac{\left(n+1\right)}{2}$$.

$${\overline{r}}_{t}=\frac{1}{n}{\displaystyle \sum _{j}{r}_{tj}}=\frac{\left(n+1\right)}{2}$$.

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

The distance input argument value (

`Distance`

) must be a compile-time constant. For example, to use the Minkowski distance, include`coder.Constant('Minkowski')`

in the`-args`

value of`codegen`

.The distance input argument value (

`Distance`

) cannot be a custom distance function.Names in name-value pair arguments must be compile-time constants. For example, to use the

`'Smallest'`

name-value pair argument in the generated code, include`{coder.Constant('Smallest'),0}`

in the`-args`

value of`codegen`

.The sorted order of tied distances in the generated code can be different from the order in MATLAB

^{®}due to numerical precision.For code generation,

`pdist2`

uses`parfor`

(by default) to create loops that run in parallel on supported shared-memory multicore platforms. If your compiler does not support the Open Multiprocessing (OpenMP) application interface or you disable OpenMP library, MATLAB Coder™ treats the`parfor`

-loops as`for`

-loops. To find supported compilers, see Supported Compilers. To disable OpenMP library, specify the`EnableOpenMP`

property of the`codegen`

configuration object as`false`

. For details, see`coder.CodeConfig`

.

`ExhaustiveSearcher`

| `KDTreeSearcher`

| `createns`

| `knnsearch`

| `pdist`

Was this topic helpful?

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

Select web siteYou can also select a web site from the following list:

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

- América Latina (Español)
- Canada (English)
- United States (English)

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)