papyri
This is a pre-release version (latest).Go to latest (1.18.0)
{ } Raw JSON

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

function

scipy.stats._stats_py:percentileofscore

source: build-install/usr/lib/python3.14/site-packages/scipy/stats/_stats_py.py:2085

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.

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)
✗
np.float64(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)
✗
np.float64(70.0)
Only 2/5 values are strictly less than 3: 
stats.percentileofscore([1, 2, 3, 3, 4], 3, kind='strict')
✗
np.float64(40.0)
But 4/5 values are less than or equal to 3: 
stats.percentileofscore([1, 2, 3, 3, 4], 3, kind='weak')
✗
np.float64(80.0)
The average between the weak and the strict scores is: 
stats.percentileofscore([1, 2, 3, 3, 4], 3, kind='mean')
✗
np.float64(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])

See also

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

Aliases

  • scipy.stats.percentileofscore

Referenced by

This package