GitHub

Distances of Distances

PortfolioOptimisers.DistanceDistance — Type
struct DistanceDistance{__T_metric, __T_args, __T_kwargs, __T_power, __T_alg} <: AbstractDistanceEstimator

Measures how differently two assets relate to the whole universe, by applying a metric to a distance matrix.

Two assets are close under this estimator when their columns of the base distance matrix are close — that is, when they stand at similar distances from every other asset. This is a second-order reading: it can separate two assets that are equally far apart under Distance but occupy different positions in the universe. It wraps a metric from Distances.jl around a base Distance built from power and alg.

Note

power = 1 reproduces the base distance exactly, so the distance-of-distances matrix is the same as at power = nothing. Only $p \geq 2$ changes the result. See Distance for the formula of each algorithm.

Mathematical definition

\[\begin{align} _{g}\tilde{d}_{i,\,j} &= \lVert_{g}\boldsymbol{D}_{i} - _{g}\boldsymbol{D}_{j}\rVert\,, \end{align}\]

Where:

  • $_{g}\tilde{d}_{i,\,j}$: General distance of distances between assets $i$ and $j$.
  • $_{g}\boldsymbol{D}_{i}$: Column $i$ of the generalised distance matrix (see AbstractDistanceAlgorithm).
  • $\lVert \cdot \rVert$: Metric used to compute the distance of distances, metric.

The source states this at the default metric, the Euclidean norm. A base distance matrix is symmetric, so the column and the row give the same answer.

Fields

  • metric: Distance metric used for the distances of distances computations.
  • args: Additional positional arguments for the distances of distances metric.
  • kwargs: Additional keyword arguments for the distances of distances metric.
  • power: Optional matrix exponent. nothing and 1 both give the base distance, so only power >= 2 changes the result.
  • alg: Distance algorithm.

Constructors

DistanceDistance(;    metric::Distances.Metric = Distances.Euclidean(),    args::Tuple = (),    kwargs::NamedTuple = (;),    power::Option{<:Integer} = nothing,    alg::AbstractDistanceAlgorithm = SimpleDistance()) -> DistanceDistance

Keywords correspond to the struct's fields. power and alg are forwarded to a Distance, so they carry the meaning and the defaults documented there.

Validation

  • If power is not nothing, power >= 1.

Examples

julia> DistanceDistance()DistanceDistance  metric ┼ Distances.Euclidean: Distances.Euclidean(0.0)    args ┼ Tuple{}: ()  kwargs ┼ @NamedTuple{}: NamedTuple()   power ┼ nothing     alg ┴ SimpleDistance()
The default metric leaves the unit interval

The Euclidean norm of two columns of a bounded distance matrix is not itself bounded by 1. On a 6-asset sample two thirds of the off-diagonal entries exceeded 1, and the largest was 1.3946164799008962.

ComplementSimilarity is therefore out of domain against this estimator's own default, and assert_similarity_domain refuses the pair on the PMFG path. Use ExponentialSimilarity or GeneralExponentialSimilarity, which have no domain.

Related

References

  • [4] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 12.1.1, Equation 12.1.
source
PortfolioOptimisers.distance — Method
distance(de::DistanceDistance, ce::StatsBase.CovarianceEstimator, X::MatNum;
         dims::Int = 1, kwargs...)

Compute the distance-of-distances matrix from a covariance estimator and data matrix.

This method first computes a base distance matrix using Distance with the specified power and algorithm, then applies the provided metric to compute a second-level distance matrix.

Arguments

  • de: Distance-of-distances estimator.
  • ce: Covariance estimator.
  • X: Data matrix (observations × assets).
  • dims: Dimension along which to perform the computation.
  • kwargs...: Additional keyword arguments passed to the base distance computation.

Returns

  • D::Matrix{<:Number}: Matrix of pairwise distances of distances.

Related

source
PortfolioOptimisers.distance — Method
distance(de::DistanceDistance, rho::MatNum, args...; kwargs...)

Compute the distance-of-distances matrix from a correlation or covariance matrix.

This method first computes a base distance matrix using Distance with the specified power and algorithm, then applies the provided metric to compute a second-level distance matrix.

Arguments

  • de: Distance-of-distances estimator.
  • rho: Correlation or covariance matrix.
  • args...: Additional arguments (ignored).
  • kwargs...: Additional keyword arguments passed to the base distance computation.

Returns

  • D::Matrix{<:Number}: Matrix of pairwise distances of distances.

Related

source
PortfolioOptimisers.cor_and_dist — Method
cor_and_dist(de::DistanceDistance, ce::StatsBase.CovarianceEstimator, X::MatNum;
             dims::Int = 1, kwargs...)

Compute both the correlation matrix and the distance-of-distances matrix from a covariance estimator and data matrix.

This method first computes the correlation and base distance matrices using Distance, then applies the provided metric to the base distance matrix.

Arguments

  • de: Distance-of-distances estimator.
  • ce: Covariance estimator.
  • X: Data matrix (observations × assets).
  • dims: Dimension along which to perform the computation.
  • kwargs...: Additional keyword arguments passed to the base distance computation.

Returns

  • (rho::Matrix{<:Number}, D::Matrix{<:Number}): Tuple of correlation matrix and distance-of-distances matrix.

Related

source

References

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