GitHub

Distance Covariance

PortfolioOptimisers.DistanceCovariance — Type
struct DistanceCovariance{__T_metric, __T_args, __T_kwargs, __T_w, __T_ex} <: AbstractCovarianceEstimator

Measures linear and non-linear codependence from doubly-centred pairwise distance matrices.

The statistic is the distance covariance, which is zero if and only if the two series are independent. metric, args and kwargs configure the pairwise distance; w weights the observations and ex selects the parallel execution strategy.

Fields

  • metric: Distance metric used for pairwise computations.
  • args: Additional positional arguments for the distance metric.
  • kwargs: Additional keyword arguments for the distance metric.
  • w: Optional observation weights vector observations × 1, or a concrete subtype of DynamicAbstractWeights. If nothing, the computation is unweighted.
  • ex: Parallel execution strategy.

Constructors

DistanceCovariance(;    metric::Distances.Metric = Distances.Euclidean(),    args::Tuple = (),    kwargs::NamedTuple = (;),    w::Option{<:ObsWeights} = nothing,    ex::FLoops.Transducers.Executor = ThreadedEx()) -> DistanceCovariance

Keywords correspond to the struct's fields.

Propagated parameters

When factory is called on this type, the following @wprop-tagged field is automatically propagated:

Observation weight parameters

When obs_weights_view is called on this type, the following fields are automatically indexed to the selected observations:

Examples

julia> DistanceCovariance()DistanceCovariance  metric ┼ Distances.Euclidean: Distances.Euclidean(0.0)    args ┼ Tuple{}: ()  kwargs ┼ @NamedTuple{}: NamedTuple()       w ┼ nothing      ex ┴ Transducers.ThreadedEx{@NamedTuple{}}: Transducers.ThreadedEx()

Related

References

  • [16] G. J. Székely, M. L. Rizzo and N. K. Bakirov. Measuring and testing dependence by correlation of distances. The Annals of Statistics 35, 2769–2794 (2007).
  • [5] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 6.1.5, equations 6.9 to 6.13.
source
Statistics.cov — Method
Statistics.cov(ce::DistanceCovariance, X::MatNum; dims::Int = 1, kwargs...)

Compute the pairwise distance covariance matrix for all columns in a data matrix using a configured DistanceCovariance estimator.

This method overrides the generic covariance fallback, which DistanceCovariance cannot use because it carries no variance estimator field. So the diagonal is the distance standard deviation of each asset and not the sample standard deviation, and the matrix that cor(ce::DistanceCovariance, X::MatNum; dims::Int = 1, kwargs...) returns is exactly this matrix rescaled by the square roots of that diagonal.

Algorithm

  1. Orient X with dims_oriented, which transposes it when dims is 2 and refuses any other value.
  2. Resolve the estimator's w field against the oriented matrix with get_observation_weights, giving nothing for an unweighted estimator.
  3. Return cov_distance(ce::DistanceCovariance, X::MatNum) of the oriented matrix and those weights.

Arguments

  • ce: Distance covariance estimator.
  • X: Data matrix (observations × assets).
  • dims: Dimension along which to perform the computation.
  • kwargs...: Additional keyword arguments (currently unused).

Validation

  • dims is either 1 or 2.

Returns

  • sigma::Matrix{<:Number}: Symmetric matrix of pairwise distance covariances.

Examples

julia> ce = DistanceCovariance()DistanceCovariance  metric ┼ Distances.Euclidean: Distances.Euclidean(0.0)    args ┼ Tuple{}: ()  kwargs ┼ @NamedTuple{}: NamedTuple()       w ┼ nothing      ex ┴ Transducers.ThreadedEx{@NamedTuple{}}: Transducers.ThreadedEx()julia> X = [1.0 2.0; 2.0 4.0; 3.0 6.0];julia> cov(ce, X)2×2 Matrix{Float64}: 0.702728  0.993808 0.993808  1.40546

Related

source
Statistics.cor — Method
Statistics.cor(ce::DistanceCovariance, X::MatNum; dims::Int = 1, kwargs...)

Compute the pairwise distance correlation matrix for all columns in a data matrix using a configured DistanceCovariance estimator.

Algorithm

  1. Orient X with dims_oriented, which transposes it when dims is 2 and refuses any other value.
  2. Resolve the estimator's w field against the oriented matrix with get_observation_weights, giving nothing for an unweighted estimator.
  3. Return cor_distance(ce::DistanceCovariance, X::MatNum) of the oriented matrix and those weights.

Arguments

  • ce: Distance covariance estimator.
  • X: Data matrix (observations × assets).
  • dims: Dimension along which to perform the computation.
  • kwargs...: Additional keyword arguments (currently unused).

Validation

  • dims is either 1 or 2.

Returns

  • rho::Matrix{<:Number}: Symmetric matrix of pairwise distance correlations, with a diagonal of exactly 1.0.

Examples

julia> ce = DistanceCovariance()DistanceCovariance  metric ┼ Distances.Euclidean: Distances.Euclidean(0.0)    args ┼ Tuple{}: ()  kwargs ┼ @NamedTuple{}: NamedTuple()       w ┼ nothing      ex ┴ Transducers.ThreadedEx{@NamedTuple{}}: Transducers.ThreadedEx()julia> X = [1.0 2.0; 2.0 4.0; 3.0 6.0];julia> cor(ce, X)2×2 Matrix{Float64}: 1.0  1.0 1.0  1.0

Related

source

References

[5]
D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025).
[16]
G. J. Székely, M. L. Rizzo and N. K. Bakirov. Measuring and testing dependence by correlation of distances. The Annals of Statistics 35, 2769–2794 (2007).