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:

    1. Level 1: y_tij = π_0ij + e_tij, e_tij ~ N(0, σ²)
    2. Level 2: π_0ij = β_00j + r_0ij, r_0ij ~ N(0, τ_π²)
    3. Level 3: β_000j = γ_000 + u_00j, u_00j ~ N(0, τ_β²)

    Combined into a single equation:

    1. 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:

    1. library(ggplot2)
    2. # 1) jittered scatter + 2) group coloring + 3) individual trajectories and group mean lines
    3. ggplot(d, aes(x = time, y = y, color = factor(group))) +
    4. geom_line(aes(group = id), alpha = 0.2, color = "grey60") + # individual trajectories
    5. geom_point(position = position_jitter(width = 0.1, height = 0), alpha = 0.5) +
    6. stat_summary(fun = mean, geom = "line", linewidth = 1.2) + # group mean lines
    7. geom_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
    1. install.packages("lme4"); install.packages("lmerTest"); install.packages("ggplot2")
    2. library(lme4); library(lmerTest)
    3. # Step 1: null model (three-level random intercepts)
    4. m0 <- lmer(y ~ 1 + (1 | cluster) + (1 | cluster:id), data = d, REML = TRUE)
    5. # Step 2: add fixed effects (including the group x time interaction)
    6. m1 <- lmer(y ~ group * time + (1 | cluster) + (1 | cluster:id), data = d)
    7. # Step 3: add a random slope (let the time slope vary by individual)
    8. m2 <- lmer(y ~ group * time + (1 + time | cluster:id) + (1 | cluster), data = d)
    9. # Step 4: center continuous predictors to improve convergence and interpretability
    10. d$time_c <- as.numeric(scale(d$time, center = TRUE, scale = TRUE))
    11. # Extract results
    12. fixef(m2) # fixed effect estimates
    13. ranef(m2) # random effects (deviations for each group/individual)
    14. VarCorr(m2) # variance components

    Interpreting the Three-Level ICC

    To decide whether you really need a multilevel structure, calculate the three-level ICC:

    1. icc3 <- function(m){
    2. v <- as.data.frame(VarCorr(m)); vc <- setNames(v$vcov, v$grp); t <- sum(vc)
    3. c(level3_cluster = vc["cluster"]/t,
    4. corr_same_person = (vc["cluster"]+vc["cluster:id"])/t,
    5. level1_resid = vc["Residual"]/t)
    6. }
    7. 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:

    1. library(nlme)
    2. m_nl <- nlme(y ~ Asym + (R0 - Asym) * exp(-exp(lrc) * time),
    3. data = d,
    4. fixed = Asym + R0 + lrc ~ 1,
    5. random = Asym + lrc ~ 1 | cluster:id,
    6. start = c(Asym = 100, R0 = 5, lrc = 0),
    7. 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”
    1. isSingular(m2) # check for a singular fit
    2. m2b <- lmer(y ~ group * time_c + (1 + time_c | cluster:id) + (1 | cluster),
    3. data = d,
    4. control = lmerControl(optimizer = "bobyqa",
    5. 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.
    • 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.
    1. m1_ml <- update(m1, REML = FALSE); m2_ml <- update(m2, REML = FALSE)
    2. anova(m1_ml, m2_ml) # differences in fixed effects: ML
    3. AIC(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:

    1. Use visualization to identify signs of nonlinearity and heteroscedasticity.
    2. Start with the null model and add fixed and random effects step by step.
    3. Use the three-level ICC to decide whether the levels are needed.
    4. If convergence problems arise, use the checklist to simplify the model.
    5. Make robust model choices with LRTs (keeping ML vs. REML in mind) and information criteria.