% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/impute-quantile_pred.R
\name{impute_quantiles}
\alias{impute_quantiles}
\title{Impute additional quantiles from a \code{quantile_pred}}
\usage{
impute_quantiles(
  x,
  probs,
  lower = -Inf,
  upper = Inf,
  middle = c("cubic", "linear")
)
}
\arguments{
\item{x}{an object of class \link{quantile_pred}}

\item{probs}{vector. probabilities at which to evaluate the inverse CDF}

\item{lower}{number. lower bound for the resulting values}

\item{upper}{number. upper bound for the resulting values}

\item{middle}{character. if \code{middle = 'cubic'} (the default), a cubic
spline is used for interpolation where possible; \code{middle='linear'}
interpolates linearly; see Details below.}
}
\value{
A matrix with \code{length(probs)} columns and \code{length(x)} rows. Each
row contains the inverse CDF (quantile function) given by \code{x},
extrapolated/interpolated to \code{probs}.
}
\description{
While a \link{quantile_pred} describes evaluations for the inverse
cummulative distribution function (CDF, sometimes called the "quantile
function") at particular quantile levels, this is not enough
to fully describe the distribution. For example,

\if{html}{\out{<div class="sourceCode r">}}\preformatted{p <- c(.1, .5, .9)
quantile_pred(matrix(qnorm(p), nrow = 1), p)
}\if{html}{\out{</div>}}

encapsulates the 10\%, 50\%, and 90\% quantile levels of the standard normal distribution.
But, what if we need, say, the 25\% and 75\% levels? This function imputes
them if possible.
}
\details{
If \code{probs} is simply a subset of \code{quantile_levels} that already exist in \code{x},
then these will be returned (up to numeric error). Small errors are possible
due to difficulties matching double vectors.

For \code{probs} that do not exist in \code{x}, these will be interpolated or
extrapolated as needed. The process has 3 steps.

First, by default (\code{middle = "cubic"}), missing \emph{internal} quantile levels are
interpolated using a cubic spline fit to the observed values + quantile
levels with
\link[stats:splinefun]{stats::splinefun}. Second, if cubic interpolation fails (or if
\code{middle = "linear"}), linear interpolation is used via \link[stats:approxfun]{stats::approx}.
Finally, missing \emph{external} quantile levels (those outside the range of
\code{quantile_levels}) are extrapolated. This is done using a linear fit on the
logistic scale to the two closest tail values.

This procedure results in sorted quantiles that interpolate/extrapolate
smoothly, while also enforcing heavy tails beyond the range.

Optionally, the resulting quantiles can be constrained to a compact interval
using \code{lower} and/or \code{upper}. This is done after extrapolation, so it may
result in multiple quantile levels having the same value (a CDF with a spike).
}
\examples{
p <- c(.1, .5, .9)
qp <- quantile_pred(matrix(c(qnorm(p), qexp(p)), nrow = 2, byrow = TRUE), p)
impute_quantiles(qp, p)
as.matrix(qp) # same as the imputation

p1 <- c(.05, .25, .75, .95)
impute_quantiles(qp, p1)
rbind(qnorm(p1), qexp(p1)) # exact values, for comparison
}
