% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/merPredict.R
\name{predictInterval}
\alias{predictInterval}
\title{Predict from merMod objects with a prediction interval}
\usage{
predictInterval(
  merMod,
  newdata = NULL,
  which = c("full", "fixed", "random", "all"),
  level = 0.8,
  n.sims = 1000,
  stat = c("median", "mean"),
  type = c("linear.prediction", "probability"),
  include.resid.var = TRUE,
  returnSims = FALSE,
  seed = NULL,
  .parallel = FALSE,
  fix.intercept.variance = FALSE,
  ignore.fixed.terms = NULL,
  new.levels = c("zero", "draw")
)
}
\arguments{
\item{merMod}{a merMod object from lme4}

\item{newdata}{a data.frame of new data to predict}

\item{which}{a character specifying what to return, by default it returns the
full interval, but you can also select to return only the fixed variation or
the random component variation. If full is selected the resulting data.frame
will be \code{nrow(newdata) * number of model levels} long}

\item{level}{the width of the prediction interval}

\item{n.sims}{number of simulation samples to construct}

\item{stat}{take the median or mean of simulated intervals}

\item{type}{type of prediction to develop}

\item{include.resid.var}{logical, include or exclude the residual variance for
linear models}

\item{returnSims}{logical, should all n.sims simulations be returned?}

\item{seed}{numeric, optional argument to set seed for simulations}

\item{.parallel}{logical, use parallel computation (default FALSE)}

\item{fix.intercept.variance}{logical; should the variance of the intercept
term be adjusted downwards to roughly correct for its covariance with the
random effects, as if all the random effects are intercept effects?}

\item{ignore.fixed.terms}{a numeric or string vector of indexes or names of
fixed effects which should be considered as fully known (zero variance).}

\item{new.levels}{character, how to treat grouping levels in \code{newdata}
that were not present when the model was fit. \code{"zero"} (the default and
the historical behavior) drops the random effect for such levels, so the
prediction rests on the fixed effects plus residual variation. \code{"draw"}
instead samples each unobserved group's effect from the estimated
random-effect covariance (\code{VarCorr}), so the interval reflects
between-group uncertainty -- the analogue of
\code{brms::posterior_predict(allow_new_levels = TRUE)}. Observations that
share an unobserved level share the same sampled effect.}
}
\value{
a data.frame with three columns: fit, lwr and upr. If `returnSims`
  is TRUE the attribute `sim.results` contains the full simulation array.
}
\description{
This function provides a way to capture model uncertainty in
predictions from multi-level models fit with \code{lme4}. By drawing a sampling
distribution for the random and the fixed effects and then estimating the fitted
value across that distribution, it is possible to generate a prediction interval
for fitted values that includes all variation in the model except for variation
in the covariance parameters, theta. This is a much faster alternative than
bootstrapping for models fit to medium to large datasets.
}
