`Distances.Bregman`

— TypeImplements the Bregman divergence, a friendly introduction to which can be found here. Bregman divergences are a minimal implementation of the "mean-minimizer" property.

It is assumed that the (convex differentiable) function F maps vectors (of any type or size) to real numbers. The inner product used is `Base.dot`

, but one can be passed in either by defining `inner`

or by passing in a keyword argument. If an analytic gradient isn't available, Julia offers a suite of good automatic differentiation packages.

function evaluate(dist::Bregman, p::AbstractVector, q::AbstractVector)

`Distances.Euclidean`

— Method`Euclidean([thresh])`

Create a euclidean metric.

When computing distances among large numbers of points, it can be much more efficient to exploit the formula

`(x-y)^2 = x^2 - 2xy + y^2`

However, this can introduce roundoff error. `thresh`

(which defaults to 0) specifies the relative square-distance tolerance on `2xy`

compared to `x^2 + y^2`

to force recalculation of the distance using the more precise direct (elementwise-subtraction) formula.

**Example:**

```
julia> x = reshape([0.1, 0.3, -0.1], 3, 1);
julia> pairwise(Euclidean(), x, x)
1×1 Array{Float64,2}:
7.45058e-9
julia> pairwise(Euclidean(1e-12), x, x)
1×1 Array{Float64,2}:
0.0
```

`Distances.Haversine`

— Type`Haversine(radius=6_371_000)`

The haversine distance between two locations on a sphere of given `radius`

, whose default value is 6,371,000, i.e., the Earth's (volumetric) mean radius in meters; cf. NASA's Earth Fact Sheet.

Locations are described with longitude and latitude in degrees. The computed distance has the unit of the radius.

`Distances.Mahalanobis`

— Type`Mahalanobis(Q; skipchecks=false) <: Metric`

Create a Mahalanobis distance (i.e., a bilinear form) with covariance matrix `Q`

. Upon construction, both symmetry/self-adjointness and positive semidefiniteness are checked, where the latter check can be skipped by passing the keyword argument `skipchecks = true`

.

**Example:**

```julia julia> A = collect(reshape(1:9, 3, 3)); Q = A'A;

julia> dist = Mahalanobis(Q) Mahalanobis{Matrix{Int64}}([14 32 50; 32 77 122; 50 122 194])

julia> dist = Mahalanobis(A, skipchecks=true) ┌ Warning: matrix is not symmetric/Hermitian └ @ Distances ... Mahalanobis{Matrix{Int64}}([1 4 7; 2 5 8; 3 6 9])

`Distances.PeriodicEuclidean`

— Type`PeriodicEuclidean(L)`

Create a Euclidean metric on a rectangular periodic domain (i.e., a torus or a cylinder). Periods per dimension are contained in the vector `L`

:

\[\sqrt{\sum_i(\min\mod(|x_i - y_i|, p), p - \mod(|x_i - y_i|, p))^2}.\]

For dimensions without periodicity put `Inf`

in the respective component.

**Example**

```
julia> x, y, L = [0.0, 0.0], [0.75, 0.0], [0.5, Inf];
julia> evaluate(PeriodicEuclidean(L), x, y)
0.25
```

`Distances.RenyiDivergence`

— Type```
RenyiDivergence(α::Real)
renyi_divergence(P, Q, α::Real)
```

Create a Rényi premetric of order α.

Rényi defined a spectrum of divergence measures generalising the Kullback–Leibler divergence (see `KLDivergence`

). The divergence is not a semimetric as it is not symmetric. It is parameterised by a parameter α, and is equal to Kullback–Leibler divergence at α = 1:

At α = 0, $R_0(P | Q) = -log(sum_{i: p_i > 0}(q_i))$

At α = 1, $R_1(P | Q) = sum_{i: p_i > 0}(p_i log(p_i / q_i))$

At α = ∞, $R_∞(P | Q) = log(sup_{i: p_i > 0}(p_i / q_i))$

Otherwise $R_α(P | Q) = log(sum_{i: p_i > 0}((p_i ^ α) / (q_i ^ (α - 1))) / (α - 1)$

**Example:**

```
julia> x = reshape([0.1, 0.3, 0.4, 0.2], 2, 2);
julia> pairwise(RenyiDivergence(0), x, x)
2×2 Array{Float64,2}:
0.0 0.0
0.0 0.0
julia> pairwise(Euclidean(2), x, x)
2×2 Array{Float64,2}:
0.0 0.577315
0.655407 0.0
```

`Distances.SphericalAngle`

— Type`SphericalAngle()`

The spherical angle distance between two locations on a sphere.

Locations are described with two angles, longitude and latitude, in radians. The distance is computed with the haversine formula and also has units of radians.

`Distances.SqEuclidean`

— Method`SqEuclidean([thresh])`

Create a squared-euclidean semi-metric. For the meaning of `thresh`

, see `Euclidean`

.

`Distances.SqMahalanobis`

— Type`SqMahalanobis(Q; skipchecks=false) <: Metric`

Create a squared Mahalanobis distance (i.e., a bilinear form) with covariance matrix `Q`

. Upon construction, both symmetry/self-adjointness and positive semidefiniteness are checked, where the latter check can be skipped by passing the keyword argument `skipchecks = true`

.

**Example:**

```julia julia> A = collect(reshape(1:9, 3, 3)); Q = A'A;

julia> dist = SqMahalanobis(Q) SqMahalanobis{Matrix{Int64}}([14 32 50; 32 77 122; 50 122 194])

julia> dist = SqMahalanobis(A, skipchecks=true) ┌ Warning: matrix is not symmetric/Hermitian └ @ Distances ... SqMahalanobis{Matrix{Int64}}([1 4 7; 2 5 8; 3 6 9])

`Distances.colwise!`

— Method`colwise!(r::AbstractArray, dist::PreMetric, a, b)`

Same as `colwise!(dist, r, a, b)`

.

Since this alternative syntax is deprecated and will be removed in a future release of Distances.jl, its use is discouraged. Please call `colwise!(dist, r, a, b)`

instead.

`Distances.colwise!`

— Method```
colwise!(metric::PreMetric, r::AbstractArray,
a::AbstractMatrix, b::AbstractMatrix)
colwise!(metric::PreMetric, r::AbstractArray,
a::AbstractVector, b::AbstractMatrix)
colwise!(metric::PreMetric, r::AbstractArray,
a::AbstractMatrix, b::AbstractVector)
```

Compute distances between each corresponding columns of `a`

and `b`

according to distance `metric`

, and store the result in `r`

. Exactly one of `a`

or `b`

can be a vector, in which case the distance between that vector and all columns of the other matrix are computed.

`a`

and `b`

must have the same number of columns if neither of the two is a vector. `r`

must be an array of length `maximum(size(a, 2), size(b, 2))`

.

If both `a`

and `b`

are vectors, the generic, iterator-based method of `colwise`

applies.

`Distances.colwise!`

— Method`colwise!(metric::PreMetric, r::AbstractArray, a, b)`

Compute distances between corresponding elements of the iterable collections `a`

and `b`

according to distance `metric`

, and store the result in `r`

.

`a`

and `b`

must have the same number of elements, `r`

must be an array of length `length(a) == length(b)`

.

`Distances.colwise`

— Method```
colwise(metric::PreMetric, a::AbstractMatrix, b::AbstractMatrix)
colwise(metric::PreMetric, a::AbstractVector, b::AbstractMatrix)
colwise(metric::PreMetric, a::AbstractMatrix, b::AbstractVector)
```

Compute distances between corresponding columns of `a`

and `b`

according to distance `metric`

. Exactly one of `a`

or `b`

can be a vector, in which case the distance between that vector and all columns of the other matrix are computed.

`a`

and `b`

must have the same number of columns if neither of the two is a vector.

If both `a`

and `b`

are vectors, the generic, iterator-based method of `colwise`

applies.

`Distances.colwise`

— Method`colwise(metric::PreMetric, a, b)`

Compute distances between corresponding elements of the iterable collections `a`

and `b`

according to distance `metric`

.

`a`

and `b`

must have the same number of elements (`length(a) == length(b)`

).

`Distances.renyi_divergence`

— Function`Distances.result_type`

— Method```
result_type(dist, Ta::Type, Tb::Type) -> T
result_type(dist, a, b) -> T
```

Infer the result type of metric `dist`

with input types `Ta`

and `Tb`

, or element types of iterators `a`

and `b`

.

`StatsAPI.pairwise!`

— Method`pairwise!(r::AbstractMatrix, dist::PreMetric, a::AbstractMatrix, b::AbstractMatrix; dims)`

Same as `pairwise!(dist, r, a, b; dims)`

.

Since this alternative syntax is deprecated and will be removed in a future release of Distances.jl, its use is discouraged. Please call `pairwise!(dist, r, a, b; dims)`

instead.

`StatsAPI.pairwise!`

— Method`pairwise!(r::AbstractMatrix, dist::PreMetric, a::AbstractMatrix; dims)`

Same as `pairwise!(dist, r, a; dims)`

.

```
!!! warning
Since this alternative syntax is deprecated and will be removed in a future release of
Distances.jl, its use is discouraged. Please call `pairwise!(dist, r, a; dims)` instead.
```

`StatsAPI.pairwise!`

— Method`pairwise!(r::AbstractMatrix, dist::PreMetric, a, b)`

Same as `pairwise!(dist, r, a, b)`

.

Since this alternative syntax is deprecated and will be removed in a future release of Distances.jl, its use is discouraged. Please call `pairwise!(dist, r, a, b)`

instead.

`StatsAPI.pairwise!`

— Method`pairwise!(r::AbstractMatrix, dist::PreMetric, a)`

Same as `pairwise!(dist, r, a)`

.

Since this alternative syntax is deprecated and will be removed in a future release of Distances.jl, its use is discouraged. Please call `pairwise!(dist, r, a)`

instead.

`StatsAPI.pairwise!`

— Method```
pairwise!(metric::PreMetric, r::AbstractMatrix,
a::AbstractMatrix, b::AbstractMatrix=a; dims)
```

Compute distances between each pair of rows (if `dims=1`

) or columns (if `dims=2`

) in `a`

and `b`

according to distance `metric`

, and store the result in `r`

. If a single matrix `a`

is provided, compute distances between its rows or columns.

`a`

and `b`

must have the same numbers of columns if `dims=1`

, or of rows if `dims=2`

. `r`

must be a matrix with size `size(a, dims) × size(b, dims)`

.

`StatsAPI.pairwise!`

— Method`pairwise!(metric::PreMetric, r::AbstractMatrix, a, b=a)`

Compute distances between each element of collection `a`

and each element of collection `b`

according to distance `metric`

, and store the result in `r`

. If a single iterable `a`

is provided, compute distances between its elements.

`r`

must be a matrix with size `length(a) × length(b)`

.

`StatsAPI.pairwise`

— Method`pairwise(metric::PreMetric, a::AbstractMatrix, b::AbstractMatrix=a; dims)`

Compute distances between each pair of rows (if `dims=1`

) or columns (if `dims=2`

) in `a`

and `b`

according to distance `metric`

. If a single matrix `a`

is provided, compute distances between its rows or columns.

`a`

and `b`

must have the same numbers of columns if `dims=1`

, or of rows if `dims=2`

.

`StatsAPI.pairwise`

— Method`pairwise(metric::PreMetric, a, b=a)`

Compute distances between each element of collection `a`

and each element of collection `b`

according to distance `metric`

. If a single iterable `a`

is provided, compute distances between its elements.