Distance

PortfolioOptimisers.Distance — Type

struct Distance{__T_power, __T_alg} <: AbstractDistanceEstimator

Pairs a distance algorithm with an optional integer power, and applies it to a correlation matrix or to the data.

This is the estimator every clustering, network and phylogeny routine reaches for a distance matrix. alg chooses the transform; power raises the quantity that transform is built on to the integer power $p$, which sharpens the contrast between a strong relationship and a weak one.

Note

power = 1 reproduces the base distance exactly, for every algorithm. It is the neutral position of the knob, not a way to select the generalised estimator. Only $p \geq 2$ changes the result. power = nothing and power = 1 are kept apart by dispatch alone, so that the base case never raises a matrix to a power.

Mathematical definition

The four correlation-based algorithms (see RhoDistanceAlgorithm) raise the correlation to $p$ inside their own base formula.

\[\begin{align} _{g}d_{i,\,j}^{\mathrm{S}} &= \sqrt{\mathrm{clamp}\left(s\left(1 - \rho_{i,\,j}^{p}\right),\, 0,\, 1\right)}\\ _{g}d_{i,\,j}^{\mathrm{SA}} &= \sqrt{\mathrm{clamp}\left(1 - \lvert\rho_{i,\,j}\rvert^{p},\, 0,\, 1\right)}\\ _{g}d_{i,\,j}^{\mathrm{L}} &= \max\left(-\log{\lvert\rho_{i,\,j}\rvert^{p}},\, 0\right)\\ _{g}d_{i,\,j}^{\mathrm{C}} &= \sqrt{\mathrm{clamp}\left(1 - \rho_{i,\,j}^{p},\, 0,\, 1\right)}\\ s &= \begin{cases} 1/2 & \text{if } p \mod 2 \neq 0\\ 1 & \text{otherwise} \end{cases}\,, \end{align}\]

VariationInfoDistance has no correlation to raise, so it raises the distance itself.

\[\begin{align} _{g}d_{i,\,j}^{\mathrm{VI}} &= \left(d_{i,\,j}^{\mathrm{VI}}\right)^{p}\,, \end{align}\]

Where:

$_{g}d_{i,\,j}$: Generalised distance between assets $i$ and $j$, superscripted by the algorithm: SimpleDistance (S), SimpleAbsoluteDistance (SA), LogDistance (L), CorrelationDistance (C), VariationInfoDistance (VI).
$d_{i,\,j}$: Base distance computed using the specified distance algorithm.
$\rho_{i,\,j}$: Pairwise correlation coefficient between assets $i$ and $j$.
$p$: Integer power.
$s$: Scaling factor of SimpleDistance alone ($s = 1/2$ if $p \bmod 2 \neq 0$, else $s = 1$).

The two cases of $s$ are not a convention. $s$ is the normalisation that keeps the radicand inside $[0,\,1]$ over the reachable range of $\rho_{i,\,j}^{p}$, so it is $1 / (1 - m)$, where $m$ is the smallest value $\rho_{i,\,j}^{p}$ can take. An odd $p$ keeps the sign, so $m = -1$ and $s = 1/2$. An even $p$ cannot be negative, so $m = 0$ and $s = 1$.

The clamp is inert for the first two algorithms at every $p$: $s(1 - \rho_{i,\,j}^{p})$ and $1 - \lvert\rho_{i,\,j}\rvert^{p}$ never leave $[0,\,1]$. It binds for CorrelationDistance at every odd $p$, where $\rho_{i,\,j}^{p}$ keeps its sign and the radicand runs over $[0,\,2]$; that algorithm's own docstring measures the truncation.

CanonicalDistance is a redirect and owns no formula. It forwards power to the algorithm it selects.

`power` raises two different quantities

The field is one field, and the reader must not assume one meaning. For a correlation-based algorithm it raises the correlation, inside the transform. For VariationInfoDistance there is no correlation to raise, so it raises the distance the algorithm returns. So $_{g}d^{\mathrm{S}}$ at $p = 2$ is not $\left(d^{\mathrm{S}}\right)^{2}$, while $_{g}d^{\mathrm{VI}}$ at $p = 2$ is $\left(d^{\mathrm{VI}}\right)^{2}$.

The source carries the four base formulas alone. Section 6.2 of the reference below ends at the tail dissimilarity, so the $p$ generalisation and the scaling $s$ are this library's own extension of it.

Fields

power: Optional matrix exponent. nothing and 1 both give the base distance, so only power >= 2 changes the result.

alg: Distance algorithm.

Constructors

Distance(;    power::Option{<:Integer} = nothing,    alg::AbstractDistanceAlgorithm = SimpleDistance()) -> Distance

Keywords correspond to the struct's fields.

Why the default `alg` is `SimpleDistance`

CanonicalDistance picks an algorithm from the covariance estimator, and falls back to SimpleDistance when the estimator carries no preference. A bare Distance() also serves the matrix entry point distance(de, rho), which holds no estimator to pick from. The two therefore agree except on the estimators CanonicalDistance treats specially. Library entry points that always hold a covariance estimator default to Distance(; alg = CanonicalDistance()) instead, so that the special cases are honoured.

Validation

If power is not nothing, power >= 1.

Examples

julia> Distance()Distance  power ┼ nothing    alg ┴ SimpleDistance()

Related

References

[4] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 6.2.

Covariance estimator	Algorithm selected	Read from `ce`
`MutualInfoCovariance`	`VariationInfoDistance`	`ce.bins`, `ce.normalise`
`PortfolioOptimisersCovariance` wrapping it	`VariationInfoDistance`	`ce.ce.bins`, `ce.ce.normalise`
`LowerTailDependenceCovariance`, wrapped or not	`LogDistance`	nothing
`DistanceCovariance`, wrapped or not	`CorrelationDistance`	nothing
any other `StatsBase.CovarianceEstimator`	`SimpleDistance`	nothing