Troubleshoot common issues

If you fit a model and any of the following situations arise, you cannot trust the estimates given to you by that model. You will need to tweak the model, as outlined in each section below, until the problems are solved.

Model failed to converge

This warning typically looks something like:

warning(s): Model failed to converge with max|grad| = 0.0071877 (tol = 0.002, component 1)

What does it mean for a model to “fail to converge”?

A bit of backstory: LMMs are fit using a method called “maximum likelihood estimation”, abbreviated as MLE. This process involves taking a guess at the model’s parameters, seeing how likely it is that those parameters would have generated the observed data, and then improving our guesses until we’ve found the parameters with the greatest probability of having generated the observed data. Once we’ve found those most likely parameters, we say the model has “converged”.

Sometimes, however, the MLE process can get stuck, resulting in “non-convergence” or “failure to converge”. Non-convergence is pretty common when we try to fit a maximal model, because with more parameters, there are more places for MLE to go wrong.

If your model fails to converge, try changing the model’s optimiser, and if that doesn’t work, then try simplifying the random effect structure.

Singularity

This warning typically looks like:

boundary (singular) fit: see ?isSingular

But the model will not always warn you about singularities, so you also need to look carefully at the variance components in the model summary.

If you see:

  • a correlation between intercept and slope adjustments of 1 or –1, or
  • SD or variance of 0 for any random effects

then these numbers don’t represent the actual variances or correlations in the data. This situation is another instance of a singularity: a technical problem in estimating the model parameters.

If your model has a “singular fit”, then that means that the random effect structure that you’ve defined is too complex to be supported by the data. In other words, the model is not able to accurately estimate all of the parameters that you want it to estimate.

In case of a singularity, try changing the model’s optimiser, and if that doesn’t work, then try simplifying the random effect structure.

In linear algebra terms, an extreme correlation value or an estimate of 0 variance/SD both indicate that the model’s variance-covariance matrix is degenerate.

If a matrix is degenerate, then it cannot be inverted. This is a problem because behind the scenes, the model must invert the variance-covariance matrix in order to estimate the fixed effect parameters. So when the matrix cannot be inverted, then the fixed effects cannot be reliably estimated.

Too few observations

This warning might look something like:

Error: number of observations (=150) <= number of random effects (=150) for term (1 + music | pid); the random-effects parameters and the residual variance (or scale parameter) are probably unidentifiable

This warning arises when the random effect structure is too complex for the given data to support. It’s common when each level of a grouping variable has exactly one observation for each level of a predictor, for example.

If you have too many random effects for too little data, the best solution is to simplify the random effect structure.

Variables need rescaling

This warning usually looks something like:

Warning messages:
1: Some predictor variables are on very different scales:
consider rescaling

Warning messages:
1: In checkConv(attr(opt, “derivs”), opt$par, ctrl = control$checkConv, :
Model is nearly unidentifiable: large eigenvalue ratio
- Rescale variables?

LMMs can have a hard time estimating parameters when variances are too close to zero. In that situation, warnings like these can arise.

If your model recommends that you rescale your variables, the best solution is to mean-centre or z-score your predictor(s)—and make sure you interpret the coefficients accordingly!

Other issues?

  • Google your error messages
  • Check on Stack Overflow / Stack Exchange for solutions others have used

Linked flash cards