papyri
{ } Raw JSON

bundles / scipy latest / scipy / stats / _stats_py / percentileofscore

function

scipy.stats._stats_py:percentileofscore

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

Signature

def   percentileofscore ( a ,  score ,  kind = rank ,  nan_policy = propagate )

Summary

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

Extended Summary

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

a : array_like

A 1-D array to which score is compared.

score : float or array_like

A float score or array of scores for which to compute the percentile(s).

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

pcos : float or array-like

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

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 dev-arrayapi 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)
✗
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)
✗
Only 2/5 values are strictly less than 3: 
stats.percentileofscore([1, 2, 3, 3, 4], 3, kind='strict')
✗
But 4/5 values are less than or equal to 3: 
stats.percentileofscore([1, 2, 3, 3, 4], 3, kind='weak')
✗
The average between the weak and the strict scores is: 
stats.percentileofscore([1, 2, 3, 3, 4], 3, kind='mean')
✗
Score arrays (of any dimensionality) are supported: 
stats.percentileofscore([1, 2, 3, 3, 4], [2, 3])
✓
The inputs can be infinite: 
stats.percentileofscore([-np.inf, 0, 1, np.inf], [1, 2, np.inf])
✗
If `a` is empty, then the resulting percentiles are all `nan`: 
stats.percentileofscore([], [1, 2])
✓

See also

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

Aliases

  • scipy.stats.percentileofscore

Referenced by

This package