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.
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.
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.
Full fitting minimizes \(\ell_s\) from scratch for every draw. BLMM instead does the following for each feature.
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".
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.
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.
A draw’s refinement is accepted only when two things hold.
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:
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.
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.44460695In 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.
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.0000000summary() 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.0000000lme4 versus blmmOn 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."
)| 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 |
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."
)
)| engine | mean_elapsed_sec | median_elapsed_sec | speedup_vs_lme4 |
|---|---|---|---|
| lme4 | 6.115 | 6.115 | 1.000 |
| blmm | 0.697 | 0.697 | 8.773 |
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 is driven by three quantities:
N, the number of samples,D, the number of features, andS, 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:
S is moderate to large, so repeated full REML fits
become expensive;D is large, so the same model structure is reused
across many features;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.
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.
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.
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.