pingouin.distance_corr

pingouin.
distance_corr
(x, y, tail='upper', n_boot=1000, seed=None)[source] Distance correlation between two arrays.
Statistical significance (pvalue) is evaluated with a permutation test.
 Parameters
 x, ynp.ndarray
1D or 2D input arrays, shape (n_samples, n_features). x and y must have the same number of samples and must not contain missing values.
 tailstr
Tail for pvalue
'upper' : onesided (upper tail) 'lower' : onesided (lower tail) 'twosided' : twosided
 n_bootint or None
Number of bootstrap to perform. If None, no bootstrapping is performed and the function only returns the distance correlation (no pvalue). Default is 1000 (thus giving a precision of 0.001).
 seedint or None
Random state seed.
 Returns
 dcorfloat
Sample distance correlation (range from 0 to 1).
 pvalfloat
Pvalue
Notes
From Wikipedia:
Distance correlation is a measure of dependence between two paired random vectors of arbitrary, not necessarily equal, dimension. The distance correlation coefficient is zero if and only if the random vectors are independent. Thus, distance correlation measures both linear and nonlinear association between two random variables or random vectors. This is in contrast to Pearson’s correlation, which can only detect linear association between two random variables.
The distance correlation of two random variables is obtained by dividing their distance covariance by the product of their distance standard deviations:
\[\text{dCor}(X, Y) = \frac{\text{dCov}(X, Y)} {\sqrt{\text{dVar}(X) \cdot \text{dVar}(Y)}}\]where \(\text{dCov}(X, Y)\) is the square root of the arithmetic average of the product of the doublecentered pairwise Euclidean distance matrices.
Note that by contrast to Pearson’s correlation, the distance correlation cannot be negative, i.e \(0 \leq \text{dCor} \leq 1\).
Results have been tested against the ‘energy’ R package. To be consistent with this latter, only the onesided pvalue is computed, i.e. the upper tail of the Tstatistic.
References
 1
 2
Székely, G. J., Rizzo, M. L., & Bakirov, N. K. (2007). Measuring and testing dependence by correlation of distances. The annals of statistics, 35(6), 27692794.
 3
 4
 5
Examples
With two 1D vectors
>>> from pingouin import distance_corr >>> a = [1, 2, 3, 4, 5] >>> b = [1, 2, 9, 4, 4] >>> distance_corr(a, b, seed=9) (0.7626762424168667, 0.312)
With two 2D arrays and no pvalue
>>> import numpy as np >>> np.random.seed(123) >>> from pingouin import distance_corr >>> a = np.random.random((10, 10)) >>> b = np.random.random((10, 10)) >>> distance_corr(a, b, n_boot=None) 0.8799633012275321