bundles / scipy latest / scipy / stats / _stats_py / spearmanr

function

`scipy.stats._stats_py:spearmanr`

source: build-install/usr/lib/python3.14/site-packages/scipy/stats/_stats_py.py:5226

Signature

def spearmanr(a, b = None, axis = 0, nan_policy = propagate, alternative = two-sided)

Summary

Calculate a Spearman correlation coefficient with associated p-value.

Extended Summary

The Spearman rank-order correlation coefficient is a nonparametric measure of the monotonicity of the relationship between two datasets. Like other correlation coefficients, this one varies between -1 and +1 with 0 implying no correlation. Correlations of -1 or +1 imply an exact monotonic relationship. Positive correlations imply that as x increases, so does y. Negative correlations imply that as x increases, y decreases.

The p-value roughly indicates the probability of an uncorrelated system producing datasets that have a Spearman correlation at least as extreme as the one computed from these datasets. Although calculation of the p-value does not make strong assumptions about the distributions underlying the samples, it is only accurate for very large samples (>500 observations). For smaller sample sizes, consider a permutation test (see Examples section below).

Parameters

a, b : 1D or 2D array_like, b is optional

One or two 1-D or 2-D arrays containing multiple variables and observations. When these are 1-D, each represents a vector of observations of a single variable. For the behavior in the 2-D case, see under axis, below. Both arrays need to have the same length in the axis dimension.

axis : int or None, optional

If axis=0 (default), then each column represents a variable, with observations in the rows. If axis=1, the relationship is transposed: each row represents a variable, while the columns contain observations. If axis=None, then both arrays will be raveled.

nan_policy : {'propagate', 'raise', 'omit'}, optional

Defines how to handle when input contains nan. The following options are available (default is 'propagate'):

'propagate': returns nan
'raise': throws an error
'omit': performs the calculations ignoring nan values

alternative : {'two-sided', 'less', 'greater'}, optional

Defines the alternative hypothesis. Default is 'two-sided'. The following options are available:

'two-sided': the correlation is nonzero
'less': the correlation is negative (less than zero)
'greater': the correlation is positive (greater than zero)

Returns

res : SignificanceResult

An object containing attributes:

statistic: Spearman correlation matrix or correlation coefficient (if only 2 variables are given as parameters). Correlation matrix is square with length equal to total number of variables (columns or rows) in a and b combined.
pvalue: The p-value for a hypothesis test whose null hypothesis is that two samples have no ordinal correlation. See alternative above for alternative hypotheses. pvalue has the same shape as statistic.

Raises

: ValueError: If axis is not 0, 1 or None, or if the number of dimensions of a is greater than 2, or if b is None and the number of dimensions of a is less than 2.

Warns

: `~scipy.stats.ConstantInputWarning`: Raised if an input is a constant array. The correlation coefficient is not defined in this case, so np.nan is returned.

Examples

import numpy as np
from scipy import stats
res = stats.spearmanr([1, 2, 3, 4, 5], [5, 6, 7, 8, 7])

✓

res.statistic
res.pvalue

✗

np.float64(0.08858700531354384)

rng = np.random.default_rng()
x2n = rng.standard_normal((100, 2))
y2n = rng.standard_normal((100, 2))
res = stats.spearmanr(x2n)

✓

res.statistic, res.pvalue

✗

(np.float64(-0.000504050405040504), np.float64(0.9960288396182977))

res = stats.spearmanr(x2n[:, 0], x2n[:, 1])

✓

res.statistic, res.pvalue

✗

(np.float64(-0.000504050405040504), np.float64(0.9960288396182977))

res = stats.spearmanr(x2n, y2n)

✓

res.statistic
res.pvalue

✗

array([[0.     , 0.99603, 0.51011, 0.2328 ],
       [0.99603, 0.     , 0.76119, 0.42432],
       [0.51011, 0.76119, 0.     , 0.32015],
       [0.2328 , 0.42432, 0.32015, 0.     ]])

res = stats.spearmanr(x2n.T, y2n.T, axis=1)

✓

res.statistic

✗

array([[ 1.     , -0.0005 ,  0.06663,  0.1204 ],
       [-0.0005 ,  1.     ,  0.03077, -0.08078],
       [ 0.06663,  0.03077,  1.     , -0.10043],
       [ 0.1204 , -0.08078, -0.10043,  1.     ]])

res = stats.spearmanr(x2n, y2n, axis=None)

✓

res.statistic, res.pvalue

✗

(np.float64(-0.009339233480837022), np.float64(0.895576195191417))

res = stats.spearmanr(x2n.ravel(), y2n.ravel())

✓

res.statistic, res.pvalue

✗

(np.float64(-0.009339233480837022), np.float64(0.895576195191417))

rng = np.random.default_rng()
xint = rng.integers(10, size=(100, 2))
res = stats.spearmanr(xint)

✓

res.statistic, res.pvalue

✗

(np.float64(-0.08692352519613988), np.float64(0.3898243103792412))

For small samples, consider performing a permutation test instead of relying on the asymptotic p-value. Note that to calculate the null distribution of the statistic (for all possibly pairings between observations in sample ``x`` and ``y``), only one of the two inputs needs to be permuted.

x = [1.76405235, 0.40015721, 0.97873798,
2.2408932, 1.86755799, -0.97727788]
y = [2.71414076, 0.2488, 0.87551913,
2.6514917, 2.01160156, 0.47699563]

✓

def statistic(x): # permute only `x`
    return stats.spearmanr(x, y).statistic
res_exact = stats.permutation_test((x,), statistic,
    permutation_type='pairings')
res_asymptotic = stats.spearmanr(x, y)

✓

res_exact.pvalue, res_asymptotic.pvalue # asymptotic pvalue is too low

✗

(np.float64(0.10277777777777777), np.float64(0.07239650145772594))

For a more detailed example, see :ref:`hypothesis_spearmanr`.

Aliases

scipy.stats.spearmanr