Distance Covariance
PortfolioOptimisers.DistanceCovariance — Type
struct DistanceCovariance{__T_metric, __T_args, __T_kwargs, __T_w, __T_ex, __T_cache} <: AbstractCovarianceEstimatorMeasures 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 thatDistances.pairwiseapplies to the observations of each series.
args: More positional arguments, whichDistances.pairwisetakes after the series.
kwargs: More keyword arguments forDistances.pairwise.
w: Optional observation weights vectorobservations × 1, or a concrete subtype ofDynamicAbstractWeights. Ifnothing, the computation is unweighted.
ex: Parallel execution strategy.
cache: Optional partial-fit state. It isnothinguntilpartial_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.factorykeeps it unchanged, because a factory call resolves the configuration, not the sample.port_opt_viewcopies the entries of the selected assets into a new state, so the viewed estimator holds the state of those assets alone.obs_weights_viewremoves 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) -> DistanceCovarianceKeywords correspond to the struct's fields.
Propagated parameters
factory passes its arguments on to these @wprop and @fprop fields:
w: Replaced with the incomingObsWeights.cache: Carried unchanged throughfactory.
View parameters
port_opt_view takes the view of this @vprop field at the selected indices:
cache: Sliced to the selected assets throughport_opt_view.
Observation weight parameters
obs_weights_view indexes these fields to the selected observations:
w: Indexed to the selected observations throughobs_weights_view.
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
AbstractCovarianceEstimatorDistances.MetricStatsBase.AbstractWeightsFLoops.Transducers.Executorfactoryobs_weights_viewcor_distancecov_distance
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.
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
- Orient
Xwithdims_oriented, which transposes it whendimsis2and refuses any other value. - Refuse a gapped sample with
assert_finite_sample. - Get the observation weights from
ce.wand the oriented matrix withget_observation_weights. An unweighted estimator getsnothing. - 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
dimsis either1or2.
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.40546Related
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
- Orient
Xwithdims_oriented, which transposes it whendimsis2and refuses any other value. - Refuse a gapped sample with
assert_finite_sample. - Get the observation weights from
ce.wand the oriented matrix withget_observation_weights. An unweighted estimator getsnothing. - 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
dimsis either1or2.
Returns
rho::Matrix{<:Number}: The symmetric matrix of pairwise distance correlations. The diagonal entry of a column that is not constant is exactly1.0, and that of a constant column isNaN.
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.0Related
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).