Skip to main content
`Ctrl`+`K`
scipy.stats.

# kendalltau

scipy.stats.kendalltau(x, y, *, nan_policy='propagate', method='auto', variant='b', alternative='two-sided', axis=None, keepdims=False)

  Calculate Kendall’s tau, a correlation measure for ordinal data.

  Kendall’s tau is a measure of the correspondence between two rankings. Values close to 1 indicate strong agreement, and values close to -1 indicate strong disagreement. This implements two variants of Kendall’s tau: tau-b (the default) and tau-c (also known as Stuart’s tau-c). These differ only in how they are normalized to lie within the range -1 to 1; the hypothesis tests (their p-values) are identical. Kendall’s original tau-a is not implemented separately because both tau-b and tau-c reduce to tau-a in the absence of ties.

  Although a naive implementation has O(n^2) complexity, this implementation uses a Fenwick tree to do the computation in O(n log(n)) complexity.

  Parameters:
    x, y array_like

      Arrays of rankings, of the same shape. If arrays are not 1-D, they will be flattened to 1-D.

    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

    method{‘auto’, ‘asymptotic’, ‘exact’}, optional

      Defines which method is used to calculate the p-value [5]. The following options are available (default is ‘auto’):

      - ‘auto’: selects the appropriate method based on a trade-off between speed and accuracy

      - ‘asymptotic’: uses a normal approximation valid for large samples

      - ‘exact’: computes the exact p-value, but can only be used if no ties are present. As the sample size increases, the ‘exact’ computation time may grow and the result may lose some precision.

    variant{‘b’, ‘c’}, optional

      Defines which variant of Kendall’s tau is returned. Default is ‘b’.

    alternative{‘two-sided’, ‘less’, ‘greater’}, optional

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

      - ‘two-sided’: the rank correlation is nonzero

      - ‘less’: the rank correlation is negative (less than zero)

      - ‘greater’: the rank correlation is positive (greater than zero)

    axis int or None, default: None

      If an int, the axis of the input along which to compute the statistic. The statistic of each axis-slice (e.g. row) of the input will appear in a corresponding element of the output. If `None`, the input will be raveled before computing the statistic.

    keepdims bool, optional

      If this is set to `True`, the axes which are reduced are left in the result as dimensions with length one. With this option, the result will broadcast correctly against the input array.

  Returns:
    res SignificanceResult

      An object containing attributes:

      statisticfloat

        The tau statistic.

      pvaluefloat

        The p-value for a hypothesis test whose null hypothesis is an absence of association, tau = 0.

  Raises:
    ValueError

      If nan_policy is ‘omit’ and variant is not ‘b’ or if method is ‘exact’ and there are ties between x and y.

  See also

  `spearmanr`

    Calculates a Spearman rank-order correlation coefficient.

  `theilslopes`

    Computes the Theil-Sen estimator for a set of points (x, y).

  `weightedtau`

    Computes a weighted version of Kendall’s tau.

  Kendall’s tau test

    Extended example

  Notes

  The definition of Kendall’s tau that is used is [2]:

      tau_b = (P - Q) / sqrt((P + Q + T) * (P + Q + U))

      tau_c = 2 (P - Q) / (n**2 * (m - 1) / m)

  where P is the number of concordant pairs, Q the number of discordant pairs, T the number of tied pairs only in x, and U the number of tied pairs only in y. If a tie occurs for the same pair in both x and y, it is not added to either T or U. n is the total number of samples, and m is the number of unique values in either x or y, whichever is smaller.

  Array API Standard Support

  `kendalltau` 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 | ⚠️ no JIT | ⛔
  Dask | ⚠️ computes graph | n/a

  `kendalltau` also accepts MArrays backed by the backends indicated above; masked values will be treated as though they were not present. nan_policy=’propagate’ is incompatible with MArray input. See Support for the array API standard for more information.

  References

  [1]

  Maurice G. Kendall, “A New Measure of Rank Correlation”, Biometrika Vol. 30, No. 1/2, pp. 81-93, 1938.

  [2]

  Maurice G. Kendall, “The treatment of ties in ranking problems”, Biometrika Vol. 33, No. 3, pp. 239-251. 1945.

  [3]

  Gottfried E. Noether, “Elements of Nonparametric Statistics”, John Wiley & Sons, 1967.

  [4]

  Peter M. Fenwick, “A new data structure for cumulative frequency tables”, Software: Practice and Experience, Vol. 24, No. 3, pp. 327-336, 1994.

  [5]

  Maurice G. Kendall, “Rank Correlation Methods” (4th Edition), Charles Griffin & Co., 1970.

  Examples

      >>> from scipy import stats
      >>> x1 = [12, 2, 1, 12, 2]
      >>> x2 = [1, 4, 7, 1, 0]
      >>> res = stats.kendalltau(x1, x2)
      >>> res.statistic
      -0.47140452079103173
      >>> res.pvalue
      0.2827454599327748

  For a more detailed example, see Kendall’s tau test.