.. _spearman_test:

Spearman correlation test
-------------------------

The Spearman Test checks if there exists a monotonic relationship between two random
variables :math:`X` and :math:`Y`.

The Spearman test is based on the Spearman correlation coefficient defined in
:ref:`Spearman coefficient <spearman_coefficient>`. It tests if the Spearman correlation
coefficient is significantly different from zero.

The Spearman compares the null hypothesis :math:`\cH_0 = \left\{ \rho_S(X,Y) = 0 \right\}` against the
alternative
hypothesis :math:`\cH_1 = \left\{ \rho_S(X,Y) \neq 0 \right\}`.

The Spearman correlation coefficient :math:`\rho_S(X,Y)` is evaluated on a sample generated by the
bivariate random vector :math:`(X,Y)` of size :math:`\sampleSize` and denoted by
:math:`\hat{\rho}_S(X,Y)` as detailed in :eq:`SpearmanEstim`.

The statistics :math:`T(X,Y)` used in the test is defined by:

.. math::
  T(X,Y) = \hat{\rho}_S(X,Y) \sqrt{\dfrac{\sampleSize-2}{1-(\hat{\rho}_S(X,Y))^2}}

Under the null hypothesis :math:`\cH_0`, the statistics :math:`T` follows a Student
distribution with :math:`\sampleSize-2` degrees of freedom in the case of a Gaussian vector. In the other
cases, the Student distribution :math:`T(\sampleSize-2)` is equivalent to the asymptotic distribution of
:math:`T`. The library uses the Student distribution :math:`T(\sampleSize-2)` in all the cases.

The p-value :math:`p_v` is the probability :math:`p_v = \Prob{|T| \geq |t(X,Y)|}`
where :math:`t(X,Y)` is the realization of
:math:`T(X,Y)` computed on the sample. The null hypothesis
:math:`\cH_0` is rejected if :math:`p_v < p_v^\ell` where  :math:`p_v^\ell` is specified
(usually 0.1 or 0.05). The p-value limit :math:`p_v^\ell` is the probability to wrongly reject the null hypothesis
:math:`\cH_0`, which
means to commit a Type I error.

When the null hypothesis :math:`\cH_0` is rejected, it means that there is a significant monotonic
relationship between both variables :math:`X` and :math:`Y`.

.. topic:: API:

    - See :py:func:`~openturns.HypothesisTest.Spearman`
    - See :py:func:`~openturns.HypothesisTest.PartialSpearman`
    - See :py:func:`~openturns.HypothesisTest.FullSpearman`


.. topic:: Examples:

    - See :doc:`/auto_data_analysis/statistical_tests/plot_test_independence`

.. topic:: References:

    - [saporta1990]_
    - [dixon1983]_
    - [nisthandbook]_
    - [dagostino1986]_
    - [bhattacharyya1997]_
    - [sprent2001]_
    - [burnham2002]_