Distance Covariance

PortfolioOptimisers.DistanceCovariance Type

struct DistanceCovariance{__T_metric, __T_args, __T_kwargs, __T_w, __T_ex} <: AbstractCovarianceEstimator

A flexible container type for configuring and applying distance-based covariance estimators in PortfolioOptimisers.jl.

DistanceCovariance encapsulates all components required for distance covariance or correlation estimation, including the distance metric, additional arguments and keyword arguments for the metric, optional weights, and parallel execution strategy.

Fields

• metric: metric: Distance metric used for pairwise computations.

• args: args: Additional positional arguments for the distance metric.

• kwargs: kwargs: Additional keyword arguments for the distance metric.

• w: w: Optional observation weights vector observations × 1, or a concrete subtype of DynamicAbstractWeights. If nothing, the computation is unweighted.

• ex: 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 @fprop-tagged fields are automatically propagated:

• w: Replaced with the incoming ObsWeights.

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

• AbstractCovarianceEstimator

• Distances.Metric

• StatsBase.AbstractWeights

• FLoops.Transducers.Executor

• factory

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.

Arguments

• ce: Distance covariance estimator.

• X: Data matrix (observations × assets).

• dims: Dimension along which to perform the computation.

• kwargs...: Additional keyword arguments (currently unused).

Returns

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

Validation

• dims is either 1 or 2.

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

• DistanceCovariance

• cov_distance(ce::DistanceCovariance, X::MatNum)

• cor(ce::DistanceCovariance, X::MatNum; dims::Int = 1, kwargs...)

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.

Arguments

• ce: Distance covariance estimator.

• X: Data matrix (observations × assets).

• dims: Dimension along which to perform the computation.

• kwargs...: Additional keyword arguments (currently unused).

Returns

• rho::Matrix{<:Number}: Symmetric matrix of pairwise distance correlations.

Validation

• dims is either 1 or 2.

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

• DistanceCovariance

• cor_distance(ce::DistanceCovariance, X::MatNum)

• cov(ce::DistanceCovariance, X::MatNum; dims::Int = 1, kwargs...)

source

PortfolioOptimisers.calc_pairwise_dists Method

calc_pairwise_dists(ce::DistanceCovariance, v1::VecNum, v2::VecNum, w::Option{<:StatsBase.AbstractWeights}) -> (MatNum, MatNum)

Compute pairwise distance matrices between two vectors using the configured metric.

Internal helper used in distance correlation computation. Handles weighted and unweighted cases.

Arguments

• ce: DistanceCovariance estimator with metric configuration.

• v1, v2: Data vectors.

• w: Observation weights (nothing for unweighted, StatsBase.AbstractWeights for weighted).

Returns

• Tuple of pairwise distance matrices (D1, D2).

Related

• DistanceCovariance

• cor_distance

source

PortfolioOptimisers.cor_distance Function

cor_distance(ce::DistanceCovariance, v1::VecNum, v2::VecNum)

Compute the distance correlation between two vectors using a configured DistanceCovariance estimator.

This function computes the distance correlation between v1 and v2 using the specified distance metric, optional weights, and any additional arguments or keyword arguments provided in the estimator. The computation follows the standard distance correlation procedure, centering the pairwise distance matrices and normalizing the result.

Mathematical definition

Let $a_{kl}=d(v_{1k},v_{1l})$ and $b_{kl}=d(v_{2k},v_{2l})$ be pairwise distance matrices. Define doubly-centered versions:

$$\begin{array}{rl}{A}_{kl}& =a_{kl}-{\overline{a}}_{k\cdot }-{\overline{a}}_{\cdot l}+{\overline{a}}_{\cdot \cdot },\\ B_{kl}& =b_{kl}-{\overline{b}}_{k\cdot }-{\overline{b}}_{\cdot l}+{\overline{b}}_{\cdot \cdot }.\end{array}$$

Where:

• $a_{kl}$, $b_{kl}$: Pairwise distances between observations $k$ and $l$.

• ${\overline{a}}_{k\cdot }$: $k$-th row mean of $\mathbf{a}$.

• ${\overline{a}}_{\cdot l}$: $l$-th column mean of $\mathbf{a}$.

• ${\overline{a}}_{\cdot \cdot }$: Grand mean of $\mathbf{a}$.

The squared distance covariances and distance correlation are:

$$\begin{array}{rl}{\widehat{\mathrm{dCov}}}^2(X,X)& =\frac{\mathbf{A}:\mathbf{A}}{n^2},\\ {\widehat{\mathrm{dCov}}}^2(X,Y)& =\frac{\mathbf{A}:\mathbf{B}}{n^2},\\ {\widehat{\mathrm{dCov}}}^2(Y,Y)& =\frac{\mathbf{B}:\mathbf{B}}{n^2}.\end{array}$$

Where:

• $n$: Number of observations.

• $\mathbf{A}:\mathbf{B}=\sum _{k,l}{A}_{kl}{B}_{kl}$: Frobenius inner product.

$$\begin{array}{rl}{\hat{R}}_{\mathrm{dist}}(X,Y)& =\frac{\sqrt{{\widehat{\mathrm{dCov}}}^2(X,Y)}}{\sqrt{\sqrt{{\widehat{\mathrm{dCov}}}^2(X,X)}\cdot \sqrt{{\widehat{\mathrm{dCov}}}^2(Y,Y)}}}.\end{array}$$

Where:

• ${\hat{R}}_{\mathrm{dist}}(X,Y)$: Distance correlation between $X$ and $Y$.

Arguments

• ce: Distance covariance estimator.

• v1: First data vector.

• v2: Second data vector.

Returns

• rho::Float64: The computed distance correlation between v1 and v2.

Details

1. Computes pairwise distance matrices for v1 and v2 using the estimator's metric and configuration.

2. Centers the distance matrices by subtracting row and column means and adding the grand mean.

3. Computes the squared distance covariance and normalizes to obtain the distance correlation.

Validation

• length(v1) == length(v2).

• length(v1) > 1.

Related

• DistanceCovariance

• cor_distance(ce::DistanceCovariance, X::MatNum)

source

PortfolioOptimisers.cov_distance Function

cov_distance(ce::DistanceCovariance, v1::VecNum, v2::VecNum)

Compute the distance covariance between two vectors using a configured DistanceCovariance estimator.

This function computes the distance covariance between v1 and v2 using the specified distance metric, optional weights, and any additional arguments or keyword arguments provided in the estimator. The computation follows the standard distance covariance procedure, centering the pairwise distance matrices and aggregating the result.

Mathematical definition

Using the same doubly-centered matrices $\mathbf{A}$ and $\mathbf{B}$ as in cor_distance:

$$\begin{array}{rl}\widehat{\mathrm{dCov}}(X,Y)& =\sqrt{\left|\frac{\mathbf{A}:\mathbf{B}}{n^2}\right|}.\end{array}$$

Where:

• $\widehat{\mathrm{dCov}}(X,Y)$: Distance covariance between $X$ and $Y$.

• $n$: Number of observations.

• $\mathbf{A}:\mathbf{B}=\sum _{k,l}{A}_{kl}{B}_{kl}$: Frobenius inner product of doubly-centered distance matrices.

Arguments

• ce: Distance covariance estimator.

• v1: First data vector.

• v2: Second data vector.

Returns

• rho::Number: The computed distance covariance between v1 and v2.

Details

1. Computes pairwise distance matrices for v1 and v2 using the estimator's metric and configuration.

2. Centers the distance matrices by subtracting row and column means and adding the grand mean.

3. Computes the squared distance covariance and returns its square root.

Validation

• length(v1) == length(v2).

• length(v1) > 1.

Related

• DistanceCovariance

• cov_distance(ce::DistanceCovariance, X::MatNum)

source

PortfolioOptimisers.cor_distance Function

cor_distance(ce::DistanceCovariance, X::MatNum)

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

This function computes the distance correlation between each pair of columns in X, using the specified distance metric, optional weights, and parallel execution strategy. The resulting matrix is symmetric, with each entry representing the distance correlation between two assets.

Arguments

• ce: Distance covariance estimator.

• X: Data matrix (observations × assets).

Returns

• rho::Matrix{<:Number}: Distance correlation matrix.

Details

• Iterates over all pairs of columns in X, computing the distance correlation for each pair using cor_distance(ce, v1, v2).

• Parallelizes computation using the estimator's ex field.

Related

• DistanceCovariance

• cor_distance(ce::DistanceCovariance, v1::VecNum, v2::VecNum)

source

PortfolioOptimisers.cov_distance Function

cov_distance(ce::DistanceCovariance, X::MatNum)

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

This function computes the distance covariance between each pair of columns in X, using the specified distance metric, optional weights, and parallel execution strategy. The resulting matrix is symmetric, with each entry representing the distance covariance between two assets.

Arguments

• ce: Distance covariance estimator.

• X: Data matrix (observations × assets).

Returns

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

Details

• Iterates over all pairs of columns in X, computing the distance covariance for each pair using cov_distance(ce, v1, v2).

• Parallelizes computation using the estimator's ex field.

Related

• DistanceCovariance

• cov_distance(ce::DistanceCovariance, v1::VecNum, v2::VecNum)

source