troubleshooting: Troubleshooting
Description
This page attempts to summarize some of the common problems with
fitting [gn]lmer models and how to troubleshoot them.
-
failure to converge in (xxxx) evaluations The
optimizer hit its maximum limit of function evaluations. To
increase this, use the optControl argument of
[g]lmerControl -- for Nelder_Mead and bobyqa
the relevant parameter is maxfun; for optim and
optimx-wrapped optimizers, including
nlminbwrap, it's maxit; for
nloptwrap, it's maxeval.
-
Model failed to converge with max|grad| ... The scaled
gradient at the fitted (RE)ML estimates
is worryingly large. Try
- refitting the parameters starting at the current
estimates: getting consistent results (with no warning)
suggests a false positive
- switching optimizers: getting consistent
results suggests there is not really a problem; getting a similar
log-likelihood with different parameter estimates suggests that
the parameters are poorly determined (possibly the result of
a misspecified or overfitted model)
- compute values of the deviance in the neighbourhood of the estimated
parameters to double-check that
lme4 has really found a
local optimum.
-
Hessian is numerically singular: parameters are not
uniquely determined
The Hessian (inverse curvature matrix) at the maximum likelihood or REML
estimates has a very large eigenvalue, indicating that (within numerical
tolerances) the surface is completely flat in some direction.
The model may be misspecified, or extremely badly scaled (see
"Model is nearly unidentifiable").
-
Model is nearly unidentifiable ... Rescale variables?
The Hessian (inverse curvature matrix) at the maximum likelihood or REML
estimates has a large eigenvalue, indicating that the surface is
nearly flat in some direction. Consider centering and/or scaling
continuous predictor variables.
-
Contrasts can be applied only to factors with 2 or more levels
One or more of the categorical predictors in the model has fewer than two
levels. This may be due to user error when converting these predictors to
factors prior to modeling, or it may result from some factor levels being
eliminated due to NAs in other predictors. Double-check the number
of data points in each factor level to see which one is the culprit:
lapply(na.omit(df[,vars]), table) (where df is the
data.frame and vars are the column names of your predictor
variables).