Distance Covariance

PortfolioOptimisers.DistanceCovariance — Type
struct DistanceCovariance{T1, T2, T3, T4, T5} <: AbstractCovarianceEstimator
    dist::T1
    args::T2
    kwargs::T3
    w::T4
    threads::T5
end

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. This enables modular and extensible workflows for robust covariance estimation using distance statistics.

Fields

  • dist::Distances.Metric: Distance metric used for pairwise computations.
  • args::Tuple: Additional positional arguments for the distance metric.
  • kwargs::NamedTuple: Additional keyword arguments for the distance metric.
  • w::Union{Nothing, <:AbstractWeights}: Optional weights for observations.
  • threads::FLoops.Transducers.Executor: Parallel execution strategy.

Constructor

DistanceCovariance(; dist::Distances.Metric = Distances.Euclidean(),
                  args::Tuple = (), kwargs::NamedTuple = (;),
                  w::Union{Nothing, <:AbstractWeights} = nothing,
                  threads::FLoops.Transducers.Executor = ThreadedEx())

Construct a DistanceCovariance estimator with the specified metric, arguments, weights, and threading strategy.

Related

source
PortfolioOptimisers.DistanceCovariance — Method
DistanceCovariance(; dist::Distances.Metric = Distances.Euclidean(),
                   args::Tuple = (), kwargs::NamedTuple = (;),
                   w::Union{Nothing, <:AbstractWeights} = nothing,
                   threads::FLoops.Transducers.Executor = ThreadedEx())

Construct a DistanceCovariance estimator for robust distance-based covariance or correlation estimation.

This constructor creates a DistanceCovariance object using the specified distance metric, additional positional and keyword arguments, optional weights, and parallel execution strategy. The estimator is highly modular, allowing users to select from different distance metrics, provide custom arguments, and configure parallelism.

Arguments

  • dist::Distances.Metric: Distance metric used for pairwise computations.
  • args::Tuple: Additional positional arguments for the distance metric.
  • kwargs::NamedTuple: Additional keyword arguments for the distance metric.
  • w::Union{Nothing, <:AbstractWeights}: Optional weights for observations.
  • threads::FLoops.Transducers.Executor: Parallel execution strategy.

ReturnsResult

  • DistanceCovariance: A configured distance covariance estimator.

Examples

julia> ce = DistanceCovariance()
DistanceCovariance
     dist | Distances.Euclidean: Distances.Euclidean(0.0)
     args | Tuple{}: ()
   kwargs | @NamedTuple{}: NamedTuple()
        w | nothing
  threads | Transducers.ThreadedEx{@NamedTuple{}}: Transducers.ThreadedEx()

Related

source
PortfolioOptimisers.cor_distance — Method
cor_distance(ce::DistanceCovariance, v1::AbstractVector, v2::AbstractVector)

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

This function calculates 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.

Arguments

  • ce::DistanceCovariance: Distance covariance estimator.
  • v1::AbstractVector: First data vector.
  • v2::AbstractVector: Second data vector.

ReturnsResult

  • ρ::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. Calculates the squared distance covariance and normalizes to obtain the distance correlation.

Validation

  • Asserts that v1 and v2 have the same length and at least two elements.

Related

source
PortfolioOptimisers.cov_distance — Method
cov_distance(ce::DistanceCovariance, v1::AbstractVector, v2::AbstractVector)

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

This function calculates 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.

Arguments

  • ce::DistanceCovariance: Distance covariance estimator.
  • v1::AbstractVector: First data vector.
  • v2::AbstractVector: Second data vector.

ReturnsResult

  • σ::Float64: 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. Calculates the squared distance covariance and returns its square root.

Validation

  • Asserts that v1 and v2 have the same length and at least two elements.

Related

source
PortfolioOptimisers.cor_distance — Method
cor_distance(ce::DistanceCovariance, X::AbstractMatrix)

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

This function calculates 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::DistanceCovariance: Distance covariance estimator.
  • X::AbstractMatrix: Data matrix (observations × assets).

ReturnsResult

  • rho::Matrix{Float64}: 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 threads field.

Related

source
PortfolioOptimisers.cov_distance — Method
cov_distance(ce::DistanceCovariance, X::AbstractMatrix)

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

This function calculates 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::DistanceCovariance: Distance covariance estimator.
  • X::AbstractMatrix: Data matrix (observations × assets).

ReturnsResult

  • sigma::Matrix{Float64}: 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 threads field.

Related

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

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

Arguments

  • ce::DistanceCovariance: Distance covariance estimator.
  • X::AbstractMatrix: Data matrix (observations × assets).
  • dims::Int: Dimension along which to compute correlations.
  • kwargs...: Additional keyword arguments (currently unused).

ReturnsResult

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

Validation

  • Asserts that dims is either 1 or 2.

Examples

julia> ce = DistanceCovariance()
DistanceCovariance
     dist | Distances.Euclidean: Distances.Euclidean(0.0)
     args | Tuple{}: ()
   kwargs | @NamedTuple{}: NamedTuple()
        w | nothing
  threads | 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
Statistics.cov — Method
Statistics.cov(ce::DistanceCovariance, X::AbstractMatrix; dims::Int = 1, kwargs...)

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

Arguments

  • ce::DistanceCovariance: Distance covariance estimator.
  • X::AbstractMatrix: Data matrix (observations × assets).
  • dims: Dimension along which to compute covariances.
  • kwargs...: Additional keyword arguments (currently unused).

ReturnsResult

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

Validation

  • Asserts that dims is either 1 or 2.

Examples

julia> ce = DistanceCovariance()
DistanceCovariance
     dist | Distances.Euclidean: Distances.Euclidean(0.0)
     args | Tuple{}: ()
   kwargs | @NamedTuple{}: NamedTuple()
        w | nothing
  threads | 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