get_predicted_ci: Confidence intervals around predicted values

In insight: Easy Access to Model Information for Various Model Objects

Confidence intervals around predicted values

Description

Confidence intervals around predicted values

Usage

get_predicted_ci(x, ...)

## Default S3 method:
get_predicted_ci(
  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

x	A statistical model (can also be a data.frame, in which case the second argument has to be a model).
...	Other argument to be passed, for instance to the model's predict() method, or get_predicted_ci().
predictions	A vector of predicted values (as obtained by stats::fitted(), stats::predict() or get_predicted()).
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 get_datagrid().
se	Numeric vector of standard error of predicted values. If NULL, standard errors are calculated based on the variance-covariance matrix.
ci	The interval level. Default is NULL, to be fast even for larger models. Set the interval level to an explicit value, e.g. 0.95, for ⁠95%⁠ CI).
ci_type	Can be "prediction" or "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 lm), as for other models (e.g., 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... ⁠[0, 1]⁠).
ci_method	The method for computing p values and confidence intervals. Possible values depend on model type. NULL uses the default method, which varies based on the model type. Most frequentist models: "wald" (default), "residual" or "normal". Bayesian models: "quantile" (default), "hdi", "eti", and "spi". Mixed effects lme4 models: "wald" (default), "residual", "normal", "satterthwaite", and "kenward-roger". See get_df() for details.
dispersion_method	Bootstrap dispersion and Bayesian posterior summary: "sd" or "mad".
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. A covariance matrix A function which returns a covariance matrix (e.g., stats::vcov()) A string which indicates the kind of uncertainty estimates to return. Heteroskedasticity-consistent: "HC", "HC0", "HC1", "HC2", "HC3", "HC4", "HC4m", "HC5". See ?sandwich::vcovHC Cluster-robust: "CR", "CR0", "CR1", "CR1p", "CR1S", "CR2", "CR3". See ?clubSandwich::vcovCR Bootstrap: "BS", "xy", "residual", "wild", "mammen", "fractional", "jackknife", "norm", "webb". See ?sandwich::vcovBS Other sandwich package functions: "HAC", "PC", "CL", "OPG", "PL". Kenward-Roger approximation: "kenward-roger". See ?pbkrtest::vcovAdj. Finite Population Correction: "fpc" applies the finite population correction. Requires the population_size to be specified in vcov_args. For mixed models, FPC is based on Lai et al. 2018. When vcov = "fpc", at least one of population_size (size of the finite population, must be larger than the number of observations in the model) or cluster_size (the finite size of cluster groups in the population, must be larger than the number of groups of the random effects) in the vcov_args argument. You can additionally apply the Kenward-Roger approximation with the kr argument, e.g. vcov_args = list(cluster_size = 15, kr = TRUE). Exceptions are following models: Model of class glmgee, which have pre-defined options for the variance-covariance matrix calculation. These are "robust", "df-adjusted", "model", "bias-corrected", and "jackknife". See ?glmtoolbox::vcov.glmgee for details. Model of class glmmTMB currently only support the "HC0" option. Models of class fixest use the vcov() method of the fixest package, so vcov accepts the types listed in ?fixest::vcov.fixest. Of the heteroskedasticity-consistent types, "HC0" to "HC3" are supported. "HC0" uses vcov = "hetero" without the small-sample adjustment (ssc = fixest::ssc(K.adj = FALSE)).
vcov_args	List of arguments to be passed to the function identified by the vcov argument. This function is typically supplied by the sandwich or clubSandwich packages. Please refer to their documentation (e.g., ?sandwich::vcovHAC) to see the list of available arguments. If no estimation type (argument type) is given, the default type for "HC" equals the default from the sandwich package; for type "CR", the default is set to "CR3". For vcov = "fpc", vcov_args must specify either population_size or cluster_size, depending on the model.
verbose	Toggle warnings.

Details

Typically, get_predicted() returns confidence intervals based on the standard errors as returned by the predict()-function, assuming normal distribution (⁠+/- 1.96 * SE⁠) resp. a Student's t-distribution (if degrees of freedom are available). If predict() for a certain class does not return standard errors (for example, merMod-objects), these are calculated manually, based on following steps: matrix-multiply X by the parameter vector B to get the predictions, then extract the variance-covariance matrix V of the parameters and compute ⁠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 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, get_predicted_ci() adds the residual variance to these values. For mixed models, get_variance_residual() is used, while get_sigma()^2 is used for non-mixed models.

Nonlinear mixed models of class nlme (from nlme::nlme()) have no model matrix X. For these models, the standard errors are calculated with the delta method: X is replaced by the Jacobian of the predictions with respect to the fixed effects, computed by central differences of predict(), with the random effects held at their predicted values. So the standard errors do not include the uncertainty of the random effects. get_predicted() uses the level of its predictions. A direct call to get_predicted_ci() uses the level argument, or the default level of predict() if level is missing. Only Wald confidence intervals are available. Prediction intervals, the vcov and vcov_args arguments, other values of ci_method and a level with more than one value are not yet supported for these models.

It is preferred to rely on standard errors returned by get_predicted() (i.e. returned by the predict()-function), because these are more accurate than manually calculated standard errors. Use get_predicted_ci() only if standard errors are not available otherwise. An exception are Bayesian models or bootstrapped predictions, where 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

# 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)

insight documentation built on Oct. 28, 2026, 5:11 p.m.