Class "merMod" of Fitted Mixed-Effect Models
merMod-class.Rd
A mixed-effects model is represented as a
merPredD
object and a response
module of a class that inherits from class
lmResp
. A model with a
lmerResp
response has class lmerMod
; a
glmResp
response has class glmerMod
; and a
nlsResp
response has class nlmerMod
.
Usage
# S3 method for class 'merMod'
anova(object, ..., refit = TRUE, model.names=NULL)
# S3 method for class 'merMod'
as.function(x, ...)
# S3 method for class 'merMod'
coef(object, ...)
# S3 method for class 'merMod'
deviance(object, REML = NULL, ...)
REMLcrit(object)
# S3 method for class 'merMod'
extractAIC(fit, scale = 0, k = 2, ...)
# S3 method for class 'merMod'
family(object, ...)
# S3 method for class 'merMod'
formula(x, fixed.only = FALSE, random.only = FALSE, ...)
# S3 method for class 'merMod'
fitted(object, ...)
# S3 method for class 'merMod'
logLik(object, REML = NULL, ...)
# S3 method for class 'merMod'
nobs(object, ...)
# S3 method for class 'merMod'
ngrps(object, ...)
# S3 method for class 'merMod'
terms(x, fixed.only = TRUE, random.only = FALSE, ...)
# S3 method for class 'merMod'
model.frame(formula, fixed.only = FALSE, ...)
# S3 method for class 'merMod'
model.matrix(object, type = c("fixed", "random", "randomListRaw"), ...)
# S3 method for class 'merMod'
print(x, digits = max(3, getOption("digits") - 3),
correlation = NULL, symbolic.cor = FALSE,
signif.stars = getOption("show.signif.stars"),
ranef.comp = "Std.Dev.",
ranef.corr = any(ranef.comp == "Std.Dev."), ...)
# S3 method for class 'merMod'
summary(object, correlation = , use.hessian = NULL, ...)
# S3 method for class 'summary.merMod'
print(x, digits = max(3, getOption("digits") - 3),
correlation = NULL, symbolic.cor = FALSE,
signif.stars = getOption("show.signif.stars"),
ranef.comp = c("Variance", "Std.Dev."),
ranef.corr = any(ranef.comp == "Std.Dev."), show.resids = TRUE, ...)
# S3 method for class 'merMod'
update(object, formula., ..., evaluate = TRUE)
# S3 method for class 'merMod'
weights(object, type = c("prior", "working"), ...)
Arguments
- object
an R object of class
merMod
, i.e., as resulting fromlmer()
, orglmer()
, etc.- x
an R object of class
merMod
orsummary.merMod
, respectively, the latter resulting fromsummary(<merMod>)
.- fit
an R object of class
merMod
.- formula
in the case of
model.frame
, amerMod
object.- refit
logical indicating if objects of class
lmerMod
should be refitted with ML before comparing models. The default isTRUE
to prevent the common mistake of inappropriately comparing REML-fitted models with different fixed effects, whose likelihoods are not directly comparable.- model.names
character vectors of model names to be used in the anova table.
- scale
Not currently used (see
extractAIC
).- k
see
extractAIC
.- REML
Logical. If
TRUE
, return the restricted log-likelihood rather than the log-likelihood. IfNULL
(the default), setREML
toisREML(object)
(seeisREML
).- fixed.only
logical indicating if only the fixed effects components (terms or formula elements) are sought. If false, all components, including random ones, are returned.
- random.only
complement of
fixed.only
; indicates whether random components only are sought. (Trying to specifyfixed.only
andrandom.only
at the same time will produce an error.)- correlation
(logical) for
summary.merMod
, indicates whether the correlation matrix should be computed and stored along with the covariance; forprint.summary.merMod
, indicates whether the correlation matrix of the fixed-effects parameters should be printed. In the latter case, whenNULL
(the default), the correlation matrix is printed when it has been computed bysummary(.)
, and when \(p <= 12\), and the cutoff12
may be modified byoptions(lme4.summary.cor.max = <n>)
- use.hessian
(logical) indicates whether to use the finite-difference Hessian of the deviance function to compute standard errors of the fixed effects; see
vcov.merMod
for details- digits
number of significant digits for printing
- symbolic.cor
should a symbolic encoding of the fixed-effects correlation matrix be printed? If so, the
symnum
function is used.- signif.stars
(logical) should significance stars be used?
- ranef.comp
character vector of length one or two, indicating if random-effects parameters should be reported on the variance and/or standard deviation scale.
- show.resids
should the quantiles of the scaled residuals be printed?
- formula.
see
update.formula
.- evaluate
see
update
.- type
For
weights()
,type of weights to be returned; either
"prior"
for the initially supplied weights or"working"
for the weights at the final iteration of the penalized iteratively reweighted least squares algorithm (PIRLS).model.matrix()
,type of model matrix to return: one of
"fixed"
giving the fixed effects model matrix,"random"
giving the random effects model matrix, or"randomListRaw"
giving a list of the raw random effects model matrices associated with each random effects term.
- ranef.corr
(logical) print correlations (rather than covariances) of random effects?
- ...
potentially further arguments passed from other methods.
S3 methods
The following S3 methods with arguments given above exist (this list is currently not complete):
-
%% TODO: document differences between update and update.merMod
anova
:returns the sequential decomposition of the contributions of fixed-effects terms or, for multiple arguments, model comparison statistics. For objects of class
lmerMod
the default behavior is to refit the models with ML if fitted withREML = TRUE
, this can be controlled via therefit
argument. See alsoanova
.as.function
:returns the deviance function, the same as
lmer(*, devFunOnly=TRUE)
, andmkLmerDevfun()
ormkGlmerDevfun()
, respectively.coef
:Computes the sum of the random and fixed effects coefficients for each explanatory variable for each level of each grouping factor.
extractAIC
:Computes the (generalized) Akaike An Information Criterion. If
isREML(fit)
, thenfit
is refitted using maximum likelihood.family
:family
of fitted GLMM. (Warning: this accessor may not work properly with customized families/link functions.)fitted
:Fitted values, given the conditional modes of the random effects. For more flexible access to fitted values, use
predict.merMod
.logLik
:Log-likelihood at the fitted value of the parameters. Note that for GLMMs, the returned value is only proportional to the log probability density (or distribution) of the response variable. See
logLik
.model.frame
:returns the
frame
slot ofmerMod
.model.matrix
:returns the fixed effects model matrix.
nobs
,ngrps
:Number of observations and vector of the numbers of levels in each grouping factor. See
ngrps
.summary
:Computes and returns a list of summary statistics of the fitted model, the amount of output can be controlled via the
print
method, see alsosummary
.print.summary
:Controls the output for the summary method.
update
:See
update
.
Deviance and log-likelihood of GLMMs
One must be careful when defining the deviance of a GLM. For example, should the deviance be defined as minus twice the log-likelihood or does it involve subtracting the deviance for a saturated model? To distinguish these two possibilities we refer to absolute deviance (minus twice the log-likelihood) and relative deviance (relative to a saturated model, e.g. Section 2.3.1 in McCullagh and Nelder 1989).
With GLMMs however, there is an additional complication involving the
distinction between the likelihood and the conditional likelihood.
The latter is the likelihood obtained by conditioning on the estimates
of the conditional modes of the spherical random effects coefficients,
whereas the likelihood itself (i.e. the unconditional likelihood)
involves integrating out these coefficients. The following table
summarizes how to extract the various types of deviance for a
glmerMod
object:
conditional | unconditional | |
relative | deviance(object) | NA in lme4 |
absolute | object@resp$aic() | -2*logLik(object) |
This table requires two caveats:
If the link function involves a scale parameter (e.g.
Gamma
) thenobject@resp$aic() - 2 * getME(object, "devcomp")$dims["useSc"]
is required for the absolute-conditional case.If adaptive Gauss-Hermite quadrature is used, then
logLik(object)
is currently only proportional to the absolute-unconditional log-likelihood.
For more information about this topic see the misc/logLikGLMM
directory in the package source.
Slots
resp
:A reference class object for an lme4 response module (
lmResp-class
).Gp
:See
getME
.call
:The matched call.
frame
:The model frame containing all of the variables required to parse the model formula.
flist
:See
getME
.cnms
:See
getME
.lower
:See
getME
.theta
:Covariance parameter vector.
beta
:Fixed effects coefficients.
u
:Conditional model of spherical random effects coefficients.
devcomp
:See
getME
.pp
:A reference class object for an lme4 predictor module (
merPredD-class
).optinfo
:List containing information about the nonlinear optimization.
See also
lmer
, glmer
,
nlmer
, merPredD
,
lmerResp
,
glmResp
,
nlsResp
Other methods for merMod
objects documented elsewhere include:
fortify.merMod
, drop1.merMod
,
isLMM.merMod
, isGLMM.merMod
,
isNLMM.merMod
, isREML.merMod
,
plot.merMod
, predict.merMod
,
profile.merMod
, ranef.merMod
,
refit.merMod
, refitML.merMod
,
residuals.merMod
, sigma.merMod
,
simulate.merMod
, summary.merMod
.
Examples
showClass("merMod")
#> Class "merMod" [package "lme4"]
#>
#> Slots:
#>
#> Name: Gp call frame flist cnms lower
#> Class: integer call data.frame list list numeric
#>
#> Name: theta beta u devcomp pp optinfo
#> Class: numeric numeric numeric list merPredD list
#>
#> Known Subclasses: "lmerMod", "glmerMod", "nlmerMod"
methods(class="merMod")## over 30 (S3) methods available
#> [1] PBmodcomp PBrefdist VarCorr
#> [4] anova as.function coef
#> [7] confint cooks.distance deviance
#> [10] df.residual drop1 extractAIC
#> [13] family fitted fixef
#> [16] formula getData getL
#> [19] getME hatvalues influence
#> [22] isGLMM isLMM isNLMM
#> [25] isREML logLik model.frame
#> [28] model.matrix model2restriction_matrix na.action
#> [31] ngrps nobs plot
#> [34] predict print profile
#> [37] qqmath ranef rePCA
#> [40] refit refitML residuals
#> [43] rstudent show sigma
#> [46] simulate summary terms
#> [49] update vcov weights
#> see '?methods' for accessing help and source code
m1 <- lmer(Reaction ~ Days + (Days | Subject), sleepstudy)
print(m1, ranef.corr = TRUE) ## print correlations of REs
#> Linear mixed model fit by REML ['lmerMod']
#> Formula: Reaction ~ Days + (Days | Subject)
#> Data: sleepstudy
#> REML criterion at convergence: 1743.628
#> Random effects:
#> Groups Name Std.Dev. Corr
#> Subject (Intercept) 24.741
#> Days 5.922 0.07
#> Residual 25.592
#> Number of obs: 180, groups: Subject, 18
#> Fixed Effects:
#> (Intercept) Days
#> 251.41 10.47
print(m1, ranef.corr = FALSE) ## print covariances of REs
#> Linear mixed model fit by REML ['lmerMod']
#> Formula: Reaction ~ Days + (Days | Subject)
#> Data: sleepstudy
#> REML criterion at convergence: 1743.628
#> Random effects:
#> Groups Name Std.Dev. Cov
#> Subject (Intercept) 24.741
#> Days 5.922 9.60
#> Residual 25.592
#> Number of obs: 180, groups: Subject, 18
#> Fixed Effects:
#> (Intercept) Days
#> 251.41 10.47