Implements 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)

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

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.

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])

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

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

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.

SqEuclidean([thresh])

Create a squared-euclidean semi-metric. For the meaning of thresh, see Euclidean.

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])

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

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

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)).

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).

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.

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)).

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.

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

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

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.

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

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

pairwise!(r::AbstractMatrix, dist::PreMetric, a)

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

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).

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).

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.

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.