Distance Covariance: private API

calc_pairwise_dists(ce::DistanceCovariance, v1::VecNum, v2::VecNum) -> (MatNum, MatNum)

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

Internal helper used in distance correlation and distance covariance computation. The observation weights never reach it. They weight the statistic that calc_centred_dists and calc_dcov2 build, and not the data that the metric measures.

Algorithm

1. Apply the estimator's metric to v1 and to v2 as the caller gave them, and pass ce.args and ce.kwargs to Distances.pairwise.
2. Return the two matrices in the order (D1, D2). Each is $T \times T$ for a pair of series of $T$ observations, and D1[t, s] is the distance between observations $t$ and $s$ of the same series.

Arguments

• ce: DistanceCovariance estimator with metric configuration.
• v1, v2: Data vectors.

Returns

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

Related

• DistanceCovariance
• calc_centred_dists
• calc_dcov2
• cor_distance

calc_centred_dists(a::MatNum, w::Option{<:StatsBase.AbstractWeights}) -> MatNum

Doubly centre a pairwise distance matrix, weighting every observation by w.

Internal helper used in distance correlation and distance covariance computation. The weights enter the three means, so a constant weight vector cancels from each of them and returns the unweighted matrix.

Algorithm

1. Without weights, take the ordinary row means, column means and grand mean of a.
2. With weights, take the same three means weighted by w. Each is normalised by the sum of the weights that it uses, so the scale of w cancels.
3. Subtract the row means and the column means from a, then add the grand mean back, giving A.

Arguments

• a: Pairwise distance matrix.
• w: Observation weights, or nothing for the unweighted statistic.

Returns

• A::MatNum: Doubly centred distance matrix.

Related

• DistanceCovariance
• calc_pairwise_dists
• calc_dcov2
• cor_distance

calc_dcov2(A::MatNum, B::MatNum, w::Option{<:StatsBase.AbstractWeights}) -> Number

Contract two doubly centred distance matrices into a squared distance covariance.

Internal helper used in distance correlation and distance covariance computation. The weights enter both indices of the contraction, so a constant weight vector cancels and returns the unweighted value.

Algorithm

1. Without weights, take the Frobenius inner product of A and B, and divide it by the number of entries of A.
2. With weights, take the element-wise product of A and B, contract it with w on both of its indices, and divide by the square of the sum of the weights.

Arguments

• A, B: Doubly centred distance matrices, as calc_centred_dists returns them.
• w: Observation weights, or nothing for the unweighted statistic.

Returns

• dcov2::Number: Squared distance covariance of the two matrices.

Related

• DistanceCovariance
• calc_pairwise_dists
• calc_centred_dists
• cov_distance

cor_distance(ce::DistanceCovariance, v1::VecNum, v2::VecNum,
             w::Option{<:StatsBase.AbstractWeights} = nothing)

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_{ts} = d(v_{1t}, v_{1s})$ and $b_{ts} = d(v_{2t}, v_{2s})$ be pairwise distance matrices. Define doubly-centered versions, whose three means carry the observation weights:

\[\begin{align} \bar{a}_{t\cdot} &= \frac{\sum\limits_{s=1}^{T} w_{s} a_{ts}}{\sum\limits_{s=1}^{T} w_{s}}\,, \\ \bar{a}_{\cdot s} &= \frac{\sum\limits_{t=1}^{T} w_{t} a_{ts}}{\sum\limits_{t=1}^{T} w_{t}}\,, \\ \bar{a}_{\cdot\cdot} &= \frac{\sum\limits_{t=1}^{T} \sum\limits_{s=1}^{T} w_{t} w_{s} a_{ts}}{\left(\sum\limits_{t=1}^{T} w_{t}\right)^{2}}\,, \\ A_{ts} &= a_{ts} - \bar{a}_{t\cdot} - \bar{a}_{\cdot s} + \bar{a}_{\cdot\cdot}\,, \\ B_{ts} &= b_{ts} - \bar{b}_{t\cdot} - \bar{b}_{\cdot s} + \bar{b}_{\cdot\cdot}\,. \end{align}\]

Where:

• $a_{ts}$, $b_{ts}$: Pairwise distances between observations $t$ and $s$.
• $\bar{a}_{t\cdot}$: $t$-th weighted row mean of $\mathbf{a}$.
• $\bar{a}_{\cdot s}$: $s$-th weighted column mean of $\mathbf{a}$.
• $\bar{a}_{\cdot\cdot}$: Weighted grand mean of $\mathbf{a}$.
• $A_{ts}$, $B_{ts}$: Doubly centred pairwise distances.
• $w_{t}$: Observation weight of observation $t$.
• $T$: Number of observations.

The three means of $\mathbf{b}$ take the form that the three means of $\mathbf{a}$ take.

The squared distance covariances and distance correlation are:

\[\begin{align} \widehat{\mathrm{dCov}}^2(X,X) &= \frac{\sum\limits_{t=1}^{T} \sum\limits_{s=1}^{T} w_{t} w_{s} A_{ts} A_{ts}}{\left(\sum\limits_{t=1}^{T} w_{t}\right)^{2}}\,, \\ \widehat{\mathrm{dCov}}^2(X,Y) &= \frac{\sum\limits_{t=1}^{T} \sum\limits_{s=1}^{T} w_{t} w_{s} A_{ts} B_{ts}}{\left(\sum\limits_{t=1}^{T} w_{t}\right)^{2}}\,, \\ \widehat{\mathrm{dCov}}^2(Y,Y) &= \frac{\sum\limits_{t=1}^{T} \sum\limits_{s=1}^{T} w_{t} w_{s} B_{ts} B_{ts}}{\left(\sum\limits_{t=1}^{T} w_{t}\right)^{2}}\,. \end{align}\]

Where:

• $\widehat{\mathrm{dCov}}^2(X,Y)$: Squared distance covariance of $X$ and $Y$.

\[\begin{align} \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{align}\]

Where:

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

Each quotient above divides two forms of one degree in the weights, so a constant weight cancels from all of them. The value $w_{t} = 1$ reduces the three squared distance covariances to $\mathbf{A}:\mathbf{B} / T^{2}$, the Frobenius inner product $\sum_{t,\,s} A_{ts} B_{ts}$ over $T^{2}$, which is the unweighted statistic.

Algorithm

1. Build the two pairwise distance matrices $\mathbf{a}$ and $\mathbf{b}$ with calc_pairwise_dists, which carries the estimator's metric, its args and its kwargs.
2. Doubly centre each matrix with calc_centred_dists, which weights the three means it subtracts and adds, giving $\mathbf{A}$ and $\mathbf{B}$.
3. Contract the three pairs $(\mathbf{A}, \mathbf{A})$, $(\mathbf{A}, \mathbf{B})$ and $(\mathbf{B}, \mathbf{B})$ with calc_dcov2, giving the three squared distance covariances.
4. Return $\sqrt{\widehat{\mathrm{dCov}}^2(X,Y)}$ divided by the square root of the product of the two remaining square roots.

Arguments

• ce: Distance covariance estimator.
• v1: First data vector.
• v2: Second data vector.
• w: Observation weights, or nothing for the unweighted statistic.

Validation

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

Returns

• rho::Float64: The computed distance correlation between v1 and v2. A series against itself gives exactly 1.0.

Related

• DistanceCovariance
• calc_pairwise_dists
• calc_centred_dists
• calc_dcov2
• cor_distance(ce::DistanceCovariance, X::MatNum)

cov_distance(ce::DistanceCovariance, v1::VecNum, v2::VecNum,
             w::Option{<:StatsBase.AbstractWeights} = nothing)

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{align} \widehat{\mathrm{dCov}}(X, Y) &= \sqrt{\frac{\sum\limits_{t=1}^{T} \sum\limits_{s=1}^{T} w_{t} w_{s} A_{ts} B_{ts}}{\left(\sum\limits_{t=1}^{T} w_{t}\right)^{2}}}\,. \end{align}\]

Where:

• $\widehat{\mathrm{dCov}}(X, Y)$: Distance covariance between $X$ and $Y$.
• $A_{ts}$, $B_{ts}$: Doubly centred pairwise distances.
• $w_{t}$: Observation weight of observation $t$.
• $T$: Number of observations.

The value $w_{t} = 1$ reduces the quotient to $\mathbf{A}:\mathbf{B} / T^{2}$, the Frobenius inner product $\sum_{t,\,s} A_{ts} B_{ts}$ over $T^{2}$, which is the unweighted statistic.

The square root takes no absolute value. It needs none: the doubly-centred V-statistic is non-negative for a metric of strong negative type, which the Euclidean default is.

Algorithm

1. Build the two pairwise distance matrices $\mathbf{a}$ and $\mathbf{b}$ with calc_pairwise_dists, which carries the estimator's metric, its args and its kwargs.
2. Doubly centre each matrix with calc_centred_dists, which weights the three means it subtracts and adds, giving $\mathbf{A}$ and $\mathbf{B}$.
3. Contract the pair $(\mathbf{A}, \mathbf{B})$ with calc_dcov2, giving the squared distance covariance.
4. Return the square root of that value. Steps 1 and 2 are those of cor_distance; this method takes one of the three contractions and takes no ratio.

Arguments

• ce: Distance covariance estimator.
• v1: First data vector.
• v2: Second data vector.
• w: Observation weights, or nothing for the unweighted statistic.

Validation

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

Returns

• rho::Number: The computed distance covariance between v1 and v2. A series against itself gives the distance standard deviation $\widehat{\mathrm{dVar}}^{1/2}(X)$, which is not the sample standard deviation.

Related

• DistanceCovariance
• calc_pairwise_dists
• calc_centred_dists
• calc_dcov2
• cov_distance(ce::DistanceCovariance, X::MatNum)

cor_distance(ce::DistanceCovariance, X::MatNum,
             w::Option{<:StatsBase.AbstractWeights} = nothing)

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.

Algorithm

1. Allocate an $N \times N$ matrix, where $N$ is the number of columns of X. The result is indexed by asset and never by observation, so a non-square X cannot hide a transposed index.
2. For each column j, and for each column i at or below j, call cor_distance(ce::DistanceCovariance, v1::VecNum, v2::VecNum) on the two columns and write the value into both rho[i, j] and rho[j, i]. The estimator's ex field runs the outer loop.
3. Return the symmetric matrix. Its diagonal is exactly 1.0, because the pair (j, j) is one of the pairs step 2 computes.

Arguments

• ce: Distance covariance estimator.
• X: Data matrix (observations × assets).
• w: Observation weights, or nothing for the unweighted statistic.

Returns

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

Related

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

cov_distance(ce::DistanceCovariance, X::MatNum,
             w::Option{<:StatsBase.AbstractWeights} = nothing)

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.

Algorithm

1. Allocate an $N \times N$ matrix, where $N$ is the number of columns of X. The result is indexed by asset and never by observation, so a non-square X cannot hide a transposed index.
2. For each column j, and for each column i at or below j, call cov_distance(ce::DistanceCovariance, v1::VecNum, v2::VecNum) on the two columns and write the value into both sigma[i, j] and sigma[j, i]. The estimator's ex field runs the outer loop.
3. Return the symmetric matrix. Its diagonal is the distance standard deviation of each asset, because the pair (j, j) is one of the pairs step 2 computes.

Arguments

• ce: Distance covariance estimator.
• X: Data matrix (observations × assets).
• w: Observation weights, or nothing for the unweighted statistic.

Returns

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

Related

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