Getting started with reintervals

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.

1. The four interval types — and when to use each

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).

2. The four verbs on a random-intercept model

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"))

Reading the output

Every verb returns the same lmm_interval columns:

Engine-specific extras (degrees of freedom, GPQ/ANOVA intermediates) live in an attribute, and the random-intercept topology in another:

ci <- ci_lmm(fm, newdata = data.frame(Days = 5))
str(attr(ci, "diagnostics"))
#> List of 2
#>  $ df       : num 17.1
#>  $ df_method: chr "satterthwaite"
attr(ci, "grouping")
#> [1] "oneway"

3. Stability worked examples that double as validation

The next two examples are not illustrations — they are the package reproducing its published validation oracles, live.

Montes-Burdick-Leblond (2019) Appendix A

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-Aviles & Hauser (2025) GPQ

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:

oliva_hauser_dgp$tau2_at_t0
#> [1] 8.439388

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.371812

The 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).

4. The engine / scope map

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).

A warning you should understand

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.

5. Limitations

6. Where to go next