def test_perm_pval(self): """Test function _perm_pval. """ np.random.seed(123) bootstat = np.random.normal(size=1000) x = -2 up = _perm_pval(bootstat, x, alternative='greater') low = _perm_pval(bootstat, x, alternative='less') two = _perm_pval(bootstat, x, alternative='two-sided') assert up > low assert up + low == 1 assert low < two < up x = 2.5 up = _perm_pval(bootstat, x, alternative='greater') low = _perm_pval(bootstat, x, alternative='less') two = _perm_pval(bootstat, x, alternative='two-sided') assert low > up assert up + low == 1 assert up < two < low
def distance_corr(x, y, tail='greater', n_boot=1000, seed=None): """Distance correlation between two arrays. Statistical significance (p-value) is evaluated with a permutation test. Parameters ---------- x, y : np.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. tail : str Tail for p-value. Can be either `'two-sided'` (default), or `'greater'` or `'less'` for directional tests. To be consistent with the original R implementation, the default is to calculate the one-sided `'greater'` p-value. n_boot : int or None Number of bootstrap to perform. If None, no bootstrapping is performed and the function only returns the distance correlation (no p-value). Default is 1000 (thus giving a precision of 0.001). seed : int or None Random state seed. Returns ------- dcor : float Sample distance correlation (range from 0 to 1). pval : float P-value 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: .. math:: \\text{dCor}(X, Y) = \\frac{\\text{dCov}(X, Y)} {\\sqrt{\\text{dVar}(X) \\cdot \\text{dVar}(Y)}} where :math:`\\text{dCov}(X, Y)` is the square root of the arithmetic average of the product of the double-centered pairwise Euclidean distance matrices. Note that by contrast to Pearson's correlation, the distance correlation cannot be negative, i.e :math:`0 \\leq \\text{dCor} \\leq 1`. Results have been tested against the 'energy' R package. References ---------- .. [1] https://en.wikipedia.org/wiki/Distance_correlation .. [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), 2769-2794. .. [3] https://gist.github.com/satra/aa3d19a12b74e9ab7941 .. [4] https://gist.github.com/wladston/c931b1495184fbb99bec .. [5] https://cran.r-project.org/web/packages/energy/energy.pdf Examples -------- 1. 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) 2. With two 2D arrays and no p-value >>> 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 """ assert tail in ['greater', 'less', 'two-sided'], 'Wrong tail argument.' x = np.asarray(x) y = np.asarray(y) # Check for NaN values if any([np.isnan(np.min(x)), np.isnan(np.min(y))]): raise ValueError('Input arrays must not contain NaN values.') if x.ndim == 1: x = x[:, None] if y.ndim == 1: y = y[:, None] assert x.shape[0] == y.shape[0], 'x and y must have same number of samples' # Extract number of samples n = x.shape[0] n2 = n**2 # Process first array to avoid redundancy when performing bootstrap a = squareform(pdist(x, metric='euclidean')) A = a - a.mean(axis=0)[None, :] - a.mean(axis=1)[:, None] + a.mean() dcov2_xx = np.vdot(A, A) / n2 # Process second array and compute final distance correlation dcor = _dcorr(y, n2, A, dcov2_xx) # Compute one-sided p-value using a bootstrap procedure if n_boot is not None and n_boot > 1: # Define random seed and permutation rng = np.random.RandomState(seed) bootsam = rng.random_sample((n_boot, n)).argsort(axis=1) bootstat = np.empty(n_boot) for i in range(n_boot): bootstat[i] = _dcorr(y[bootsam[i, :]], n2, A, dcov2_xx) pval = _perm_pval(bootstat, dcor, tail=tail) return dcor, pval else: return dcor