![]() |
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, keep_dims=None, 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
.
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 :
|
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 .
|
keep_dims
|
deprecated, use keepdims instead. |
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.]