How to Fit Three-Level Hierarchical Linear Models (HLM) in R: Modeling, Diagnostics, and Convergence Troubleshooting
Hierarchical linear models (HLM), also called multilevel or mixed linear models, handle nested data: repeated measures of the same person, individuals grouped into teams or schools, or students nested within classes. Treating these observations as independent underestimates standard errors and inflates significance. This guide explains three-level HLM in R with runnable lme4 and lmerTest code. It starts with an empty random-intercept model and adds fixed effects, random slopes, and predictor centering. It also shows how to interpret a three-level ICC, handle nonlinear responses with an nlme mixed model, and use a checklist to fix singular fits and convergence failures. You will also learn to compare models with likelihood ratio tests and information criteria, and to set up reproducible workflows.
1. Why You Need Hierarchical Linear Models
Experimental, ecological, and survey researchers often ask the same three questions about HLM (hierarchical linear models, also called multilevel or mixed linear models):
- What is it?
- How do you fit one?
- How do you fix convergence errors?
The underlying problem is that data are often not independent of one another. They have a natural “nested” structure:
- The same respondent is measured repeatedly.
- Students in the same class belong to the same school.
- Observations of the same subject at multiple time points are correlated.
Applying ordinary linear regression to such data violates the independence-of-observations assumption. The consequences:
- Standard errors are underestimated.
- Significance is exaggerated.
- Conclusions become distorted.
HLM lets you model variation from different sources within a single model. It separates differences between individuals from variation within individuals.
2. What the Three Levels Mean
In repeated-measures data, a typical three-level structure looks like this:
- Level 1 is the finest-grained observation (for example, a person’s measurement on a given day).
- Level 2 is the individual who is observed repeatedly (a single subject).
- Level 3 is the higher-level group the individual belongs to (treatment group, class, or study site).
You can describe this as “measurement points t nested within individuals i, which are in turn nested within groups j.”
At its core, a three-level model lets the intercept (and, if needed, the slope) vary randomly at each level. It breaks down sources of variation layer by layer.
3. Model Specification
Start with a “null model” (random intercept) that contains no predictors. At the three levels, it is written as follows:
Level 1: y_tij = π_0ij + e_tij, e_tij ~ N(0, σ²)Level 2: π_0ij = β_00j + r_0ij, r_0ij ~ N(0, τ_π²)Level 3: β_000j = γ_000 + u_00j, u_00j ~ N(0, τ_β²)
Combined into a single equation:
y_tij = γ_000 + u_00j + r_0ij + e_tij
In this equation:
- γ_000 is the overall mean intercept (the fixed effect).
- u_00j, r_0ij, and e_tij are the random residuals at Level 3, Level 2, and Level 1, respectively.
If you want to know whether the slope of a predictor x varies across individuals or groups, add a random-slope term at the corresponding level.
4. Fixed Effects vs. Random Effects
The two types of effects play different roles:
- Fixed effects are the quantities you genuinely care about and want to generalize to the population. Examples include treatment effects, time trends, and the average influence of a covariate.
- Random effects are control terms that absorb expected differences between individuals or groups. They are assumed to follow a normal distribution with mean zero.
Apply this rule of thumb:
- If your question is “how large is the average effect,” set the effect as a fixed effect.
- If you only want to describe variation that is expected to exist across groups or individuals, set it as a random effect.
The level of a variable is another guide:
- If its levels cover everything you care about (for example, treatment vs. control), use a fixed effect.
- If it is randomly sampled from a larger population (for example, randomly selected subjects or schools), use a random effect.
5. Data Exploration Before You Start
When visualizing hierarchical data, do three things. The code below shows how:
library(ggplot2)# 1) jittered scatter + 2) group coloring + 3) individual trajectories and group mean linesggplot(d, aes(x = time, y = y, color = factor(group))) +geom_line(aes(group = id), alpha = 0.2, color = "grey60") + # individual trajectoriesgeom_point(position = position_jitter(width = 0.1, height = 0), alpha = 0.5) +stat_summary(fun = mean, geom = "line", linewidth = 1.2) + # group mean linesgeom_smooth(method = "loess", se = FALSE)
Plots like this usually reveal three things:
- Possible nonlinearity. The relationship may not be linear; a straight line is only a rough approximation.
- Heteroscedasticity. There may be larger variation at low mean values, or a “ceiling” effect.
- Systematic individual differences. Some curves run almost parallel, which suggests you may need a random slope.
Also check for outliers and measurement error. Do not blindly include observations that clearly deviate, because they will distort the variance component estimates.
6. A Step-by-Step Fitting Strategy (Runnable)
Build your models from simple to complex. The code below runs directly using lme4 and lmerTest.
Your data must be in long format:
- One observation per row.
- The following columns:
| Column | Meaning |
|---|---|
y |
Outcome |
time |
Observation (Level 1) |
id |
Individual (Level 2) |
cluster |
Group (Level 3) |
group |
Treatment group |
install.packages("lme4"); install.packages("lmerTest"); install.packages("ggplot2")library(lme4); library(lmerTest)# Step 1: null model (three-level random intercepts)m0 <- lmer(y ~ 1 + (1 | cluster) + (1 | cluster:id), data = d, REML = TRUE)# Step 2: add fixed effects (including the group x time interaction)m1 <- lmer(y ~ group * time + (1 | cluster) + (1 | cluster:id), data = d)# Step 3: add a random slope (let the time slope vary by individual)m2 <- lmer(y ~ group * time + (1 + time | cluster:id) + (1 | cluster), data = d)# Step 4: center continuous predictors to improve convergence and interpretabilityd$time_c <- as.numeric(scale(d$time, center = TRUE, scale = TRUE))# Extract resultsfixef(m2) # fixed effect estimatesranef(m2) # random effects (deviations for each group/individual)VarCorr(m2) # variance components
Interpreting the Three-Level ICC
To decide whether you really need a multilevel structure, calculate the three-level ICC:
icc3 <- function(m){v <- as.data.frame(VarCorr(m)); vc <- setNames(v$vcov, v$grp); t <- sum(vc)c(level3_cluster = vc["cluster"]/t,corr_same_person = (vc["cluster"]+vc["cluster:id"])/t,level1_resid = vc["Residual"]/t)}icc3(m0)
If level3_cluster is close to zero, the correlation at the group level is weak. A two-level or even a simpler model may be sufficient.
7. When the Linearity Assumption Does Not Hold
If the response curve is clearly curved (for example, a growth curve that levels off), a linear model will fit poorly in a systematic way. In that case, use a nonlinear mixed model instead.
A common misconception needs clarifying: nonlinear mixed models usually parameterize the mean response or the curve parameters directly. They do not simply wrap a model in a link function. Link functions belong mainly to the generalized linear and generalized additive model families.
Implementation essentials:
- Choose the curve family based on the underlying mechanism (asymptotic, saturating, or logistic).
- Let curve parameters (such as the asymptote or the rate of change) vary randomly across individuals or groups.
- Set reasonable starting values to increase the chances of convergence.
The example below uses an asymptotic curve in nlme. It also uses variance function weights to handle heteroscedasticity:
library(nlme)m_nl <- nlme(y ~ Asym + (R0 - Asym) * exp(-exp(lrc) * time),data = d,fixed = Asym + R0 + lrc ~ 1,random = Asym + lrc ~ 1 | cluster:id,start = c(Asym = 100, R0 = 5, lrc = 0),weights = varPower())
Nonlinear fitting is sensitive to starting values. It helps to fit a few representative individuals with ordinary nls first to obtain reasonable start values. Then scale the model to the full sample.
8. Fitting Failures and Convergence Diagnostics: A Checklist
Multilevel and nonlinear models frequently report “fitting failed.” Use the checklist below to work through the problem systematically:
| Check | How to judge | How to fix |
|---|---|---|
| Sample size per level | A level has only 2–3 units | Simplify the random structure; remove random terms from sparse levels |
| Singular fit | isSingular(m) returns TRUE, and a variance has collapsed to 0 |
Remove unnecessary random-slope and correlation terms |
| Variable scaling | Variables are on very different scales | Standardize or center continuous variables |
| Optimizer and iterations | The model repeatedly fails to converge | Switch the optimizer and raise the iteration limit |
| Random structure complexity | The model still fails from a complex specification | Reduce in this order: “intercept + slope + correlation” → “random intercept only” |
isSingular(m2) # check for a singular fitm2b <- lmer(y ~ group * time_c + (1 + time_c | cluster:id) + (1 | cluster),data = d,control = lmerControl(optimizer = "bobyqa",optCtrl = list(maxfun = 2e5)))
9. Model Comparison and Evaluation
To judge whether an extra random effect is worth adding, keep these principles in mind:
- Likelihood ratio tests (LRT). When comparing nested models, the likelihood must be comparable.
- If the difference lies in the fixed effects, use ML (
REML = FALSE). REML likelihoods are not comparable when the fixed effects differ. - When testing random effects, REML is acceptable. However, variance components are tested on the boundary (variance = 0). The null distribution is therefore not a standard chi-square, so interpret results conservatively or use a parametric bootstrap.
- If the difference lies in the fixed effects, use ML (
- Information criteria. For non-nested models or more complex situations, use AIC or BIC. Lower values are better.
- Residual diagnostics. Hierarchical residuals should be approximately normal and show no clear heteroscedasticity.
- Variance explained. Measure explanatory power using the ICC together with the drop in variance components as fixed effects are added step by step.
m1_ml <- update(m1, REML = FALSE); m2_ml <- update(m2, REML = FALSE)anova(m1_ml, m2_ml) # differences in fixed effects: MLAIC(m1, m2); BIC(m1, m2)
10. Engineering and Scaling Up
When you are working with large datasets, tuning repeatedly, or running cross-validation, organize the analysis into reusable steps:
- Data loading
- Visualization
- Stepwise modeling
- Diagnostic evaluation
Fix a random seed to keep results reproducible.
As the computational load grows, cloud platforms can help. Their general-purpose services let you scale up compute and run configurations in parallel:
- Elastic compute for parallel runs
- Containerized scheduling to orchestrate those runs
- Object storage, logging, and monitoring with alerts to track long-running jobs
These standard capability categories, such as general-purpose compute, object storage, and log monitoring, have equivalents across mainstream cloud platforms. The right choice depends on your budget, compliance requirements, and existing tech stack. With this setup, you can turn a one-off analysis into a pipeline that runs continuously.
Wrap-Up
The value of a three-level linear model is that it uses one framework to answer two questions at once: “what is the average level?” and “where do the differences come from?”
The practical workflow is straightforward:
- Use visualization to identify signs of nonlinearity and heteroscedasticity.
- Start with the null model and add fixed and random effects step by step.
- Use the three-level ICC to decide whether the levels are needed.
- If convergence problems arise, use the checklist to simplify the model.
- Make robust model choices with LRTs (keeping ML vs. REML in mind) and information criteria.
