ALDEx3 Mixed-Effects Models

Motivation

ALDEx3 fits a regression model to every Monte Carlo draw of the latent log-abundance for every feature. When samples are grouped, for example repeated samples from the same participant, that regression is a linear mixed model. Fitting a full mixed model, including its variance components, separately for every feature and every draw can dominate runtime.

ALDEx3 offers three mixed-effects engines:

  • method = "lme4" fits every draw fully with lme4/lmerTest;
  • method = "nlme" fits every draw fully with nlme, and supports residual correlation structures;
  • method = "blmm" is designed as a drop-in replacement for lme4 inside ALDEx3. It accepts the same lme4 model formulas and targets the same REML fit and Satterthwaite inference, but because ALDEx3 refits the model to many posterior draws of the same feature, BLMM shares work across those draws and can be much faster.

This vignette explains the model, what BLMM approximates and how it computes standard errors and degrees of freedom, and then works through an example.

The model

Fix one feature. For Monte Carlo draw \(s\), let \(y_s \in \mathbb{R}^{N}\) be the vector of latent log-abundances across the \(N\) samples. Every engine targets the usual Gaussian linear mixed model for each draw, \[ y_s = X\beta_s + Z u_s + \varepsilon_s, \qquad u_s \sim N(0, \sigma_s^2 \Sigma_{\theta_s}), \qquad \varepsilon_s \sim N(0, \sigma_s^2 I_N), \] fitted by restricted maximum likelihood (REML).

Here \(X \in \mathbb{R}^{N \times p}\) is the fixed-effects design matrix, \(\beta_s \in \mathbb{R}^{p}\) the fixed-effect coefficients, \(Z \in \mathbb{R}^{N \times q}\) the random-effects design matrix, and \(u_s \in \mathbb{R}^{q}\) the random effects. The residual standard deviation is \(\sigma_s > 0\), and \(I_N\) is the \(N \times N\) identity matrix. The design matrices are the same for every draw; only the response \(y_s\) changes.

The parameter vector \(\theta_s\) determines the random-effects covariance relative to the residual variance. As in lme4, it does so through a lower-triangular factor \(\Lambda_{\theta_s}\): \[ \Sigma_{\theta_s} = \Lambda_{\theta_s}\Lambda_{\theta_s}^T . \] The entries of \(\theta_s\) are the entries of this relative Cholesky factor; its diagonal entries are constrained to be nonnegative. For a random intercept with \(m\) groups, \(\Lambda_{\theta_s} = \theta_s I_m\), so \(\theta_s\) is simply the ratio of the random-intercept standard deviation to the residual standard deviation. A diagonal entry of zero is a boundary fit, for example a random-intercept variance estimated as zero.

The profiled REML objective

After the fixed effects and the residual scale are profiled out, the REML criterion depends only on \(\theta_s\). Following lme4, define \[ A_{\theta} = I_q + \Lambda_{\theta}^T Z^T Z \Lambda_{\theta} = L_{\theta}L_{\theta}^T, \qquad R_{ZX,\theta} = L_{\theta}^{-1}\Lambda_{\theta}^T Z^T X, \qquad M_{\theta} = X^T X - R_{ZX,\theta}^T R_{ZX,\theta}, \] where \(L_\theta\) is the lower Cholesky factor of \(A_\theta\). The matrix \(M_\theta\) equals \(X^T V_\theta^{-1} X\) for the relative marginal covariance \(V_\theta = Z\Sigma_\theta Z^T + I_N\); it is the generalized least-squares (GLS) information for \(\beta\). The response enters through the penalized weighted residual sum of squares, \[ \mathrm{PWRSS}_s(\theta) = \|y_s\|^2 - \|R_{ZY,s,\theta}\|^2 - \|C_{s,\theta}\|^2, \] with \(R_{ZY,s,\theta} = L_{\theta}^{-1}\Lambda_{\theta}^T Z^T y_s\), \(C_{s,\theta} = L_{X,\theta}^{-1}(X^T y_s - R_{ZX,\theta}^T R_{ZY,s,\theta})\), and \(M_\theta = L_{X,\theta}L_{X,\theta}^T\).

With \(d = N - p\), the profiled REML objective for draw \(s\) is, up to a constant, \[ \ell_s(\theta) = \frac{1}{2} \left\{ \log |A_{\theta}| + \log |M_{\theta}| + d\log\frac{\mathrm{PWRSS}_s(\theta)}{d} \right\}. \] Its minimizer \(\hat\theta_s\) is the REML covariance estimate for draw \(s\). Given \(\hat\theta_s\), the fixed effects are the GLS solution \[ \hat\beta_s = M_{\hat\theta_s}^{-1} X^T V_{\hat\theta_s}^{-1} y_s, \qquad \hat\sigma_s^2 = \mathrm{PWRSS}_s(\hat\theta_s)/d . \]

The first two terms of \(\ell_s\) depend only on the shared design. Only the \(\mathrm{PWRSS}\) term depends on the draw. This is what BLMM exploits.

What BLMM approximates

Full fitting minimizes \(\ell_s\) from scratch for every draw. BLMM instead does the following for each feature.

  1. Center each draw. Regress \(y_s\) on \(X\) by ordinary least squares, keep the coefficients \(a_s\), and fit the residuals \(z_s = y_s - Xa_s\). Shifting a response by \(Xa_s\) leaves \(\ell_s\) and the standard errors unchanged and shifts \(\hat\beta_s\) by exactly \(a_s\), which is added back at the end. This is the same model; it only improves numerical accuracy when fixed effects are large.
  2. Fit one anchor. Minimize the average objective \[ \bar{\ell}(\theta) = \frac{1}{S}\sum_{s=1}^S \ell_s(\theta) \] over all \(S\) draws, giving \(\bar\theta\). Because the design is shared, one evaluation of \(\bar\ell\) needs a single factorization of \(A_\theta\) and \(M_\theta\) plus one multi-column solve for all draws, so the anchor costs roughly as much as one ordinary fit. The draws are not treated as extra observations; the anchor is only a starting point.
  3. Refine each draw. Starting at \(\bar\theta\), minimize the draw’s own \(\ell_s\) with at most eight safeguarded Newton steps. Each step uses the gradient and Hessian of \(\ell_s\) (computed by automatic differentiation, with the Hessian damped if it is not positive definite), is shortened if it would increase the objective, and respects the bounds on \(\theta\). Because draws of the same feature are usually similar, the anchor is close to each draw’s optimum and a few steps suffice.
  4. Check and compute inference. Accept the draw only when the refinement has converged and its standard errors and degrees of freedom have settled (see Stopping and boundary checks). Then compute estimates, standard errors and Satterthwaite degrees of freedom at the draw’s own estimate \(\hat\theta_s\).
  5. Refit what fails. A draw that does not pass the checks is refit fully with lmerTest, and a single warning reports how many draws were refit. Accepted draws keep their BLMM results. If the anchor itself cannot be computed, every draw of that feature is refit.

So the fitted model is unchanged, and the fixed effects are always the exact GLS solution at the draw’s covariance estimate. What BLMM approximates is the covariance optimization: it stops after a bounded number of steps from a shared starting point, accepting the result only when numerical checks show it is converged. This is the default, test = "t.satterthwaite.adaptive".

Standard errors and degrees of freedom

For a contrast vector \(c\) (a unit vector when testing a single coefficient), the estimate and its squared standard error at \(\hat\theta_s\) are \[ \hat\delta_{s} = c^T\hat\beta_s, \qquad v_{s} = \frac{\mathrm{PWRSS}_s(\hat\theta_s)}{d}\; c^T M_{\hat\theta_s}^{-1} c . \] The test statistic \(t_s = \hat\delta_s / \sqrt{v_s}\) is compared with a \(t\) distribution on Satterthwaite degrees of freedom \(\nu_s\), as in lmerTest.

The idea behind Satterthwaite df is that \(v_s\) is itself estimated: it depends on \(\hat\theta_s\) and \(\hat\sigma^2_s\), which are uncertain. If \(v_s\) were a scaled \(\chi^2\) variable with \(\nu\) df, it would satisfy \(\nu = 2v_s^2/\operatorname{Var}(v_s)\). Satterthwaite’s method estimates \(\operatorname{Var}(v_s)\) with the delta method and solves for \(\nu\). With \[ H_s = \nabla^2 \ell_s(\hat\theta_s), \qquad u_s = \nabla \log \mathrm{PWRSS}_s(\hat\theta_s), \qquad b_s = \nabla \log\left(c^T M_{\theta}^{-1} c\right)\Big|_{\hat\theta_s}, \] this gives \[ \boxed{\displaystyle \nu_s = \frac{2}{\,2/d + (u_s + b_s)^T H_s^{-1} (u_s + b_s)\,}} \] Each term has a direct reading. The \(2/d\) term is the uncertainty in \(\hat\sigma^2\) alone; with no random effects it gives the ordinary least-squares df \(d = N - p\). The quadratic term is the extra uncertainty from estimating the covariance parameters: \(u_s + b_s\) measures how sensitive the log standard error is to \(\theta\), and \(H_s^{-1}\) is the approximate sampling covariance of \(\hat\theta_s\). Because \(H_s\) is positive definite at a minimum, \(\nu_s \le d\). BLMM computes \(u_s\) and \(b_s\) by symmetric finite differences and uses the undamped Hessian at the accepted point. A nonfinite or nonpositive df causes a refit; small positive df are not clipped.

Derivation of the df formula

Drop the index \(s\), write \(\eta = \log\sigma^2\), \(a(\theta) = c^T M_\theta^{-1} c\) and \(r(\theta) = \mathrm{PWRSS}(\theta)\). Before \(\sigma^2\) is profiled out, the REML objective is, up to a constant, \[ F(\theta, \eta) = \tfrac{1}{2}\left\{\log|A_\theta| + \log|M_\theta| + d\eta + r(\theta)e^{-\eta}\right\}, \] with profiled optimum \(\hat\eta(\theta) = \log\{r(\theta)/d\}\), so that \(F(\theta, \hat\eta(\theta)) = \ell(\theta)\) up to a constant. At the optimum, the Hessian of \(F\) in \((\theta, \eta)\) is \[ J = \begin{pmatrix} H + \frac{d}{2}uu^T & -\frac{d}{2}u \\ -\frac{d}{2}u^T & \frac{d}{2} \end{pmatrix}, \] where \(H = \nabla^2\ell\) and \(u = \nabla\log r\). The squared standard error is \(v = e^\eta a(\theta)\), whose log-gradient in \((\theta, \eta)\) is \(g = (b^T, 1)^T\). Block inversion gives \[ g^T J^{-1} g = \frac{2}{d} + (b + u)^T H^{-1} (b + u). \] The delta method with \(J^{-1}\) as the parameter covariance gives \(\operatorname{Var}(v) \approx v^2\, g^T J^{-1} g\), and \(\nu = 2v^2/\operatorname{Var}(v)\) yields the boxed formula. Because \(\ell\) is half the REML deviance, \(H\) is the Hessian of a negative log likelihood and no extra factor of two appears.

Stopping and boundary checks

A draw’s refinement is accepted only when two things hold.

  • The fit has converged. With gradient \(g_s\) and Newton correction \(H_s^{-1}g_s\), the Newton decrement \(\sqrt{g_s^T H_s^{-1} g_s}\) must be at most \(10^{-4}\) and the largest coordinate of the correction at most \(10^{-3}\). BLMM also checks that no point with a covariance parameter set to zero has a lower objective.
  • The inference has settled. BLMM recomputes inference at the point one Newton correction further on. For every coefficient and contrast, the log standard error and log df must change by at most \(10^{-3}\), the lower-tail probability by at most \(10^{-5}\), and the \(t\) statistic by at most \(10^{-4}\).

If either check fails, refinement continues within the eight-step budget; a draw still unresolved after eight steps is refit with lmerTest.

Boundary fits need separate treatment, because the df formula assumes an interior minimum. Covariance parameters within \(10^{-10}\) of zero are set exactly to zero. BLMM then checks that the objective cannot be lowered by moving into the feasible region and that the curvature there is nonnegative. Two boundary cases receive local inference:

  • All covariance parameters are zero. The model reduces to ordinary least squares: estimates and standard errors are the least-squares ones and the df are \(d = N - p\), which is the limit of the formula above.
  • Whole columns of \(\Lambda_\theta\) are zero. For example, one of two random-effect terms has zero variance. Those coordinates are dropped after BLMM checks that they decouple from the rest (zero gradient, zero cross curvature and zero sensitivities), and the interior rules and df formula are applied to the remaining coordinates.

Any other boundary case, such as a zero diagonal entry with a nonzero entry below it, is refit with lmerTest. All of these are first-order calculations at the fitted covariance; they do not account for a variance having been estimated as zero from the data.

Worked example

The oral_mouthwash_data dataset has a repeated-measures design: each participant received one of four treatments and was sampled before, 15 minutes after and 2 hours after treatment. A random intercept per participant accounts for the repeated sampling. The model formula uses lme4 syntax:

set.seed(42)
library(ALDEx3)
data("oral_mouthwash_data", package = "ALDEx3")

Y <- oral_mouthwash_data$counts
keep_names <- row.names(Y[((rowSums(Y == 0)) / ncol(Y)) <= 0.75, ])
other <- colSums(Y[((rowSums(Y == 0)) / ncol(Y)) > 0.75, ])
Y <- rbind(Y[keep_names, ], other = other)

meta <- oral_mouthwash_data$metadata

fit_blmm <- aldex(
  Y,
  ~ treat * timec + (1 | participant_id),
  data = meta,
  method = "blmm",
  n.cores = 1,
  nsample = 32,
  scale = clr.sm,
  gamma = 0
)
#> Warning: blmm: 5 draw(s) across 3 feature(s) were refit with lmerTest because
#> their local covariance updates or inference failed validation. Examples:
#> feature 7: draw 11: boundary objective indistinguishable; draw 14: boundary
#> objective indistinguishable; draw 30: boundary objective indistinguishable;
#> feature 20: draw 2: boundary objective indistinguishable; feature 57: draw 14:
#> boundary objective indistinguishable

head(summary(fit_blmm))
#>                                    parameter         entity   estimate
#> 1                  treatantiseptic-mouthwash g__Haemophilus  2.3487822
#> 2                 treatalcoholfree-mouthwash g__Haemophilus  3.2243681
#> 3                                  treatsoda g__Haemophilus  1.6695833
#> 4                           timec15min-later g__Haemophilus  0.8186471
#> 5                            timec2hrs-later g__Haemophilus  2.3640193
#> 6 treatantiseptic-mouthwash:timec15min-later g__Haemophilus -2.2938022
#>   std.error  p.val.adj
#> 1 0.8220558 0.35946060
#> 2 0.8220558 0.01681809
#> 3 0.8220558 0.91995385
#> 4 0.6372714 1.00000000
#> 5 0.6372714 0.04224706
#> 6 0.9012379 0.44460695

In this example, clr.sm centers the scale model on the scales implied by the centered log-ratio (CLR) transformation, and gamma = 0 adds no scale uncertainty around that center. These choices reproduce a fixed CLR scale assumption; they are not required by the BLMM engine. The example uses 32 draws to keep the vignette fast; use more for a real analysis (see Practical guidance).

Estimates are on the log2-abundance scale, and estimate and std.error are averages over draws of each draw’s estimate and within-fit standard error. You may see a warning that some draws were refit with lmerTest; those draws are included in the results like any other.

Contrasts

Questions that involve more than one coefficient are answered with contrasts. Each row of a contrast matrix tests whether a weighted sum of the fixed-effect coefficients is zero. For example, the difference between antiseptic mouthwash and water two hours after treatment is the antiseptic main effect plus its interaction with the two-hour time point:

coefs <- colnames(model.matrix(~ treat * timec, meta))
C <- matrix(0, 2, length(coefs), dimnames = list(
  c("antiseptic - water at 2h", "antiseptic change by 2h"), coefs
))
C["antiseptic - water at 2h",
  c("treatantiseptic-mouthwash", "treatantiseptic-mouthwash:timec2hrs-later")] <- 1
C["antiseptic change by 2h",
  c("timec2hrs-later", "treatantiseptic-mouthwash:timec2hrs-later")] <- 1

set.seed(42)
fit_contrast <- aldex(
  Y,
  ~ treat * timec + (1 | participant_id),
  data = meta,
  method = "blmm",
  contrasts = C,
  n.cores = 1,
  nsample = 32,
  scale = clr.sm,
  gamma = 0
)
#> Warning: blmm: 5 draw(s) across 3 feature(s) were refit with lmerTest because
#> their local covariance updates or inference failed validation. Examples:
#> feature 7: draw 11: boundary objective indistinguishable; draw 14: boundary
#> objective indistinguishable; draw 30: boundary objective indistinguishable;
#> feature 20: draw 2: boundary objective indistinguishable; feature 57: draw 14:
#> boundary objective indistinguishable

head(summary(fit_contrast, component = "contrasts"))
#>                  parameter                             entity   estimate
#> 1 antiseptic - water at 2h                     g__Haemophilus -0.9956489
#> 2  antiseptic change by 2h                     g__Haemophilus -0.9804118
#> 3 antiseptic - water at 2h                     g__Actinomyces  1.5588305
#> 4  antiseptic change by 2h                     g__Actinomyces -0.2885548
#> 5 antiseptic - water at 2h g__Peptostreptococcaceae_[XI][G-7] -0.3323262
#> 6  antiseptic change by 2h g__Peptostreptococcaceae_[XI][G-7] -0.1117336
#>   std.error p.val.adj
#> 1 0.8220558 1.0000000
#> 2 0.6372714 0.9923661
#> 3 1.1387570 0.9691201
#> 4 0.6378209 1.0000000
#> 5 1.5959667 1.0000000
#> 6 1.3801545 1.0000000

summary() reports coefficients and contrasts together, with a type column to tell them apart; component selects one. Contrast standard errors use the full coefficient covariance, and each contrast gets its own Satterthwaite df.

By default each coefficient and each contrast is its own multiple-testing family across features: p-values are adjusted within each draw with p.adjust.method (BH by default) and then averaged over draws. To adjust several rows as one family, use aldex.p.adjust(), which works from the stored per-draw results without refitting:

joint <- aldex.p.adjust(fit_contrast, groups = rownames(C))
head(summary(joint, component = "contrasts"))
#>                  parameter                             entity   estimate
#> 1 antiseptic - water at 2h                     g__Haemophilus -0.9956489
#> 2  antiseptic change by 2h                     g__Haemophilus -0.9804118
#> 3 antiseptic - water at 2h                     g__Actinomyces  1.5588305
#> 4  antiseptic change by 2h                     g__Actinomyces -0.2885548
#> 5 antiseptic - water at 2h g__Peptostreptococcaceae_[XI][G-7] -0.3323262
#> 6  antiseptic change by 2h g__Peptostreptococcaceae_[XI][G-7] -0.1117336
#>   std.error p.val.adj
#> 1 0.8220558 1.0000000
#> 2 0.6372714 1.0000000
#> 3 1.1387570 0.9988702
#> 4 0.6378209 1.0000000
#> 5 1.5959667 1.0000000
#> 6 1.3801545 1.0000000

Example comparison: lme4 versus blmm

On a small subset of the oral_mouthwash_data features, the code below fits the same model with both engines and compares the posterior mean coefficients and their standard errors.

set.seed(42)
data("oral_mouthwash_data", package = "ALDEx3")

Y0 <- oral_mouthwash_data$counts
keep_names <- row.names(Y0[((rowSums(Y0 == 0)) / ncol(Y0)) <= 0.75, ])
other <- colSums(Y0[((rowSums(Y0 == 0)) / ncol(Y0)) > 0.75, ])
Y <- rbind(Y0[keep_names, ], other = other)

# Keep a small subset to make the comparison easy to inspect in the vignette.
Y <- Y[c(seq_len(min(8, nrow(Y) - 1)), nrow(Y)), ]
meta <- oral_mouthwash_data$metadata

K <- 1

fit_args <- list(
  data = meta,
  n.cores = 1,
  nsample = 16,
  scale = clr.sm,
  gamma = 0
)

fit_model <- function(method) {
  suppressWarnings(do.call(
    aldex,
    c(
      list(Y, ~ treat * timec + (1 | participant_id)),
      fit_args,
      list(method = method)
    )
  ))
}

set.seed(42)
fit_lme4 <- fit_model("lme4")

set.seed(42)
fit_blmm <- fit_model("blmm")

time_lme4 <- replicate(K, {
  set.seed(42)
  system.time({
    invisible(fit_model("lme4"))
  })[["elapsed"]]
})

time_blmm <- replicate(K, {
  set.seed(42)
  system.time({
    invisible(fit_model("blmm"))
  })[["elapsed"]]
})

s_lme4 <- summary(fit_lme4)
s_blmm <- summary(fit_blmm)

cmp <- merge(
  s_lme4,
  s_blmm,
  by = c("parameter", "entity"),
  suffixes = c(".lme4", ".blmm")
)

cmp$abs_est_diff <- abs(cmp$estimate.lme4 - cmp$estimate.blmm)
cmp$abs_se_diff <- abs(cmp$std.error.lme4 - cmp$std.error.blmm)

cmp_tbl <- cmp[order(cmp$abs_est_diff, decreasing = TRUE), ][1:8, c(
  "parameter", "entity",
  "estimate.lme4", "estimate.blmm", "abs_est_diff",
  "std.error.lme4", "std.error.blmm", "abs_se_diff"
)]

cat('<div style="overflow-x:auto; width:100%;">\n')
knitr::kable(
  cmp_tbl,
  format = "html",
  digits = 4,
  row.names = FALSE,
  caption = "Largest absolute differences between lme4 and blmm on the shared-draw subset."
)
Largest absolute differences between lme4 and blmm on the shared-draw subset.
parameter entity estimate.lme4 estimate.blmm abs_est_diff std.error.lme4 std.error.blmm abs_se_diff
treatalcoholfree-mouthwash:timec15min-later g__Treponema -0.9707 -0.9707 0 2.3296 2.3296 0
treatalcoholfree-mouthwash:timec15min-later g_Lachnospiraceae[G-3] 0.7208 0.7208 0 2.3903 2.3903 0
treatsoda:timec2hrs-later other -1.0886 -1.0886 0 1.4234 1.4234 0
treatsoda:timec2hrs-later g__Treponema -0.8690 -0.8690 0 2.2612 2.2611 0
treatsoda:timec2hrs-later g_Lachnospiraceae[G-3] 1.0390 1.0390 0 2.3156 2.3156 0
treatsoda:timec2hrs-later g__Tannerella -0.7981 -0.7981 0 1.6934 1.6934 0
treatsoda:timec2hrs-later g_Peptostreptococcaceae[XI][G-7] 0.9976 0.9976 0 1.7979 1.7979 0
treatalcoholfree-mouthwash:timec15min-later other 1.9028 1.9028 0 1.4748 1.4748 0
cat('\n</div>\n')

runtime_tbl <- data.frame(
  engine = c("lme4", "blmm"),
  mean_elapsed_sec = c(mean(time_lme4), mean(time_blmm)),
  median_elapsed_sec = c(median(time_lme4), median(time_blmm)),
  speedup_vs_lme4 = c(1, mean(time_lme4) / mean(time_blmm))
)

cat('\n\n')
cat('<div style="overflow-x:auto; width:100%;">\n')
knitr::kable(
  runtime_tbl,
  format = "html",
  digits = 3,
  caption = paste0(
    "Elapsed runtime on the shared-draw vignette subset averaged over K = ",
    K,
    " timing run(s). Times will vary by hardware."
  )
)
Elapsed runtime on the shared-draw vignette subset averaged over K = 1 timing run(s). Times will vary by hardware.
engine mean_elapsed_sec median_elapsed_sec speedup_vs_lme4
lme4 6.115 6.115 1.000
blmm 0.697 0.697 8.773
cat('\n</div>\n')

For an engine comparison to be meaningful, both fits must use the same Monte Carlo draws. The repeated set.seed(42) above ensures that. Without it, the comparison would mix engine differences with differences in the draws themselves.

With identical draws on this subset, the maximum absolute difference in posterior-mean coefficients was 1.4e-06, and the maximum absolute difference in standard errors was 1.7e-06. blmm was approximately 8.8 times as fast as lme4 on this subset. The next section gives timings for the full dataset.

Runtime scaling

Runtime is driven by three quantities:

  • N, the number of samples,
  • D, the number of features, and
  • S, the number of Monte Carlo draws.

All engines pay the shared cost of generating and transforming the Monte Carlo draws, which scales roughly with D * N * S. The difference is in the mixed model fit.

lme4 performs a full variance-component optimization for every feature and every draw, so its expensive nonlinear step scales roughly like D * S * cost(full_REML_fit(N, random_effect_structure)). Each full fit starts from a generic starting value and runs to convergence.

blmm replaces those repeated optimizations with one anchor fit per feature, which handles all draws in a single batched computation, followed by a few Newton steps per draw that start close to the answer. Its cost is closer to D * cost(anchor_fit(N)) + D * S * cost(few_newton_steps(N)), plus a full lmerTest fit for each draw that is refit. The savings are largest when the repeated full optimization is the dominant cost.

The table below gives measured times for the full model above on all 62 features of oral_mouthwash_data (81 samples), and for a simulated design with 2,000 samples in 200 groups (6 features, random intercept). Runs used one core on a laptop (Intel Core Ultra 7 165U, R 4.6.1) with identical draws for every engine.

Data Draws lme4 Adaptive BLMM (default) Shared-anchor BLMM
oral_mouthwash_data 32 54.6 s 25.3 s 4.1 s
oral_mouthwash_data 128 221.6 s 105.2 s 16.2 s
Simulated, \(N = 2000\) 32 6.6 s 2.5 s 0.7 s

On these data the adaptive default is two to three times faster than lme4 and reproduces its results to numerical precision: on oral_mouthwash_data the largest difference in any estimate, standard error or adjusted p-value was below \(5\times10^{-6}\). Shared-anchor inference is several times faster again, but its adjusted p-values differed from lme4 by up to 0.025. Times will differ with hardware, model and data.

In practice, BLMM is most valuable when:

  1. S is moderate to large, so repeated full REML fits become expensive;
  2. D is large, so the same model structure is reused across many features;
  3. the random-effects structure is nontrivial, so each full fit is expensive;
  4. few draws need to be refit.

BLMM is less compelling when S is very small, when the dataset is so small that full fitting is already cheap, or when most draws end up being refit.

The n.cores argument distributes features across workers; the draws of one feature are processed in sequence. Parallelism and BLMM therefore reduce different parts of the runtime and their gains combine.

Practical guidance

Refit warnings. A warning that some draws were refit with lmerTest means those draws did not pass BLMM’s numerical checks; their full fits are used in the results. A refit costs time, not accuracy. Frequent refits usually mean covariance estimates close to (but not exactly at) zero, very few groups, or a random-effects structure the data barely support. If most draws are refit, consider simplifying the random effects or using method = "lme4" directly. Warnings from lmerTest itself, such as convergence warnings, still need the usual attention.

Number of draws. Reported p-values are averages over draws, so they carry Monte Carlo error. For a final analysis use hundreds to thousands of draws, and check stability by rerunning with a different seed. More draws reduce Monte Carlo error; they do not add biological replicates or correct a misspecified model.

Memory and streaming. Each worker needs its own memory, so more workers is not free. streamsize (default 8000) splits large jobs into chunks of draws; streaming starts when \(8NDS/10^5\) exceeds streamsize, so the default corresponds to about 800 MB of response draws. Each chunk gets its own anchor, so changing streamsize can change BLMM results slightly. streamsize = Inf disables streaming. BLMM chooses between dense and sparse linear algebra automatically.

Choosing an engine. Use method = "lme4" to fit every draw fully, for example as a check on a small analysis. Use method = "nlme" when you need residual correlation structures such as AR(1) (via correlation = ...), which BLMM does not support.

Other inference options

method Default when test is omitted Other supported test values
"blmm" "t.satterthwaite.adaptive" "t.satterthwaite", "t.residual" (deprecated)
"lme4" "t" (lmerTest Satterthwaite) None
"nlme" "t" (native nlme inference) None
"lm" "t.HC3" "t", "t.HC0"

Shared-anchor inference, test = "t.satterthwaite". This was the BLMM default in ALDEx3 1.5.0–1.6.2 and remains available to reproduce those results. Instead of refining each draw, it takes a single Newton step from the anchor using the anchor’s curvature. With \(\bar H = \nabla^2\bar\ell(\bar\theta)\), draw \(s\) gets \[ \tilde\theta_s = \bar\theta + \bar H^{-1}\left\{\nabla\bar\ell(\bar\theta) - \nabla\ell_s(\bar\theta)\right\}, \] which is one Newton step on \(\ell_s\) with the shared Hessian \(\bar H\) in place of the draw’s own. The step is kept only if it does not increase \(\ell_s\) beyond a small tolerance; otherwise the draw is refit with lmerTest. The fixed effects are the exact GLS solution at \(\tilde\theta_s\), and the df use the formula above evaluated with the anchor’s curvature and sensitivities. This selector works in log coordinates for the bounded parameters, so it cannot represent exact zero variances, and it does not center the draws. It is cheaper than the adaptive default but can differ from it materially.

Residual df, test = "t.residual". Deprecated; it warns once per aldex() call. Accepted draws use the residual df \(N - p\), which overstates the available information when there are few groups.

All engines support contrasts. Each contrast is a single-row test of \(c^T\beta = 0\); omnibus tests and nonzero null values are not supported.

Assumptions, validation and limitations

BLMM targets the same Gaussian linear mixed model as lme4 for each feature and draw. It uses lme4::lFormula() to parse the formula and build the random-effects design, so the same syntax works for random intercepts, random slopes, correlated and crossed random effects. Models need a full-rank fixed-effect design.

The test suite compares BLMM draw by draw with full lmerTest fits, including contrasts, for random intercepts (with some variances estimated as zero), correlated random slopes, crossed random effects and uncorrelated slopes, using both the dense and sparse linear algebra. Estimates, standard errors and df agree to within about \(10^{-3}\) relative error. Other tests check the refit paths, boundary handling, and that parallel and serial runs give identical results.

BLMM’s checks are numerical: they confirm that each accepted draw is at a converged REML fit with settled inference, not that the resulting p-values are calibrated. Satterthwaite inference, from BLMM or lmerTest, is itself an approximation and is least reliable with few independent groups or with variance estimates at or near zero. When a conclusion rests on borderline results, examine its sensitivity to the random-effects structure and the scale model.