reintervals computes four kinds of interval for a linear
mixed model fitted with lme4::lmer(), through one uniform
interface, and returns them in one tidy lmm_interval data
frame.
| Verb | Answers | Use when you want… |
|---|---|---|
ci_lmm() |
confidence interval for the mean | uncertainty in the average response at a point |
pi_lmm() |
prediction interval for one future observation | where a single new measurement will fall |
ti_lmm() |
tolerance interval covering a proportion P of the
population |
a content/coverage statement (e.g. “99% of units, 95% confident”) |
new_group_mean_lmm() |
the CInew / new-batch-mean interval | where the mean of one new, unobserved group/batch will fall |
lmm_predict(model, interval = ...) is a
predict()-style wrapper over the four. The engine that
computes each interval is chosen automatically from the fitted model;
method = can override it only within the engines allowed
for that model’s design (Section 4).
We use sleepstudy (reaction time by Days,
random intercept per Subject):
fm <- lme4::lmer(Reaction ~ Days + (1 | Subject), data = lme4::sleepstudy)
ci_lmm(fm, newdata = data.frame(Days = 5))
#> <lmm_interval> ci (method = ems-mls, design = random_intercept_fixed_slope)
#> Days type estimate lower upper level P sides singular boundary vg_floored
#> 5 ci 303.7415 284.6347 322.8483 0.95 NA two.sided FALSE NA NA
#> diagnostics: df, df_method (see attr(., "diagnostics"))
pi_lmm(fm, newdata = data.frame(Days = 5))
#> <lmm_interval> pi (method = ems-mls, design = random_intercept_fixed_slope)
#> Days type estimate lower upper level P sides singular boundary vg_floored
#> 5 pi 303.7415 204.3995 403.0835 0.95 NA two.sided FALSE NA NA
#> diagnostics: df, df_method (see attr(., "diagnostics"))
ti_lmm(fm, newdata = data.frame(Days = 5), P = 0.99)
#> <lmm_interval> ti (method = ems-mls, design = random_intercept_fixed_slope)
#> Days type estimate lower upper level P sides singular boundary vg_floored
#> 5 ti 303.7415 142.9097 464.5734 0.95 0.99 two.sided FALSE NA NA
new_group_mean_lmm(fm, newdata = data.frame(Days = 5))
#> <lmm_interval> new_group_mean (method = anova-mls, design = random_intercept_fixed_slope)
#> Days type estimate lower upper level P sides singular boundary
#> 5 new_group_mean 303.7415 220.511 386.972 0.95 NA two.sided FALSE NA
#> vg_floored
#> NA
#> diagnostics: df, df_rule, W (see attr(., "diagnostics"))Every verb returns the same lmm_interval columns:
Days here);type
(ci/pi/ti/new_group_mean),
estimate, lower, upper;level (the confidence, 1 - alpha) and
P (content proportion — a value for ti,
NA for the coverage intervals); sides;method (the engine that ran) and design
(the route-independent model class);singular, boundary,
vg_floored.Engine-specific extras (degrees of freedom, GPQ/ANOVA intermediates) live in an attribute, and the random-intercept topology in another:
The next two examples are not illustrations — they are the package reproducing its published validation oracles, live.
mbl_appendix_a is the committed Appendix A dataset (11
lots, mixing multi-timepoint stability lots with release-only
single-observation lots). The published two-sided 99%-content /
95%-confidence tolerance interval at month 12 is (57.25,
75.41):
head(mbl_appendix_a)
#> Lot Month Y
#> 1 A 0 70
#> 2 A 1 71
#> 3 A 3 69
#> 4 A 6 68
#> 5 A 9 66
#> 6 A 12 65
fm_mbl <- lme4::lmer(Y ~ Month + (1 | Lot), data = mbl_appendix_a)
ti_lmm(fm_mbl, newdata = data.frame(Month = 12), P = 0.99)
#> <lmm_interval> ti (method = anova-mls, design = random_intercept_fixed_slope)
#> Month type estimate lower upper level P sides singular boundary vg_floored
#> 12 ti 66.33349 57.25272 75.41425 0.95 0.99 two.sided FALSE FALSE NA
#> diagnostics: df, beta_hat, n_E, U, Vhat_Y, C1, C2 (see attr(., "diagnostics"))The dispatcher routes this single-observation design to the
unweighted lot-mean ANOVA engine (method = "anova-mls"),
which reproduces the published number.
oliva_hauser_dgp is the published Section-5
data-generating specification. The content variance the GPQ method
targets at t0 = 20 has the closed form
tau^2 = 8.439:
The GPQ engine is Monte Carlo: its tau^2 estimate
(tau2_med) is noisy on a single dataset but recovers the
closed-form value in expectation. Simulating 20
datasets from the published DGP and averaging:
d <- oliva_hauser_dgp
sim_one <- function(seed, K = 40) {
set.seed(seed)
Lc <- chol(matrix(c(d$s2_0, d$s01, d$s01, d$s2_1), 2, 2))
do.call(rbind, lapply(seq_len(K), function(k) {
a <- as.numeric(crossprod(Lc, rnorm(2))) # batch random effects
data.frame(batch = k, time = d$times,
y = (d$beta0 + a[1]) + (d$beta1 + a[2]) * d$times +
rnorm(length(d$times), 0, sqrt(d$s2e)))
}))
}
tau2_med <- vapply(1:20, function(s) {
x <- sim_one(s)
g <- ti_gpq_raw(x$y, x$time, x$batch, t0 = 20, P = 0.90, level = 0.95,
c_resid = 0, control = lmm_interval_control(seed = s, M = 2000))
attr(g, "diagnostics")$tau2_med
}, numeric(1))
c(closed_form = d$tau2_at_t0, mean_gpq_tau2 = mean(tau2_med))
#> closed_form mean_gpq_tau2
#> 8.439388 8.371812The mean GPQ tau^2 recovers the published
8.439 (the package’s test suite checks both the exact
closed form and this expectation on CI).
The engine is chosen from the fitted model’s structure, and can
differ between the verbs (full mapping in
vignette("choosing-an-interval") and
?reintervals-models):
| Model class | CI / PI | new-group-mean | TI |
|---|---|---|---|
random intercept, intercept-only one-way
(y ~ 1 + (1 | g)) |
ems-mls |
anova-mls |
anova-mls (Hoffman & Kringle 2005) |
| random intercept, nested, crossed (with interaction), or one-way with covariates | ems-mls |
ems-mls |
ems-mls |
| random intercept + fixed slope, clean balanced | ems-mls |
anova-mls |
ems-mls |
| random intercept + fixed slope, single-observation / unbalanced | ems-mls (warns if any lot has a single
observation) |
anova-mls |
anova-mls |
| random slope, non-singular, future-observation | reml-mls |
reml-mls |
reml-mls |
| random slope, future-observation, singular fit or TI df unavailable | reml-mls (flagged singular) |
reml-mls (flagged singular) |
gpq (two-sided TI only; one-sided tolerance intervals
stay on reml-mls) |
random slope, batch-mean (over = "group_mean", TI
only) |
— | — | gpq |
The new-group-mean interval targets the true mean of a new innermost
cell (a new group, a new B-within-A cell, a new (a, b) cell, or a new
lot at t0); on fixed-slope and intercept-only one-way
designs it uses the unweighted lot-mean (Montes) construction.
Only the tolerance interval is re-routed: on a singular random-slope
fit the TI moves to gpq while CI, PI, and new-group-mean
stay on reml-mls (flagged singular), and it
also moves to gpq at any t0 where the closed
form’s Satterthwaite df for the between-group or residual variance is
unavailable; on a single-observation / unbalanced fixed-slope design the
TI moves to anova-mls while CI and PI stay on
ems-mls (and warn when a lot has a single observation; see
below). The intercept-only one-way TI uses anova-mls, the
Hoffman & Kringle (2005) interval, balanced or not.
On the random-intercept path the confidence interval uses a
Satterthwaite df, falling back to the SAS-style containment df
(A - 1 one-way or nested, min(A, B) - 1
crossed) when that is unavailable; Kenward-Roger df are used only on
request (lmm_interval_control(ci_df = "kenward-roger")).
The df source is in attr(., "diagnostics")$df_method.
method = "auto" (the default) picks the engine in the
table. Any other value is accepted only if it is in the allowed set for
that model’s design and interval; anything else is an error. For CI, PI,
and new-group-mean the allowed engine is the one in the table, so there
is no alternative. Only the tolerance interval offers a choice: on an
intercept-only one-way model, "anova-mls" (Hoffman &
Kringle, the default) and "ems-mls" (Francq et al.) are
both allowed; on a fixed-slope model, "ems-mls" and
"anova-mls" are both allowed (forcing
"ems-mls" on single-observation / unbalanced data takes the
anti-conservative path, mainly for comparison); on a random-slope model
with the future-observation target, "reml-mls" and
"gpq" are both allowed. Every other design (other
random-intercept models without a fixed slope, and the random-slope
batch-mean target) has a single allowed TI engine.
Scope: general fixed effects for random-intercept models; a single continuous covariate for random-slope models (the stability design).
On a fixed-slope model with single-observation lots, the EMS
confidence and prediction intervals can be anti-conservative
(too narrow), because REML precision-weighting down-weights the
single-observation lots. ci_lmm() and pi_lmm()
warn when at least one lot has a single observation
(the interval is still returned). Here the warning fires on the MBL
data:
ci_lmm(fm_mbl, newdata = data.frame(Month = 12))
#> Warning: This is a fixed-slope model with single-observation lots; the EMS CI interval
#> may be anti-conservative (too narrow) on such data, because REML precision-weighting
#> down-weights the single-observation lots. The tolerance and new-group-mean intervals use
#> the unweighted lot-mean (Montes) closed forms on this structure; no validated alternative
#> is currently available for the confidence or prediction interval here.
#> <lmm_interval> ci (method = ems-mls, design = random_intercept_fixed_slope)
#> Month type estimate lower upper level P sides singular boundary vg_floored
#> 12 ci 66.25067 64.60075 67.90059 0.95 NA two.sided FALSE NA NA
#> diagnostics: df, df_method (see attr(., "diagnostics"))The tolerance and new-group-mean intervals use the unweighted lot-mean (Montes) closed forms on this structure (Section 3) and do not warn; no validated alternative is currently available for the confidence or prediction interval.
The vg_floored flag is a defensive guard you
should not normally see. A valid lmer fit has a
positive-semidefinite random-effect covariance, so the between-group
variance V_G(t0) = z0' Sigma z0 is non-negative at every
t0. The floor-and-flag only triggers if a (numerically
degenerate) fit drives it below zero; in normal use it stays
FALSE/NA. Do not be alarmed by a guard you
will not hit.
V_G is quadratic in the time
covariate. Evaluating a slope interval at a t0
outside the observed time range extrapolates that quadratic; do it
knowingly. There is no guard or warning for extrapolation.
?reintervals — package overview and the engine/scope
map.?reintervals-models — the model-class to engine mapping
and design tags.?ci_lmm — the full lmm_interval output
contract (shared by all verbs).NEWS.md — the change log.