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

# percentileofscore

scipy.stats.percentileofscore(a, score, kind='rank', nan_policy='propagate')

  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:
    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.

  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])