Base Distance
PortfolioOptimisers.SimpleDistance — Type
struct SimpleDistance <: AbstractDistanceAlgorithmTurns a signed correlation into a distance by $\sqrt{(1 - \rho) / 2}$.
The halving keeps the result in $[0,\,1]$ over the whole signed range of the correlation, which is what makes this the algorithm for a codependence measure on $[-1,\,1]$: Pearson, Spearman, Kendall and the Gerber statistic.
Mathematical definition
\[\begin{align} d_{i,\,j} &= \sqrt{\mathrm{clamp}\left(\dfrac{1 - \rho_{i,\,j}}{2},\, 0,\, 1\right)}\,, \end{align}\]
Where:
- $d_{i,\,j}$: Pairwise distance between assets $i$ and $j$.
- $\rho_{i,\,j}$: Pairwise correlation coefficient between assets $i$ and $j$.
The clamp is a numerical guard and nothing more. $(1 - \rho_{i,\,j}) / 2$ already lies in $[0,\,1]$ for every $\lvert\rho_{i,\,j}\rvert \leq 1$, so it binds only on a correlation that a shrinking, denoising or repairing estimator pushed a hair outside $[-1,\,1]$. Contrast CorrelationDistance, where the same clamp binds on ordinary data.
Related
AbstractDistanceAlgorithmAbstractDistanceEstimatorSimpleAbsoluteDistanceCorrelationDistancedistancecor_and_dist
References
PortfolioOptimisers.SimpleAbsoluteDistance — Type
struct SimpleAbsoluteDistance <: AbstractDistanceAlgorithmTurns the magnitude of a correlation into a distance by $\sqrt{1 - \lvert\rho\rvert}$.
Reading the magnitude discards the sign, so two assets that move together and two that move oppositely are equally close. This is the algorithm for a codependence measure that is already non-negative, and for the case where only the strength of the relationship matters.
Mathematical definition
\[\begin{align} d_{i,\,j} &= \sqrt{\mathrm{clamp}\left(1 - \lvert\rho_{i,\,j}\rvert,\, 0,\, 1\right)}\,, \end{align}\]
Where:
- $d_{i,\,j}$: Pairwise distance between assets $i$ and $j$.
- $\rho_{i,\,j}$: Pairwise correlation coefficient between assets $i$ and $j$.
The clamp is a numerical guard and nothing more, as in SimpleDistance: $1 - \lvert\rho_{i,\,j}\rvert$ already lies in $[0,\,1]$ for every $\lvert\rho_{i,\,j}\rvert \leq 1$.
The magnitude comes from _absguard, which is an allocation guard and not a branch in the mathematics. A matrix with no negative entry is returned as the same object, and abs. of such a matrix equals it entry for entry, so both routes give the identical result for every input, -0.0 included. A non-negative codependence measure therefore reaches this algorithm unchanged, and pays no allocation for the guard.
Related
AbstractDistanceAlgorithmAbstractDistanceEstimatorSimpleDistanceCorrelationDistancedistancecor_and_dist
References
PortfolioOptimisers.LogDistance — Type
struct LogDistance <: AbstractDistanceAlgorithmTurns the magnitude of a correlation into an unbounded distance by $-\log\lvert\rho\rvert$.
The range is $[0,\,\infty)$ rather than $[0,\,1]$, so the distance grows without limit as the relationship weakens. This is the algorithm for a tail dependence coefficient, and the one CanonicalDistance selects for LowerTailDependenceCovariance.
Mathematical definition
\[\begin{align} d_{i,\,j} &= \max\left(-\log{\lvert\rho_{i,\,j}\rvert},\, 0\right)\,, \end{align}\]
Where:
- $d_{i,\,j}$: Pairwise distance between assets $i$ and $j$.
- $\rho_{i,\,j}$: Pairwise correlation coefficient between assets $i$ and $j$.
The floor at zero is not cosmetic. A covariance estimator that shrinks, denoises or repairs a matrix can return $\lvert\rho_{i,\,j}\rvert$ a hair above one, and $-\log$ of that is negative — unlike the square-root algorithms, which already clamp before taking the root. A negative distance inverts the ordering it is meant to express and is unsound under the shortest-path routines that consume it.
Perfectly uncorrelated assets remain infinitely far apart: $\rho_{i,\,j} = 0$ gives $d_{i,\,j} = \infty$, which is a meaningful value here and is left alone. It is also the entry that the two bounded similarity members cannot take, so assert_similarity_domain refuses this algorithm under MaximumDistanceSimilarity on the PMFG path.
The magnitude comes from _absguard, as in SimpleAbsoluteDistance. It is an allocation guard and not a branch in the mathematics: a matrix with no negative entry is returned as the same object, and the result is identical to taking abs. unconditionally.
Related
AbstractDistanceAlgorithmAbstractDistanceEstimatorLowerTailDependenceCovarianceCanonicalDistanceassert_similarity_domaindistancecor_and_dist
References
- [4] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 6.2.3, Equation 6.26.
- [16] G. De Luca and P. Zuccolotto. A tail dependence-based dissimilarity measure for financial time series clustering. Advances in Data Analysis and Classification 5, 323–340 (2011).
PortfolioOptimisers.CorrelationDistance — Type
struct CorrelationDistance <: AbstractDistanceAlgorithmTurns a non-negative codependence into a distance by $\sqrt{1 - \rho}$, without halving.
This is SimpleAbsoluteDistance with the absolute value dropped, and it is the algorithm for a codependence measure whose own range is $[0,\,1]$. It is what CanonicalDistance selects for DistanceCovariance.
Mathematical definition
\[\begin{align} d_{i,\,j} &= \sqrt{\mathrm{clamp}\left(1 - \rho_{i,\,j},\, 0,\, 1\right)}\,, \end{align}\]
Where:
- $d_{i,\,j}$: Pairwise distance between assets $i$ and $j$.
- $\rho_{i,\,j}$: Pairwise correlation coefficient between assets $i$ and $j$.
This is the one algorithm in the family whose clamp is not a numerical guard. Without the halving, $1 - \rho_{i,\,j}$ runs over $[0,\,2]$ on a signed correlation, so the clamp truncates every negative entry to a distance of exactly 1.
At $\rho_{i,\,j} = -0.9311319132604445$ the algorithm returns 1.0 where $\sqrt{1 - \rho_{i,\,j}}$ is 1.3896517237280874. The truncation is not monotone: $\rho_{i,\,j} = -0.1$ and $\rho_{i,\,j} = -1$ are both reported as 1, so the ordering the distance is meant to express is lost across the whole negative half.
The intended domain has no negative entry. Give a signed correlation to SimpleDistance, which halves and therefore never saturates, or to SimpleAbsoluteDistance, which reads the magnitude.
Related
AbstractDistanceAlgorithmAbstractDistanceEstimatorSimpleDistanceSimpleAbsoluteDistanceDistanceCovarianceCanonicalDistancedistancecor_and_dist
References
- [4] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 6.2.1, Equation 6.23.
PortfolioOptimisers.VariationInfoDistance — Type
struct VariationInfoDistance{__T_bins, __T_normalise} <: AbstractDistanceAlgorithmMeasures the information one asset loses about another, from the entropies of a joint histogram.
This is the only algorithm in the family that reads the data matrix rather than a correlation matrix, so it captures a non-linear relationship that no correlation coefficient sees. It is what CanonicalDistance selects for MutualInfoCovariance.
Mathematical definition
\[\begin{align} d_{i,\,j} &= H(X_{i}) + H(X_{j}) - 2\,I(X_{i};X_{j})\,, \end{align}\]
When normalise is true, the result is divided by the joint entropy:
\[\begin{align} \tilde{d}_{i,\,j} &= \dfrac{H(X_{i}) + H(X_{j}) - 2\,I(X_{i};X_{j})}{H(X_{i}) + H(X_{j}) - I(X_{i};X_{j})}\,. \end{align}\]
Where:
- $d_{i,\,j}$: Pairwise variation of information between assets $i$ and $j$.
- $\tilde{d}_{i,\,j}$: Normalised pairwise variation of information.
- $H(X_{i})$: Marginal Shannon entropy of asset $i$, estimated from a histogram whose bin count comes from
bins. - $I(X_{i};X_{j})$: Mutual information between assets $i$ and $j$.
Equation 6.25 of the source normalises by $\max(H(X_{i}),\, H(X_{j}))$ instead. This algorithm divides by the joint entropy, which keeps the result a metric on $[0,\,1]$. See variation_info, which computes it.
Algorithm
This is the only algorithm of the family that runs a procedure rather than applying a closed form to a correlation entry. variation_info carries out the steps; bins and normalise are the two fields below.
- Take the number of histogram bins from
bins. AnIntegeris that count; a bin-width rule computes the count from the sample size and the pairwise correlation. - Build the joint histogram of the two asset columns over that bin count, giving the joint distribution.
- Reduce the joint histogram along each axis, giving the two marginal distributions.
- Take the Shannon entropy of each marginal and of the joint histogram, giving $H(X_{i})$, $H(X_{j})$ and $H(X_{i},\,X_{j})$.
- Form the mutual information $I(X_{i};X_{j}) = H(X_{i}) + H(X_{j}) - H(X_{i},\,X_{j})$, and from it the variation of information of the first formula above.
- When
normaliseistrue, divide by the joint entropy $H(X_{i}) + H(X_{j}) - I(X_{i};X_{j})$, giving the second formula.
Fields
bins: Binning algorithm or fixed number of bins.
normalise: Whether to normalise the mutual and/or variation of information calculation.
Constructors
VariationInfoDistance(; bins::Int_Bin = HacineGharbiRavier(), normalise::Bool = true) -> VariationInfoDistanceKeywords correspond to the struct's fields.
Validation
- If
binsis an integer,0 < bins <= RESOURCE_LIMITS[].max_bins(the joint histogram isbins × bins; seeRESOURCE_LIMITS).
Examples
julia> VariationInfoDistance()VariationInfoDistance bins ┼ HacineGharbiRavier() normalise ┴ Bool: trueRelated
References
PortfolioOptimisers.CanonicalDistance — Type
struct CanonicalDistance <: AbstractDistanceAlgorithmSelects the distance algorithm that matches the covariance estimator it is given.
It owns no formula of its own. It is a redirect, and it exists so that a codependence measure reaches the distance transform its own range calls for: a signed correlation must be halved, a mutual information has no correlation to transform at all, and a tail dependence coefficient wants an unbounded distance.
| Covariance Estimator | Distance Metric |
|---|---|
MutualInfoCovariance | VariationInfoDistance |
LowerTailDependenceCovariance | LogDistance |
DistanceCovariance | CorrelationDistance |
StatsBase.CovarianceEstimator | SimpleDistance |
The table also applies to PortfolioOptimisersCovariance where ce is one of the aforementioned estimators.
When used with a covariance matrix directly, uses SimpleDistance.
Related
PortfolioOptimisers.AbstractDistanceEstimator — Type
abstract type AbstractDistanceEstimator <: AbstractEstimatorAbstract supertype for all distance estimator types.
All concrete and/or abstract types implementing distance-based estimation algorithms should be subtypes of AbstractDistanceEstimator.
Related
PortfolioOptimisers.AbstractDistanceAlgorithm — Type
abstract type AbstractDistanceAlgorithm <: AbstractAlgorithmAbstract supertype for all distance algorithm types.
All concrete and/or abstract types implementing specific distance-based algorithms (such as correlation distance, absolute distance, log distance, or information-theoretic distances) should be subtypes of AbstractDistanceAlgorithm.
Related
References
- [4]
- D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025).
- [7]
- M. M. De Prado. Machine learning for asset managers (Cambridge University Press, 2020).
- [16]
- G. De Luca and P. Zuccolotto. A tail dependence-based dissimilarity measure for financial time series clustering. Advances in Data Analysis and Classification 5, 323–340 (2011).