Distance Covariance

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

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

The statistic is the distance covariance. Its population value 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.

Section 2.2 of [37] defines the sample statistics. Definition 4 gives the doubly centred distance matrices. Equation 2.8 gives the squared distance covariance, the mean of their element-wise product with the divisor $n^{2}$, which is a V-statistic. Definition 5 and Equations 2.9 and 2.10 give the distance correlation, the square root of $\mathcal{V}_n^2(X, Y) / \sqrt{\mathcal{V}_n^2(X)\,\mathcal{V}_n^2(Y)}$. Without weights, the library computes these values. The observation weights w and the choice of metric are extensions of the library.

Fields

  • metric: The metric that Distances.pairwise applies to the observations of each series.
  • args: More positional arguments, which Distances.pairwise takes after the series.
  • kwargs: More keyword arguments for Distances.pairwise.
  • w: Optional observation weights vector observations × 1, or a concrete subtype of DynamicAbstractWeights. If nothing, the computation is unweighted.
  • ex: Parallel execution strategy.
  • cache: Optional partial-fit state. It is nothing until partial_fit! writes one. When the caller gives no data matrix, the batch verb of the estimator reads it. Each propagation channel does one thing with it. factory keeps it unchanged, because a factory call resolves the configuration, not the sample. port_opt_view copies the entries of the selected assets into a new state, so the viewed estimator holds the state of those assets alone. obs_weights_view removes it, because a state has no slice on the observation axis. Only a type with an observation-weights field has that channel. A type with no such field falls through to the identity method, so it keeps its state. A family whose state has no exact asset slice removes it on both axes and names the reason.

Constructors

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

Keywords correspond to the struct's fields.

Propagated parameters

factory passes its arguments on to these @wprop and @fprop fields:

View parameters

port_opt_view takes the view of this @vprop field at the selected indices:

Observation weight parameters

obs_weights_view indexes these fields 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

  • [37] 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). Section 2.2, Definitions 4 and 5, Equations 2.8 to 2.10.
source
Statistics.cov — Method
Statistics.cov(ce::DistanceCovariance, X::MatNum; dims::Int = 1, kwargs...)

Compute the distance covariance matrix of the columns of a data matrix with a DistanceCovariance estimator.

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

Algorithm

  1. Orient X with dims_oriented, which transposes it when dims is 2 and refuses any other value.
  2. Refuse a gapped sample with assert_finite_sample.
  3. Get the observation weights from ce.w and the oriented matrix with get_observation_weights. An unweighted estimator gets nothing.
  4. Return cov_distance(ce::DistanceCovariance, X::MatNum) of the oriented matrix and those weights.

Arguments

  • ce: The distance covariance estimator.
  • X: The data matrix, observations × assets.
  • dims: Dimension along which the computation runs.
  • kwargs...: More keyword arguments, which the method ignores.

Validation

  • dims is either 1 or 2.

Returns

  • sigma::Matrix{<:Number}: The 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 distance correlation matrix of the columns of a data matrix with a DistanceCovariance estimator.

Algorithm

  1. Orient X with dims_oriented, which transposes it when dims is 2 and refuses any other value.
  2. Refuse a gapped sample with assert_finite_sample.
  3. Get the observation weights from ce.w and the oriented matrix with get_observation_weights. An unweighted estimator gets nothing.
  4. Return cor_distance(ce::DistanceCovariance, X::MatNum) of the oriented matrix and those weights.

Arguments

  • ce: The distance covariance estimator.
  • X: The data matrix, observations × assets.
  • dims: Dimension along which the computation runs.
  • kwargs...: More keyword arguments, which the method ignores.

Validation

  • dims is either 1 or 2.

Returns

  • rho::Matrix{<:Number}: The symmetric matrix of pairwise distance correlations. The diagonal entry of a column that is not constant is exactly 1.0, and that of a constant column is NaN.

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

[37]
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).