Choosing an interval

reintervals computes four interval types for a linear mixed model, and picks the computational engine automatically from the fitted model. This vignette is the map: given your model, which intervals are available, which method you get by default, and what to watch for.

library(reintervals)
library(lme4)

The four intervals

Verb Answers
ci_lmm() Confidence interval for the mean.
pi_lmm() Prediction interval for a single future observation.
ti_lmm() Tolerance interval covering a proportion P of the population.
new_group_mean_lmm() Interval for the mean of one new, as-yet-unobserved group (CInew / new-batch-mean).

The four engines

Engine (method) Used for Reference
ems-mls Random-intercept designs and the balanced fixed-slope design (expected-mean-square / observed-information MLS); the new-group-mean interval on nested, crossed, and one-way-with-covariates designs. Francq, Lin & Hoyer (2019)
anova-mls Single-observation / unbalanced fixed-slope (stability) tolerance intervals, and — without a covariate — the intercept-only one-way tolerance interval (unweighted group-mean ANOVA); the new-group-mean interval on every fixed-slope design and on the intercept-only one-way design. Montes, Burdick & Leblond (2019); Hoffman & Kringle (2005)
reml-mls Random-slope closed-form intervals. Graybill–Wang MLS two-component bound (Graybill & Wang 1980); generalized Satterthwaite df
gpq Random-slope batch-mean target, and random-slope tolerance intervals when the fit is singular or the closed form’s Satterthwaite df is unavailable (generalized pivotal quantity, Monte-Carlo). Oliva-Aviles & Hauser (2025)

The engine is chosen automatically from the model’s structure; method = lets you pin it (within what is valid — see below).

Which interval for which model

Read down to your model structure. ems, anova, reml, gpq are the engine tags; superscript letters are explained below. CI_new (new_group_mean_lmm()) targets the true mean of a new innermost cell: a new group (one-way), a new B-within-A cell (nested), a new (a, b) cell (crossed), or a new lot at t0 (fixed and random slope) h.

Model / situation CI PI TI CI_new
Random intercept — one-way, intercept only (y ~ 1 + (1 | g); balanced or unbalanced) ems ems anova g anova h
Random intercept — one-way with covariates (balanced or unbalanced) ems ems ems ems h
Random intercept — nested (balanced or unbalanced) ems ems ems ems
Random intercept — crossed with interaction (balanced/unbalanced; >2 VCs) ems ems ems ems
Random intercept — crossed no interaction ems ems error a error a
Random intercept — ≥4 grouping factors (off-catalog) ems ems error a error a
Random intercept + fixed slope — clean balanced ems ems ems anova h
Random intercept + fixed slope — single-obs / staggered / unbalanced ems b ems b anova c anova h
Random slope — non-singular, future-observation target reml reml reml reml
Random slope — non-singular, batch-mean target (over = "group_mean") — d — d gpq — d
Random slope — singular fit, or TI Satterthwaite df unavailable reml e reml e gpq e reml e
Random slope + ≥2 fixed effects error f error f error f error f

a These designs have no closed-form variance decomposition, so ti_lmm() and new_group_mean_lmm() signal a clear error. CI and PI remain available.

b On fixed-slope data with single-observation lots the EMS confidence and prediction intervals can be anti-conservative (too narrow); ci_lmm() and pi_lmm() emit a warning when at least one lot has a single observation. The interval is returned unchanged. Staggered designs whose lots all have two or more observations do not warn.

c ti_lmm() re-routes to the Montes ANOVA closed form (anova-mls), which is validated for this structure.

d over = "group_mean" (batch-mean) is a ti_lmm() argument only, and the batch-mean tolerance target is random-slope-only in this version. For other designs, new_group_mean_lmm() gives an interval for a new batch’s mean — it is available for random-intercept, fixed-slope, and random-slope models. The coverage verbs carry no batch-mean target.

e For a singular random-slope fit, the tolerance interval switches to the GPQ engine (the closed form’s batch-mean/singular behavior is not validated); CI, PI, and CI_new stay on the closed form, flagged singular. The tolerance interval also switches to GPQ, at a given t0, on a non-singular fit whose Satterthwaite df for the between-group or residual variance is unavailable (the closed form’s containment fallback fired; such fits sit near the variance-component boundary). attr(., "diagnostics")$route_reason reports "singular" or "df_unavailable".

f Random-slope support is limited to a single continuous covariate (~ 1 + x) in this version — time in the stability use case, but any continuous predictor works.

g ti_lmm() uses the Hoffman & Kringle (2005) closed form (anova-mls), the one-way case of the unweighted-means ANOVA interval. method = "ems-mls" gives the Francq et al. (2019) interval instead; the two coincide on balanced data with a non-singular fit and differ on singular or unbalanced data.

h The new-group-mean interval is center ± t_df · sqrt(W). On fixed-slope and intercept-only one-way designs (anova-mls) the center is the unweighted mean of the lot means (at t0 for a fixed slope) and W = S2_L (1 + 1/I) plus, with a slope, S2_E (t0 - tbar)^2 / S_tt, with a Satterthwaite df (I - 1 without a slope). On nested and one-way-with-covariates designs (ems-mls) W = V_F + Σ k_j EMS_j over the random terms with the top factor’s df A - 1; on crossed designs the same W with a Satterthwaite df in which V_F is attached to the two main effects. W, df, and the rule are in attr(., "diagnostics"). The one-way-with-covariates construction has not been validated by simulation.

Confidence-interval degrees of freedom

For random-intercept models (including the fixed-slope design), ci_lmm() uses a Satterthwaite df built from the observed-information covariance of the variance components. When that df is unavailable — typically on a singular fit — it falls back to the SAS-style containment df: A - 1 for one-way and nested designs (one less per between-group fixed effect) and min(A, B) - 1 for crossed designs. Kenward-Roger df are used only on request, control = lmm_interval_control(ci_df = "kenward-roger"), which needs the pbkrtest package and errors if it is not installed, so results never depend on which packages happen to be installed. The df source is reported in attr(., "diagnostics")$df_method. Random-slope models use their own generalized Satterthwaite df.

One-sided intervals

Every verb accepts sides = "lower" or "upper".

Interval One-sided construction Status
CI, PI, new-group mean (all engines) same center, variance, and df as the two-sided interval, with t_{1-alpha} available
TI, anova-mls (Hoffman-Kringle one-way; Montes fixed slope) Hoffman’s (2010) one-sided limit: Yhat ∓ (z_P sqrt(U) + z_{1-alpha} sqrt(Vhat(Yhat))) with the two-sided MLS bound U available (published: Hoffman 2010; Montes et al. 2019)
TI, ems-mls (Francq) the same structure with Francq’s MLS bound on the total variance and Vhat = V_F available (the package’s extension of Hoffman 2010, validated by simulation)
TI, random slope the same structure with the REML closed form’s bound and Vhat = V_F (reml-mls), on every fit including singular ones available (the package’s extension of Hoffman 2010, validated by simulation); method = "gpq" can be forced but under-covered near the variance-component boundary in validation

Choosing the method by hand

By default method = "auto" selects the one engine valid for your model. For most models there is no alternative — requesting a different engine errors. Only three cases offer a genuine choice, all for tolerance intervals:

Worked examples

A random-intercept + fixed-slope model — every verb uses ems-mls:

fm <- lmer(Reaction ~ Days + (1 | Subject), data = 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
#>     5   ci 303.7415 284.6347 322.8483  0.95 NA two.sided    FALSE       NA
#>  vg_floored
#>          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
#>     5   ti 303.7415 142.9097 464.5734  0.95 0.99 two.sided    FALSE       NA
#>  vg_floored
#>          NA

A random-slope model — the verbs use the reml-mls closed form:

fs <- lmer(Reaction ~ Days + (Days | Subject), data = sleepstudy)
ci_lmm(fs, newdata = data.frame(Days = 5))
#> <lmm_interval> ci  (method = reml-mls, design = random_slope_correlated)
#>  Days type estimate    lower    upper level  P     sides singular boundary
#>     5   ci 303.7415 283.5268 323.9563  0.95 NA two.sided    FALSE    FALSE
#>  vg_floored
#>       FALSE
#> diagnostics: df, se  (see attr(., "diagnostics"))

The batch-mean tolerance interval on the same slope model uses GPQ (Monte-Carlo set a seed for reproducibility):

ti_lmm(fs, newdata = data.frame(Days = 5), P = 0.99,
       over = "group_mean",
       control = lmm_interval_control(seed = 1, M = 20000))
#> <lmm_interval> ti  (method = gpq, design = random_slope_correlated)
#>  Days type estimate    lower    upper level    P     sides singular boundary
#>     5   ti 303.7527 154.8042 452.7012  0.95 0.99 two.sided    FALSE       NA
#>  vg_floored
#>          NA
#> diagnostics: df, tau2_med, s2e_med, frac_boundary, K, df_resid, phi1, c_resid, route_reason  (see attr(., "diagnostics"))

Limitations in this version

References