The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

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

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.