Predictions from a model at new data values

The predict method for merMod objects, i.e. results of lmer(), glmer(), etc.

Usage

# S3 method for class 'merMod'
predict(object, newdata = NULL, newparams = NULL,
    re.form = NULL,
    random.only=FALSE, terms = NULL,
    type = c("link", "response"), allow.new.levels = FALSE,
    na.action = na.pass,
    se.fit = FALSE,
    ...)

Arguments

object: a fitted model object
newdata: data frame for which to evaluate predictions.
newparams: new parameters to use in evaluating predictions, specified as in the start parameter for lmer or glmer – a list with components theta and/or (for GLMMs) beta.
re.form: (formula, NULL, or NA) specify which random effects to condition on when predicting. If NULL, include all random effects; if NA or ~0, include no random effects.
random.only: (logical) ignore fixed effects, making predictions only using random effects?
terms: a terms object - unused at present.
type: character string - either "link", the default, or "response" indicating the type of prediction object returned.
allow.new.levels: logical if new levels (or NA values) in newdata are allowed. If FALSE (default), such new values in newdata will trigger an error; if TRUE, then the prediction will use the unconditional (population-level) values for data with previously unobserved levels (or NAs).
na.action: function determining what should be done with missing values for fixed effects in newdata. The default is to predict NA: see na.pass.
se.fit: (Experimental) A logical value indicating whether the standard errors should be included or not. Default is FALSE.
...: optional additional parameters. None are used at present.

Value

a numeric vector of predicted values

Details

If any random effects are included in re.form (i.e. it is not ~0 or NA), newdata must contain columns corresponding to all of the grouping variables and random effects used in the original model, even if not all are used in prediction; however, they can be safely set to NA in this case.
There is no option for computing standard errors of predictions because it is difficult to define an efficient method that incorporates uncertainty in the variance parameters; we recommend bootMer for this task.

Examples

(gm1 <- glmer(cbind(incidence, size - incidence) ~ period + (1 |herd), cbpp, binomial))
#> Generalized linear mixed model fit by maximum likelihood (Laplace
#>   Approximation) [glmerMod]
#>  Family: binomial  ( logit )
#> Formula: cbind(incidence, size - incidence) ~ period + (1 | herd)
#>    Data: cbpp
#>       AIC       BIC    logLik -2*log(L)  df.resid 
#>  194.0531  204.1799  -92.0266  184.0531        51 
#> Random effects:
#>  Groups Name        Std.Dev.
#>  herd   (Intercept) 0.6421  
#> Number of obs: 56, groups:  herd, 15
#> Fixed Effects:
#> (Intercept)      period2      period3      period4  
#>     -1.3983      -0.9919      -1.1282      -1.5797  
str(p0 <- predict(gm1))            # fitted values
#>  Named num [1:56] -0.809 -1.801 -1.937 -2.388 -1.697 ...
#>  - attr(*, "names")= chr [1:56] "1" "2" "3" "4" ...
str(p1 <- predict(gm1,re.form=NA))  # fitted values, unconditional (level-0)
#>  Named num [1:56] -1.4 -2.39 -2.53 -2.98 -1.4 ...
#>  - attr(*, "names")= chr [1:56] "1" "2" "3" "4" ...
newdata <- with(cbpp, expand.grid(period=unique(period), herd=unique(herd)))
str(p2 <- predict(gm1,newdata))    # new data, all RE
#>  Named num [1:60] -0.809 -1.801 -1.937 -2.388 -1.697 ...
#>  - attr(*, "names")= chr [1:60] "1" "2" "3" "4" ...
str(p3 <- predict(gm1,newdata,re.form=NA)) # new data, level-0
#>  Named num [1:60] -1.4 -2.39 -2.53 -2.98 -1.4 ...
#>  - attr(*, "names")= chr [1:60] "1" "2" "3" "4" ...
str(p4 <- predict(gm1,newdata,re.form= ~(1|herd))) # explicitly specify RE
#>  Named num [1:60] -0.809 -1.801 -1.937 -2.388 -1.697 ...
#>  - attr(*, "names")= chr [1:60] "1" "2" "3" "4" ...
stopifnot(identical(p2, p4))
#> boundary (singular) fit: see help('isSingular')