tfp.substrates.jax.stats.percentile

Compute the q-th percentile(s) of x.

tfp.substrates.jax.stats.percentile(
    x, q, axis=None, interpolation=None, keepdims=False, validate_args=False,
    preserve_gradients=True, name=None
)

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.

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'

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.

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