bundles / scipy 1.17.1 / scipy / stats / _stats_py / spearmanr

function

`scipy.stats._stats_py:spearmanr`

source: /scipy/stats/_stats_py.py :5168

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: statistic
pvalue: pvalue

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.

Notes

Array API Standard Support

spearmanr has experimental support for Python Array API Standard compatible backends in addition to NumPy. Please consider testing these features by setting an environment variable SCIPY_ARRAY_API=1 and providing CuPy, PyTorch, JAX, or Dask arrays as array arguments. The following combinations of backend and device (or other capability) are supported.

====================  ====================  ====================
Library               CPU                   GPU
====================  ====================  ====================
NumPy                 ✅                     n/a                 
CuPy                  n/a                   ⛔                   
PyTorch               ⛔                     ⛔                   
JAX                   ⛔                     ⛔                   
Dask                  ⛔                     n/a                 
====================  ====================  ====================

See dev-arrayapi for more information.

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

✗

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

✗

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

✓

res.statistic, res.pvalue

✗

res = stats.spearmanr(x2n, y2n)

✓

res.statistic
res.pvalue

✗

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

✓

res.statistic

✗

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

✓

res.statistic, res.pvalue

✗

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

✓

res.statistic, res.pvalue

✗

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

✓

res.statistic, res.pvalue

✗

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

✗

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

Aliases

scipy.stats.spearmanr