scipy.stats.

percentileofscore#

scipy.stats.percentileofscore(a, score, kind='rank', nan_policy='propagate')[source]#

Compute the percentile rank of a score relative to a list of scores.

A percentileofscore of, for example, 80% means that 80% of the scores in a are below the given score. In the case of gaps or ties, the exact definition depends on the optional keyword, kind.

Parameters:
aarray_like

A 1-D array to which score is compared.

scorearray_like

Scores to compute percentiles for.

kind{‘rank’, ‘weak’, ‘strict’, ‘mean’}, optional

Specifies the interpretation of the resulting score. The following options are available (default is ‘rank’):

  • ‘rank’: Average percentage ranking of score. In case of multiple matches, average the percentage rankings of all matching scores.

  • ‘weak’: This kind corresponds to the definition of a cumulative distribution function. A percentileofscore of 80% means that 80% of values are less than or equal to the provided score.

  • ‘strict’: Similar to “weak”, except that only values that are strictly less than the given score are counted.

  • ‘mean’: The average of the “weak” and “strict” scores, often used in testing. See https://en.wikipedia.org/wiki/Percentile_rank

nan_policy{‘propagate’, ‘raise’, ‘omit’}, optional

Specifies how to treat nan values in a. The following options are available (default is ‘propagate’):

  • ‘propagate’: returns nan (for each value in score).

  • ‘raise’: throws an error

  • ‘omit’: performs the calculations ignoring nan values

Returns:
pcosfloat

Percentile-position of score (0-100) relative to a.

See also

numpy.percentile
scipy.stats.scoreatpercentile, scipy.stats.rankdata

Notes

Array API Standard Support

percentileofscore 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 Support for the array API standard for more information.

Examples

Three-quarters of the given values lie below a given score:

>>> import numpy as np
>>> from scipy import stats
>>> stats.percentileofscore([1, 2, 3, 4], 3)
75.0

With multiple matches, note how the scores of the two matches, 0.6 and 0.8 respectively, are averaged:

>>> stats.percentileofscore([1, 2, 3, 3, 4], 3)
70.0

Only 2/5 values are strictly less than 3:

>>> stats.percentileofscore([1, 2, 3, 3, 4], 3, kind='strict')
40.0

But 4/5 values are less than or equal to 3:

>>> stats.percentileofscore([1, 2, 3, 3, 4], 3, kind='weak')
80.0

The average between the weak and the strict scores is:

>>> stats.percentileofscore([1, 2, 3, 3, 4], 3, kind='mean')
60.0

Score arrays (of any dimensionality) are supported:

>>> stats.percentileofscore([1, 2, 3, 3, 4], [2, 3])
array([40., 70.])

The inputs can be infinite:

>>> stats.percentileofscore([-np.inf, 0, 1, np.inf], [1, 2, np.inf])
array([75., 75., 100.])

If a is empty, then the resulting percentiles are all nan:

>>> stats.percentileofscore([], [1, 2])
array([nan, nan])
On this page