Quantiles of Distributions

Produces quantiles corresponding to the given probabilities with configurable distribution parameters.

Usage

# S3 method for Distribution
quantile(x, probs = seq(0, 1, 0.25), with_params = list(), ..., .start = 0)

Arguments

x

A Distribution.

probs

Quantiles to compute.

with_params

Optional list of distribution parameters. Note that if x$has_capability("quantile") is false, with_params is assumed to contain only one set of parameters.

...

ignored

.start

Starting value if quantiles are computed numerically. Must be within the support of x.

Value

The quantiles of x corresponding to probs with parameters with_params.

Details

If x$has_capability("quantile") is true, this returns the same as x$quantile(probs, with_params = with_params). In this case, with_params may contain separate sets of parameters for each quantile to be determined.

Otherwise, a numerical estimation of the quantiles is done using the density and probability function. This method assumes with_params to cantain only one set of parameters. The strategy uses two steps:

1. Find the smallest and largest quantiles in probs using a newton method starting from .start.

2. Find the remaining quantiles with bisection using stats::uniroot().

Examples

# With quantiles available
dist <- dist_normal(sd = 1)
qqs <- quantile(dist, probs = rep(0.5, 3), with_params = list(mean = 1:3))
stopifnot(all.equal(qqs, 1:3))

# Without quantiles available
dist <- dist_erlangmix(shapes = list(1, 2, 3), scale = 1.0)
my_probs <- c(0, 0.01, 0.25, 0.5, 0.75, 1)
qqs <- quantile(
  dist, probs = my_probs,
  with_params = list(probs = list(0.5, 0.3, 0.2)), .start = 2
)

all.equal(dist$probability(qqs, with_params = list(probs = list(0.5, 0.3, 0.2))), my_probs)
#> [1] "Mean relative difference: 2.890015e-06"
# Careful: Numerical estimation of extreme quantiles can result in out-of-bounds values.
# The correct 0-quantile would be 0 in this case, but it was estimated < 0.
qqs[1L]
#> [1] -1.138089