|---|
| [ View source on GitHub](https://github.com/tensorflow/probability/blob/v0.25.0/tensorflow_probability/python/stats/quantiles.py#L428-L642) |
Compute the `q`-th percentile(s) of `x`.
tfp.stats.percentile(
x,
q,
axis=None,
interpolation=None,
keepdims=False,
validate_args=False,
preserve_gradients=True,
name=None
)
### Used in the notebooks
| Used in the tutorials |
|---|
| - [Modeling COVID-19 spread in Europe and the effect of interventions](https://www.tensorflow.org/probability/examples/Estimating_COVID_19_in_11_European_countries) |
Given a vector `x`, the `q`-th percentile of `x` is the value `q / 100` of the
way from the minimum to the maximum in a sorted copy of `x`.
The values and distances of the two nearest neighbors as well as the
`interpolation` parameter will determine the percentile if the normalized
ranking does not match the location of `q` exactly.
This function is the same as the median if `q = 50`, the same as the minimum
if `q = 0` and the same as the maximum if `q = 100`.
Multiple percentiles can be computed at once by using `1-D` vector `q`.
Dimension zero of the returned `Tensor` will index the different percentiles.
Compare to [`numpy.percentile`](https://www.tensorflow.org/api_docs/python/tf/keras/ops/percentile).
| ## Args ||
|---|---|
| `x` | Numeric `N-D` `Tensor` with `N > 0`. If `axis` is not `None`, `x` must have statically known number of dimensions. |
| `q` | Scalar or vector `Tensor` with values in `[0, 100]`. The percentile(s). |
| `axis` | Optional `0-D` or `1-D` integer `Tensor` with constant values. The axis that index independent samples over which to return the desired percentile. If `None` (the default), treat every dimension as a sample dimension, returning a scalar. |
| `interpolation` | {'nearest', 'linear', 'lower', 'higher', 'midpoint'}. Default value: 'nearest'. This specifies the interpolation method to use when the desired quantile lies between two data points `i < j`:
- linear: i + (j - i) \* fraction, where fraction is the fractional part of the index surrounded by i and j. - lower: `i`. - higher: `j`. - nearest: `i` or `j`, whichever is nearest. - midpoint: (i + j) / 2. `linear` and `midpoint` interpolation do not work with integer dtypes. |
| `keepdims` | Python `bool`. If `True`, the last dimension is kept with size 1 If `False`, the last dimension is removed from the output shape. |
| `validate_args` | Whether to add runtime checks of argument validity. If False, and arguments are incorrect, correct behavior is not guaranteed. |
| `preserve_gradients` | Python `bool`. If `True`, ensure that gradient w.r.t the percentile `q` is preserved in the case of linear interpolation. If `False`, the gradient will be (incorrectly) zero when `q` corresponds to a point in `x`. |
| `name` | A Python string name to give this `Op`. Default is 'percentile' |
| ## Returns ||
|---|---|
| A `(rank(q) + N - len(axis))` dimensional `Tensor` of same dtype as `x`, or, if `axis` is `None`, a `rank(q)` `Tensor`. The first `rank(q)` dimensions index quantiles for different values of `q`. ||
| ## Raises ||
|---|---|
| `ValueError` | If argument 'interpolation' is not an allowed type. |
| `ValueError` | If interpolation type not compatible with `dtype`. |
#### Examples
# Get 30th percentile with default ('nearest') interpolation.
x = [1., 2., 3., 4.]
tfp.stats.percentile(x, q=30.)
==> 2.0
# Get 30th percentile with 'linear' interpolation.
x = [1., 2., 3., 4.]
tfp.stats.percentile(x, q=30., interpolation='linear')
==> 1.9
# Get 30th and 70th percentiles with 'lower' interpolation
x = [1., 2., 3., 4.]
tfp.stats.percentile(x, q=[30., 70.], interpolation='lower')
==> [1., 3.]
# Get 100th percentile (maximum). By default, this is computed over every dim
x = [[1., 2.]
[3., 4.]]
tfp.stats.percentile(x, q=100.)
==> 4.
# Treat the leading dim as indexing samples, and find the 100th quantile (max)
# over all such samples.
x = [[1., 2.]
[3., 4.]]
tfp.stats.percentile(x, q=100., axis=[0])
==> [3., 4.]