% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_predicted_ci.R
\name{get_predicted_ci}
\alias{get_predicted_ci}
\alias{get_predicted_ci.default}
\title{Confidence intervals around predicted values}
\usage{
get_predicted_ci(x, ...)

\method{get_predicted_ci}{default}(
  x,
  predictions = NULL,
  data = NULL,
  se = NULL,
  ci = 0.95,
  ci_type = "confidence",
  ci_method = NULL,
  dispersion_method = "sd",
  vcov = NULL,
  vcov_args = NULL,
  verbose = TRUE,
  ...
)
}
\arguments{
\item{x}{A statistical model (can also be a data.frame, in which case the
second argument has to be a model).}

\item{...}{Other argument to be passed, for instance to \code{get_predicted_ci()}.}

\item{predictions}{A vector of predicted values (as obtained by
\code{stats::fitted()}, \code{stats::predict()} or \code{\link[=get_predicted]{get_predicted()}}).}

\item{data}{An optional data frame in which to look for variables with which
to predict. If omitted, the data used to fit the model is used. Visualization
matrices can be generated using \code{\link[=get_datagrid]{get_datagrid()}}.}

\item{se}{Numeric vector of standard error of predicted values. If \code{NULL},
standard errors are calculated based on the variance-covariance matrix.}

\item{ci}{The interval level. Default is \code{NULL}, to be fast even for larger
models. Set the interval level to an explicit value, e.g. \code{0.95}, for \verb{95\%}
CI).}

\item{ci_type}{Can be \code{"prediction"} or \code{"confidence"}. Prediction
intervals show the range that likely contains the value of a new
observation (in what range it would fall), whereas confidence intervals
reflect the uncertainty around the estimated parameters (and gives the
range of the link; for instance of the regression line in a linear
regressions). Prediction intervals account for both the uncertainty in the
model's parameters, plus the random variation of the individual values.
Thus, prediction intervals are always wider than confidence intervals.
Moreover, prediction intervals will not necessarily become narrower as the
sample size increases (as they do not reflect only the quality of the fit).
This applies mostly for "simple" linear models (like \code{lm}), as for
other models (e.g., \code{glm}), prediction intervals are somewhat useless
(for instance, for a binomial model for which the dependent variable is a
vector of 1s and 0s, the prediction interval is... \verb{[0, 1]}).}

\item{ci_method}{The method for computing p values and confidence intervals.
Possible values depend on model type.
\itemize{
\item \code{NULL} uses the default method, which varies based on the model type.
\item Most frequentist models: \code{"wald"} (default), \code{"residual"} or \code{"normal"}.
\item Bayesian models:  \code{"quantile"}  (default), \code{"hdi"}, \code{"eti"}, and \code{"spi"}.
\item Mixed effects \strong{lme4} models: \code{"wald"} (default), \code{"residual"}, \code{"normal"},
\code{"satterthwaite"}, and \code{"kenward-roger"}.
}

See \code{\link[=get_df]{get_df()}} for details.}

\item{dispersion_method}{Bootstrap dispersion and Bayesian posterior summary:
\code{"sd"} or \code{"mad"}.}

\item{vcov}{Variance-covariance matrix used to compute uncertainty estimates
(e.g., for robust standard errors). This argument accepts a covariance
matrix, a function which returns a covariance matrix, or a string which
identifies the function to be used to compute the covariance matrix.
\itemize{
\item A covariance matrix
\item A function which returns a covariance matrix (e.g., \code{stats::vcov()})
\item A string which indicates the kind of uncertainty estimates to return.
\itemize{
\item Heteroskedasticity-consistent: \code{"HC"}, \code{"HC0"}, \code{"HC1"}, \code{"HC2"},
\code{"HC3"}, \code{"HC4"}, \code{"HC4m"}, \code{"HC5"}. See \code{?sandwich::vcovHC}
\item Cluster-robust: \code{"CR"}, \code{"CR0"}, \code{"CR1"}, \code{"CR1p"}, \code{"CR1S"}, \code{"CR2"},
\code{"CR3"}. See \code{?clubSandwich::vcovCR}
\item Bootstrap: \code{"BS"}, \code{"xy"}, \code{"residual"}, \code{"wild"}, \code{"mammen"},
\code{"fractional"}, \code{"jackknife"}, \code{"norm"}, \code{"webb"}. See
\code{?sandwich::vcovBS}
\item Other \code{sandwich} package functions: \code{"HAC"}, \code{"PC"}, \code{"CL"}, \code{"OPG"},
\code{"PL"}.
\item Kenward-Roger approximation: \code{kenward-roger}. See \code{?pbkrtest::vcovAdj}.
}
}}

\item{vcov_args}{List of arguments to be passed to the function identified by
the \code{vcov} argument. This function is typically supplied by the
\strong{sandwich} or \strong{clubSandwich} packages. Please refer to their
documentation (e.g., \code{?sandwich::vcovHAC}) to see the list of available
arguments. If no estimation type (argument \code{type}) is given, the default
type for \code{"HC"} equals the default from the \strong{sandwich} package; for type
\code{"CR"}, the default is set to \code{"CR3"}.}

\item{verbose}{Toggle warnings.}
}
\description{
Confidence intervals around predicted values
}
\details{
Typically, \code{get_predicted()} returns confidence intervals based on the standard
errors as returned by the \code{predict()}-function, assuming normal distribution
(\verb{+/- 1.96 * SE}) resp. a Student's t-distribution (if degrees of freedom are
available). If \code{predict()} for a certain class does \emph{not} return standard
errors (for example, \emph{merMod}-objects), these are calculated manually, based
on following steps: matrix-multiply \code{X} by the parameter vector \code{B} to get the
predictions, then extract the variance-covariance matrix \code{V} of the parameters
and compute \verb{XVX'} to get the variance-covariance matrix of the predictions.
The square-root of the diagonal of this matrix represent the standard errors
of the predictions, which are then multiplied by the critical test-statistic
value (e.g., ~1.96 for normal distribution) for the confidence intervals.

If \code{ci_type = "prediction"}, prediction intervals are calculated. These are
wider than confidence intervals, because they also take into account the
uncertainty of the model itself. Before taking the square-root of the
diagonal of the variance-covariance matrix, \code{get_predicted_ci()} adds the
residual variance to these values. For mixed models, \code{get_variance_residual()}
is used, while \code{get_sigma()^2} is used for non-mixed models.

It is preferred to rely on standard errors returned by \code{get_predicted()} (i.e.
returned by the \code{predict()}-function), because these are more accurate than
manually calculated standard errors. Use \code{get_predicted_ci()} only if standard
errors are not available otherwise. An exception are Bayesian models or
bootstrapped predictions, where \code{get_predicted_ci()} returns quantiles of the
posterior distribution or bootstrapped samples of the predictions. These are
actually accurate standard errors resp. confidence (or uncertainty) intervals.
}
\examples{
\dontshow{if (require("boot") && require("datawizard") && require("bayestestR")) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
# Confidence Intervals for Model Predictions
# ------------------------------------------

data(mtcars)

# Linear model
# ------------
x <- lm(mpg ~ cyl + hp, data = mtcars)
predictions <- predict(x)
ci_vals <- get_predicted_ci(x, predictions, ci_type = "prediction")
head(ci_vals)
ci_vals <- get_predicted_ci(x, predictions, ci_type = "confidence")
head(ci_vals)
ci_vals <- get_predicted_ci(x, predictions, ci = c(0.8, 0.9, 0.95))
head(ci_vals)

# Bootstrapped
# ------------
predictions <- get_predicted(x, iterations = 500)
get_predicted_ci(x, predictions)

ci_vals <- get_predicted_ci(x, predictions, ci = c(0.80, 0.95))
head(ci_vals)
datawizard::reshape_ci(ci_vals)

ci_vals <- get_predicted_ci(x,
  predictions,
  dispersion_method = "MAD",
  ci_method = "HDI"
)
head(ci_vals)


# Logistic model
# --------------
x <- glm(vs ~ wt, data = mtcars, family = "binomial")
predictions <- predict(x, type = "link")
ci_vals <- get_predicted_ci(x, predictions, ci_type = "prediction")
head(ci_vals)
ci_vals <- get_predicted_ci(x, predictions, ci_type = "confidence")
head(ci_vals)
\dontshow{\}) # examplesIf}
}
