| Title: | Confidence, Prediction, Tolerance, and New-Group-Mean Intervals for Linear Mixed Models |
|---|---|
| Description: | Confidence, prediction, tolerance, and new-group-mean (also called CInew or new-batch-mean) intervals for linear mixed models fitted with 'lme4' ('lmerMod' objects), returned through one uniform interface. Several validated interval engines are provided and selected automatically for the fitted model, with a manual override: an expected-mean-square, modified large-sample construction for random-intercept models (Francq, Lin and Hoyer (2019) <doi:10.1002/sim.8386>); a restricted-maximum- likelihood closed form for random-slope models; an unweighted lot-mean analysis-of-variance closed form for unbalanced single-observation fixed-slope stability designs (Montes, Burdick and Leblond (2019) <doi:10.5731/pdajpst.2018.008839>) and, without a covariate, for the one-way random-effects model (Hoffman and Kringle (2005) <doi:10.1081/BIP-200048826>); and a generalized-pivotal-quantity Monte Carlo engine (Oliva-Aviles and Hauser (2025) <doi:10.1080/00401706.2024.2407324>). Intervals are two-sided or one-sided; one-sided tolerance limits follow Hoffman (2010) <doi:10.1198/TECH.2010.09171>. General fixed effects are supported for random-intercept models; random-slope models are supported for a single continuous covariate (the stability design). The methods serve general linear-mixed-model interval estimation, with particular support for pharmaceutical stability and shelf-life work and for bioassay applications through the tolerance and new-group-mean intervals. |
| Authors: | Perceval Sondag [aut, cre, cph] (ORCID: <https://orcid.org/0009-0001-9183-6991>) |
| Maintainer: | Perceval Sondag <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.2.0 |
| Built: | 2026-11-20 21:34:01 UTC |
| Source: | https://github.com/cran/reintervals |
One of the four interval verbs (ci_lmm(), pi_lmm(), ti_lmm(),
new_group_mean_lmm()). ci_lmm() gives a confidence interval for the mean
response at newdata. It dispatches by random structure: random-intercept
designs (including a fixed slope) use the expected-mean-square engine;
random-slope designs use the REML closed form. See reintervals and
vignette("choosing-an-interval") for the engine map, reintervals-models
for the design tags, and lmm_predict() for the unified entry point.
ci_lmm( model, newdata = NULL, alpha = NULL, level = NULL, sides = c("two.sided", "lower", "upper"), method = "auto", control = lmm_interval_control() )ci_lmm( model, newdata = NULL, alpha = NULL, level = NULL, sides = c("two.sided", "lower", "upper"), method = "auto", control = lmm_interval_control() )
model |
A fitted |
newdata |
Row(s) giving the fixed-effect combination(s) to evaluate at.
|
alpha, level
|
The interval confidence, as a mutually-exclusive pair: give
at most one. |
sides |
|
method |
|
control |
An |
An lmm_interval object (a data frame), one row per evaluation point,
with columns, in order:
the eval-point column(s), named by the actual model predictor(s)
(e.g. the time covariate for a slope model, or each newdata column);
type ("ci", "pi", "ti", or "new_group_mean"), estimate,
lower, upper;
level (the confidence, 1 - alpha); P (content proportion —
the value for ti, NA for the coverage intervals); sides;
method (the engine: "ems-mls", "reml-mls", "anova-mls", or
"gpq"); design (the route-independent model class, see
reintervals-models);
the per-row flags singular, boundary, vg_floored.
attr(., "diagnostics") is a list of engine-specific extras (degrees of
freedom df; for the random-intercept confidence interval its source
df_method — "satterthwaite", "containment", or "kenward-roger";
for the random-slope tolerance interval the GPQ route_reason; standard
error se; and any GPQ / ANOVA intermediates);
attr(., "grouping") is the random-intercept topology ("oneway",
"nested", "crossed", or NA for slope models).
On a fixed-slope model with single-observation lots (the release-only
stability structure), 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() emit a
warning when at least one lot has a single observation (the interval is
still returned, unchanged); staggered designs whose lots all have two or more
observations do not warn. The tolerance interval (ti_lmm()) and the
new-group-mean interval (new_group_mean_lmm()) use the unweighted lot-mean
(Montes) closed forms on single-observation and staggered fixed-slope
designs and do not warn; no validated alternative is currently available for
the confidence or prediction interval.
pi_lmm(), ti_lmm(), new_group_mean_lmm(), lmm_predict(),
reintervals-models.
fm <- lme4::lmer(Reaction ~ Days + (1 | Subject), data = lme4::sleepstudy) ci_lmm(fm, newdata = data.frame(Days = 0))fm <- lme4::lmer(Reaction ~ Days + (1 | Subject), data = lme4::sleepstudy) ci_lmm(fm, newdata = data.frame(Days = 0))
The one-way random-effects worked example of Hoffman & Kringle (2007),
Table III (their Example 1): an assay concentration measured in 6 analytical
runs with 3 replicates each. It is the published oracle for the
Hoffman-Kringle (2005) two-sided tolerance interval: with content
P = 0.95 and confidence 0.90, ti_lmm() (default "anova-mls") or
ti_anova_raw() with time = NULL reproduces the published
(0.846, 1.114); with P = 0.667 it reproduces (0.914, 1.046).
hk_assayhk_assay
A data frame with 18 rows and 3 columns:
analytical run (factor, 6 levels).
replicate number within run (integer, 1-3).
measured concentration.
The same data appear in Hoffman & Kringle (2005), Table 6, with run 5 /
replicate 3 misprinted as 1.020. The correct value is 0.998: only it is
consistent with the published mean 0.9798 and mean squares (between
0.003251, within 0.001167). Francq, Lin & Hoyer (2019), Sections 5.2-5.3,
used the misprinted value, which is why their intervals for this example
differ slightly from Hoffman & Kringle's.
Hoffman D, Kringle R (2007). A total error approach for the validation of quantitative analytical methods. Pharmaceutical Research 24(6):1157-1164. doi:10.1007/s11095-007-9242-3. Table III.
Hoffman D, Kringle R (2005). Two-sided tolerance intervals for balanced and unbalanced random effects models. Journal of Biopharmaceutical Statistics 15(2):283-293. doi:10.1081/BIP-200048826
Francq BG, Lin D, Hoyer W (2019). Confidence, prediction, and tolerance in linear mixed models. Statistics in Medicine 38(30):5603-5622. doi:10.1002/sim.8386
ti_lmm(), ti_anova_raw(), reintervals-models.
fm <- lme4::lmer(conc ~ 1 + (1 | run), data = hk_assay) ti_lmm(fm, P = 0.95, level = 0.90) # Hoffman-Kringle: (0.846, 1.114)fm <- lme4::lmer(conc ~ 1 + (1 | run), data = hk_assay) ti_lmm(fm, P = 0.95, level = 0.90) # Hoffman-Kringle: (0.846, 1.114)
Tuning knobs only — the RNG seed and Monte-Carlo size used when the
GPQ algorithm runs, and the denominator-df rule of the random-intercept
confidence interval. Algorithm selection is the method argument, not this.
lmm_interval_control( seed = NULL, M = 10000L, ci_df = c("satterthwaite", "kenward-roger") )lmm_interval_control( seed = NULL, M = 10000L, ci_df = c("satterthwaite", "kenward-roger") )
seed |
Optional integer seed for the GPQ draws (reproducibility / GxP
traceability). |
M |
Number of GPQ Monte-Carlo realizations. Default 10000. |
ci_df |
Denominator-df rule for the confidence interval ( |
An lmm_interval_control list (passed to a verb's control
argument); a list with elements seed, M, and ci_df.
ci_lmm(), ti_lmm(), ti_gpq_raw().
lmm_interval_control(seed = 1, M = 5000) lmm_interval_control(ci_df = "kenward-roger")lmm_interval_control(seed = 1, M = 5000) lmm_interval_control(ci_df = "kenward-roger")
A predict-style wrapper over the four interval verbs (ci_lmm(), pi_lmm(),
ti_lmm(), new_group_mean_lmm()), selected by interval. This is a plain
function, not an S3 method — it does not override lme4's
predict.merMod.
lmm_predict( model, interval = c("confidence", "prediction", "tolerance", "new_group_mean"), newdata = NULL, P = 0.95, over = c("observation", "group_mean"), alpha = NULL, level = NULL, sides = c("two.sided", "lower", "upper"), method = "auto", control = lmm_interval_control() )lmm_predict( model, interval = c("confidence", "prediction", "tolerance", "new_group_mean"), newdata = NULL, P = 0.95, over = c("observation", "group_mean"), alpha = NULL, level = NULL, sides = c("two.sided", "lower", "upper"), method = "auto", control = lmm_interval_control() )
model |
A fitted |
interval |
Which interval: |
newdata |
Row(s) giving the fixed-effect combination(s); the time column
supplies the evaluation point(s). |
P, over
|
Content proportion and tolerance target; honored only for
|
alpha, level
|
The confidence, as a mutually-exclusive pair: give at most
one. |
sides |
|
method |
|
control |
|
An lmm_interval object (a data frame), one row per evaluation point,
with columns, in order:
the eval-point column(s), named by the actual model predictor(s)
(e.g. the time covariate for a slope model, or each newdata column);
type ("ci", "pi", "ti", or "new_group_mean"), estimate,
lower, upper;
level (the confidence, 1 - alpha); P (content proportion —
the value for ti, NA for the coverage intervals); sides;
method (the engine: "ems-mls", "reml-mls", "anova-mls", or
"gpq"); design (the route-independent model class, see
reintervals-models);
the per-row flags singular, boundary, vg_floored.
attr(., "diagnostics") is a list of engine-specific extras (degrees of
freedom df; for the random-intercept confidence interval its source
df_method — "satterthwaite", "containment", or "kenward-roger";
for the random-slope tolerance interval the GPQ route_reason; standard
error se; and any GPQ / ANOVA intermediates);
attr(., "grouping") is the random-intercept topology ("oneway",
"nested", "crossed", or NA for slope models).
ci_lmm(), pi_lmm(), ti_lmm(), new_group_mean_lmm(),
reintervals-models.
fm <- lme4::lmer(Reaction ~ Days + (1 | Subject), data = lme4::sleepstudy) lmm_predict(fm, interval = "confidence", newdata = data.frame(Days = 0))fm <- lme4::lmer(Reaction ~ Days + (1 | Subject), data = lme4::sleepstudy) lmm_predict(fm, interval = "confidence", newdata = data.frame(Days = 0))
The worked-example stability dataset from Montes, Burdick & Leblond (2019),
Appendix A: 11 lots measured over time, mixing genuine multi-timepoint
stability lots (A-D) with release-only single-observation lots (E-K). It is
the published oracle for the random-intercept + fixed-slope tolerance
interval: a two-sided P = 0.99 / gamma = 0.95 interval at Month = 12
reproduces the published (57.25, 75.41) (via ti_anova_raw() or
ti_lmm()); intermediates beta = 0.457, n_E = 6.729, U = 10.820.
mbl_appendix_ambl_appendix_a
A data frame with 26 rows and 3 columns:
lot identifier (character), 11 lots A-K.
time since release (numeric, months).
measured response.
Montes RO, Burdick RK, Leblond DJ (2019). Simple approach to calculate random effects model tolerance intervals to set release and shelf-life specification limits of pharmaceutical products. PDA Journal of Pharmaceutical Science and Technology. doi:10.5731/pdajpst.2018.008839. Appendix A (reproduced from their Table II).
ti_anova_raw(), ti_lmm(), reintervals-models.
fm <- lme4::lmer(Y ~ Month + (1 | Lot), data = mbl_appendix_a) ti_lmm(fm, newdata = data.frame(Month = 12), P = 0.99)fm <- lme4::lmer(Y ~ Month + (1 | Lot), data = mbl_appendix_a) ti_lmm(fm, newdata = data.frame(Month = 12), P = 0.99)
One of the four interval verbs: an interval for the mean of one new,
as-yet-unobserved group/batch (the CInew / new-batch-mean interval). Its
coverage is level/alpha, so it carries no content P (unlike
ti_lmm()).
new_group_mean_lmm( model, newdata = NULL, alpha = NULL, level = NULL, sides = c("two.sided", "lower", "upper"), method = "auto", control = lmm_interval_control() )new_group_mean_lmm( model, newdata = NULL, alpha = NULL, level = NULL, sides = c("two.sided", "lower", "upper"), method = "auto", control = lmm_interval_control() )
model |
A fitted |
newdata |
Row(s) giving the fixed-effect combination(s) to evaluate at.
|
alpha, level
|
The interval confidence, as a mutually-exclusive pair: give
at most one. |
sides |
|
method |
|
control |
An |
An lmm_interval object (a data frame), one row per evaluation point,
with columns, in order:
the eval-point column(s), named by the actual model predictor(s)
(e.g. the time covariate for a slope model, or each newdata column);
type ("ci", "pi", "ti", or "new_group_mean"), estimate,
lower, upper;
level (the confidence, 1 - alpha); P (content proportion —
the value for ti, NA for the coverage intervals); sides;
method (the engine: "ems-mls", "reml-mls", "anova-mls", or
"gpq"); design (the route-independent model class, see
reintervals-models);
the per-row flags singular, boundary, vg_floored.
attr(., "diagnostics") is a list of engine-specific extras (degrees of
freedom df; for the random-intercept confidence interval its source
df_method — "satterthwaite", "containment", or "kenward-roger";
for the random-slope tolerance interval the GPQ route_reason; standard
error se; and any GPQ / ANOVA intermediates);
attr(., "grouping") is the random-intercept topology ("oneway",
"nested", "crossed", or NA for slope models).
The target is the true mean of a new innermost cell: a new group in a
one-way design, a new B-within-A cell in a nested design, a new (a, b) cell
in a crossed design; for the fixed-slope and random-slope designs, the true
mean of a new lot at t0.
The interval is center +/- t_df * sqrt(W), with W, df and the rule
reported in attr(., "diagnostics") (W, df, df_rule):
fixed slope (one grouping factor, any balance): the unweighted
lot-mean (Montes) center Yhat(t0) with
W = S2_L (1 + 1/I) + S2_E (t0 - tbar)^2 / S_tt and a Satterthwaite df
on the two mean squares (df_rule = "anova-satterthwaite", method
"anova-mls");
intercept-only one-way: the unweighted mean of group means with
W = S2_L (1 + 1/I) and df = I - 1 ("anova-single",
"anova-mls");
nested, and one-way with other fixed effects:
W = V_F + sum_j k_j EMS_j over the random terms (REML-implied expected
mean squares, synthesis coefficients when unbalanced) with the top
factor's df A - 1 ("top-factor", "ems-mls");
crossed with interaction: the same W, with a Satterthwaite df in
which V_F is attached to the two main-effect terms
("satterthwaite-vf", "ems-mls");
random slope: the REML closed form
("reml-mls").
A design without a closed-form variance decomposition (two crossed factors
without their interaction term, or four or more grouping factors) is an
error.
One-sided intervals (sides = "lower" / "upper") use the same center, W,
and df with t_{1 - alpha}.
ci_lmm(), pi_lmm(), ti_lmm(), lmm_predict(),
reintervals-models.
fm <- lme4::lmer(Reaction ~ Days + (1 + Days | Subject), data = lme4::sleepstudy) new_group_mean_lmm(fm, newdata = data.frame(Days = 5))fm <- lme4::lmer(Reaction ~ Days + (1 + Days | Subject), data = lme4::sleepstudy) new_group_mean_lmm(fm, newdata = data.frame(Days = 5))
The published data-generating specification for the random-intercept +
random-slope single-temperature stability model of Oliva-Aviles & Hauser
(2025), Section 5, at variance ratio kappa = 1. The paper reports a
simulation / coverage study rather than a single raw dataset, so the
specification (not a dataset) is stored: it makes the closed-form content
variance exactly reproducible and lets reference datasets be simulated
deterministically. The GPQ tolerance interval targets the content variance
tau^2(t0) = z' V z, z = (1, t0); at t0 = 20 this is 8.439388
(the paper's 8.439), reproduced exactly by the engine's V_G machinery.
oliva_hauser_dgpoliva_hauser_dgp
A named list:
fixed intercept and slope (100, -0.03).
random intercept variance, intercept-slope
covariance, slope variance of V (at kappa = 1).
residual variance (1).
the variance ratio (1).
the staggered measurement times.
the evaluation time (20).
the closed-form content variance at t0 (8.439388).
the source reference.
Oliva-Aviles C, Hauser P (2025). Technometrics 67(2):193-202 doi:10.1080/00401706.2024.2407324, Section 5.
ti_gpq_raw(), reintervals-models.
# the published content-variance functional, reproduced exactly: oliva_hauser_dgp$tau2_at_t0# the published content-variance functional, reproduced exactly: oliva_hauser_dgp$tau2_at_t0
One of the four interval verbs (ci_lmm(), pi_lmm(), ti_lmm(),
new_group_mean_lmm()). pi_lmm() gives a prediction interval for one future
observation at newdata. Dispatch and arguments are as for ci_lmm().
pi_lmm( model, newdata = NULL, alpha = NULL, level = NULL, sides = c("two.sided", "lower", "upper"), method = "auto", control = lmm_interval_control() )pi_lmm( model, newdata = NULL, alpha = NULL, level = NULL, sides = c("two.sided", "lower", "upper"), method = "auto", control = lmm_interval_control() )
model |
A fitted |
newdata |
Row(s) giving the fixed-effect combination(s) to evaluate at.
|
alpha, level
|
The interval confidence, as a mutually-exclusive pair: give
at most one. |
sides |
|
method |
|
control |
An |
An lmm_interval object (a data frame), one row per evaluation point,
with columns, in order:
the eval-point column(s), named by the actual model predictor(s)
(e.g. the time covariate for a slope model, or each newdata column);
type ("ci", "pi", "ti", or "new_group_mean"), estimate,
lower, upper;
level (the confidence, 1 - alpha); P (content proportion —
the value for ti, NA for the coverage intervals); sides;
method (the engine: "ems-mls", "reml-mls", "anova-mls", or
"gpq"); design (the route-independent model class, see
reintervals-models);
the per-row flags singular, boundary, vg_floored.
attr(., "diagnostics") is a list of engine-specific extras (degrees of
freedom df; for the random-intercept confidence interval its source
df_method — "satterthwaite", "containment", or "kenward-roger";
for the random-slope tolerance interval the GPQ route_reason; standard
error se; and any GPQ / ANOVA intermediates);
attr(., "grouping") is the random-intercept topology ("oneway",
"nested", "crossed", or NA for slope models).
With few levels of the top random factor (five or fewer) and a dominant between-group variance (an intraclass correlation near 0.9), the Francq et al. (2019) prediction interval used for random-intercept models can under-cover: the worst coverage observed in the package's validation was about 0.93 for a nominal 0.95, consistent with Francq et al. (2019, Fig. 2).
On a fixed-slope model with single-observation lots (the release-only
stability structure), 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() emit a
warning when at least one lot has a single observation (the interval is
still returned, unchanged); staggered designs whose lots all have two or more
observations do not warn. The tolerance interval (ti_lmm()) and the
new-group-mean interval (new_group_mean_lmm()) use the unweighted lot-mean
(Montes) closed forms on single-observation and staggered fixed-slope
designs and do not warn; no validated alternative is currently available for
the confidence or prediction interval.
ci_lmm(), ti_lmm(), new_group_mean_lmm(), lmm_predict(),
reintervals-models.
fm <- lme4::lmer(Reaction ~ Days + (1 | Subject), data = lme4::sleepstudy) pi_lmm(fm, newdata = data.frame(Days = 0))fm <- lme4::lmer(Reaction ~ Days + (1 | Subject), data = lme4::sleepstudy) pi_lmm(fm, newdata = data.frame(Days = 0))
reintervals covers four linear-mixed-model classes: random intercepts
(one-way, nested, or crossed; general fixed effects), a random intercept with
a fixed slope, and a random intercept with a correlated or independent random
slope (single grouping factor, fixed part ~ 1 + time). The interval verbs
(ci_lmm(), pi_lmm(), ti_lmm(), new_group_mean_lmm()) detect the class
from the fitted model and route to the engine that is exact/validated for it
(engine map: reintervals, vignette("choosing-an-interval")); the class is
reported back, route-independently, in the design column of the result.
This page records the mapping from each model definition to its design tag.
| lme4 formula | design tag |
description |
y ~ 1 + (1 | g) (and nested/crossed) |
random_intercept |
random intercept only |
y ~ time + (1 | g) |
random_intercept_fixed_slope |
random intercept with a fixed (population) slope |
y ~ time + (1 + time | g) |
random_slope_correlated |
random intercept and random slope, correlated |
y ~ time + (1 | g) + (0 + time | g) |
random_slope_independent |
random intercept and random slope, independent |
grouping attribute)For random-intercept models (no random slope) the one-way / nested / crossed
topology is reported separately in attr(result, "grouping")
("oneway", "nested", or "crossed"); it is NA for random-slope models.
For the random-slope and fixed-slope models the between-group variance
V_G(t0) = z0' Sigma z0 is quadratic in the time covariate. Evaluating an
interval at a time point outside the observed range therefore extrapolates
that quadratic; the package computes it without a guard or warning, so
out-of-range t0 should be requested knowingly.
new_group_mean_lmm() is the CInew / new-batch-mean interval — a
prediction interval for the mean of one new, as-yet-unobserved group/batch
(the prediction interval with the residual component removed). It is listed
here under both names so it is discoverable as "CInew" or "new batch mean".
Every verb accepts sides = "lower" or "upper".
Confidence, prediction, and new-group-mean intervals: the same center,
variance, and df as the two-sided interval, with t_{1 - alpha} in place
of t_{1 - alpha/2} (all engines).
Tolerance intervals, anova-mls (Hoffman-Kringle one-way and Montes
fixed slope): Hoffman's (2010) one-sided limit
Yhat -/+ (z_P sqrt(U) + z_{1-alpha} sqrt(Vhat(Yhat))), with the same MLS
bound U as the two-sided interval (Montes et al. 2019, Eqs. 2-3, 6-7).
Tolerance intervals, ems-mls (Francq): the same structure with
Francq's MLS bound on the total variance and Vhat = V_F — the
package's extension of Hoffman (2010), validated by simulation.
Tolerance intervals, random slope: Hoffman's structure with the
REML closed form's bound and Vhat = V_F (reml-mls), on every fit
including singular ones — the package's extension of Hoffman (2010),
validated by simulation. method = "gpq" is available but under-covered
near the variance-component boundary in validation.
Hoffman D (2010). One-sided tolerance limits for balanced and unbalanced random effects models. Technometrics 52(3):303-312. doi:10.1198/TECH.2010.09171
ci_lmm(), pi_lmm(), ti_lmm(), new_group_mean_lmm(),
lmm_predict(), ti_anova_raw(), ti_gpq_raw().
Tier-2 direct engine: the published closed-form (ANOVA mean-square / modified
large-sample) tolerance interval from raw vectors, without a fitted lmer
model. Two cases share one estimator (the unweighted lot-mean ANOVA):
ti_anova_raw( y, time, lot, t0 = NULL, P = 0.95, alpha = NULL, level = NULL, sides = c("two.sided", "lower", "upper") )ti_anova_raw( y, time, lot, t0 = NULL, P = 0.95, alpha = NULL, level = NULL, sides = c("two.sided", "lower", "upper") )
y |
Numeric response. |
time |
Numeric time/age covariate (same length as |
lot |
Lot/batch (grouping) factor (same length as |
t0 |
Time point(s) at which to evaluate the interval; must be |
P |
Content proportion (default 0.95; pharma stability typically 0.99). |
alpha, level
|
Confidence as a mutually-exclusive pair (give at most one);
|
sides |
|
With a time covariate (time, t0 given): the Montes, Burdick &
Leblond (2019, Appendix A) interval for the random-intercept + fixed-slope
stability model. ti_lmm() routes single-observation / staggered
fixed-slope designs here automatically.
Without one (time = NULL, t0 = NULL): the Hoffman & Kringle (2005)
two-sided interval for the one-way random-effects model, balanced or
unbalanced (restated in Hoffman & Kringle 2007, Eqs. 1-2). It is the same
computation with the slope removed (residual df N - I, center = the
unweighted mean of the group means). ti_lmm() uses it by default for an
intercept-only model with one random-intercept factor.
One-sided limits (both cases) are Hoffman's (2010) limit
Yhat -/+ (z_P sqrt(U) + z_{1-alpha} sqrt(Vhat(Yhat))), with the same MLS
bound U as the two-sided interval and Vhat(Yhat) the variance of the
center (Montes et al. 2019, Eqs. 2-3 and 6-7).
Method-pure (never touches lme4). The between- and within-lot mean squares
are sums of squares over their degrees of freedom and so are non-negative by
construction; no ANOVA-estimate truncation.
A data frame (one row per t0, or one row when time = NULL):
time (only with a time covariate), type = "TI", estimate, lower,
upper, content, conf, df, sides, design
("random_intercept_fixed_slope", or "random_intercept" when
time = NULL), method = "anova-mls", and singular/boundary flags.
ANOVA intermediates are attached as attributes: n_E, U, Vhat_Y
(Hoffman-Kringle's N_e and sTOT2 when time = NULL), C1, C2
(their H1, H2), and beta_hat (with a time covariate).
Hoffman D (2010). One-sided tolerance limits for balanced and unbalanced random effects models. Technometrics 52(3):303-312. doi:10.1198/TECH.2010.09171
Montes RO, Burdick RK, Leblond DJ (2019). Simple approach to calculate random effects model tolerance intervals to set release and shelf-life specification limits of pharmaceutical products. PDA Journal of Pharmaceutical Science and Technology. doi:10.5731/pdajpst.2018.008839
Hoffman D, Kringle R (2005). Two-sided tolerance intervals for balanced and unbalanced random effects models. Journal of Biopharmaceutical Statistics 15(2):283-293. doi:10.1081/BIP-200048826
Hoffman D, Kringle R (2007). A total error approach for the validation of quantitative analytical methods. Pharmaceutical Research 24(6):1157-1164. doi:10.1007/s11095-007-9242-3
ti_lmm() (the dispatcher), ti_gpq_raw() (the GPQ raw engine),
hk_assay, reintervals-models.
lot <- rep(c("A", "B", "C", "D", "E", "F"), c(6, 5, 2, 5, 2, 1)) ti_anova_raw( y = c(70, 71, 69, 68, 66, 65, 71, 69, 68, 66, 66, 71, 69, 73, 73, 71, 71, 70, 72, 73, 70), time = c(0, 1, 3, 6, 9, 12, 0, 1, 3, 6, 9, 0, 3, 0, 1, 3, 6, 9, 0, 1, 0), lot = lot, t0 = 12, P = 0.99 ) # one-way, no covariate: Hoffman & Kringle (2005), here (0.846, 1.114) ti_anova_raw(hk_assay$conc, time = NULL, lot = hk_assay$run, P = 0.95, level = 0.90)lot <- rep(c("A", "B", "C", "D", "E", "F"), c(6, 5, 2, 5, 2, 1)) ti_anova_raw( y = c(70, 71, 69, 68, 66, 65, 71, 69, 68, 66, 66, 71, 69, 73, 73, 71, 71, 70, 72, 73, 70), time = c(0, 1, 3, 6, 9, 12, 0, 1, 3, 6, 9, 0, 3, 0, 1, 3, 6, 9, 0, 1, 0), lot = lot, t0 = 12, P = 0.99 ) # one-way, no covariate: Hoffman & Kringle (2005), here (0.846, 1.114) ti_anova_raw(hk_assay$conc, time = NULL, lot = hk_assay$run, P = 0.95, level = 0.90)
The Oliva-Aviles & Hauser (2025) generalized-pivotal-
quantity tolerance interval for the random-intercept + random-slope stability
model, from raw (y, time, batch) vectors without a fitted lmer model. The
fit-based dispatcher ti_lmm() routes random-slope designs here automatically
(singular fits, fits whose closed-form Satterthwaite df is unavailable at a
given t0, and the batch-mean target over = "group_mean"); use
ti_gpq_raw() directly when you have data but no model object.
ti_gpq_raw( y, time, batch, t0, P = 0.95, alpha = NULL, level = NULL, sides = c("two.sided", "lower", "upper"), c_resid = 1, control = lmm_interval_control() )ti_gpq_raw( y, time, batch, t0, P = 0.95, alpha = NULL, level = NULL, sides = c("two.sided", "lower", "upper"), c_resid = 1, control = lmm_interval_control() )
y |
Numeric response. |
time |
Numeric time/age covariate (same length as |
batch |
Batch factor (same length as |
t0 |
Time point(s) at which to evaluate the interval. |
P |
Content proportion (default 0.95; pharma stability typically 0.99). |
alpha, level
|
Confidence as a mutually-exclusive pair (give at most one);
|
sides |
|
c_resid |
Residual multiplier |
control |
|
A data frame, one row per t0: method = "gpq", time, estimate,
lower, upper, design = "random_slope_correlated", plus audit fields
(tau2_med, s2e_med, frac_boundary, K, df_resid, phi1).
Oliva-Aviles C, Hauser P (2025). Technometrics 67(2):193-202. doi:10.1080/00401706.2024.2407324
ti_lmm() (the dispatcher), ti_anova_raw() (the ANOVA raw engine),
reintervals-models.
fm <- lme4::lmer(Reaction ~ Days + (1 + Days | Subject), data = lme4::sleepstudy) d <- lme4::sleepstudy ti_gpq_raw(d$Reaction, d$Days, d$Subject, t0 = 5, control = lmm_interval_control(seed = 1, M = 2000))fm <- lme4::lmer(Reaction ~ Days + (1 + Days | Subject), data = lme4::sleepstudy) d <- lme4::sleepstudy ti_gpq_raw(d$Reaction, d$Days, d$Subject, t0 = 5, control = lmm_interval_control(seed = 1, M = 2000))
One of the four interval verbs, and the dispatched tolerance interval. It
classifies the fitted model and routes by random/fixed structure, the
tolerance target (over), the singular flag, and (random slope) whether the
closed form's Satterthwaite df is available, to the engine that is
exact/validated for that case — all transparently:
ti_lmm( model, newdata = NULL, P = 0.95, over = c("observation", "group_mean"), alpha = NULL, level = NULL, sides = c("two.sided", "lower", "upper"), method = "auto", control = lmm_interval_control() )ti_lmm( model, newdata = NULL, P = 0.95, over = c("observation", "group_mean"), alpha = NULL, level = NULL, sides = c("two.sided", "lower", "upper"), method = "auto", control = lmm_interval_control() )
model |
A fitted |
newdata |
Row(s) giving the fixed-effect combination(s); the time column
supplies the evaluation point(s). |
P |
Content proportion (the population fraction covered). Default 0.95
(pharma stability work typically passes |
over |
What the interval covers: |
alpha, level
|
The confidence, as a mutually-exclusive pair: give at most
one. |
sides |
|
method |
|
control |
|
Random slope. over = "observation" uses the REML closed-form MLS
interval when the fit is non-singular and the GPQ interval when the fit is
singular or, at a given t0, when the Satterthwaite df of the closed form's
between-group or residual variance is unavailable (its containment fallback
fired); over = "group_mean" always uses GPQ. One-sided intervals
(sides = "lower" / "upper", future-observation target) use Hoffman's
(2010) one-sided limit on the REML closed form on every fit, singular and
df-unavailable fits included (validated by simulation on all of them);
method = "gpq" remains available, but in the package's validation the
one-sided GPQ limit under-covered on near-boundary singular fits at the
edge of the observed time range (worst cell 0.928 for a nominal 0.95).
The reason is reported per row in attr(., "diagnostics")$route_reason
("none", "singular", "df_unavailable", "group_mean_target", or
"method" when forced).
Random intercept + fixed slope. Clean balanced -> EMS engine; single- observation / staggered / unbalanced -> the Montes ANOVA/MLS closed form.
Intercept-only one-way (y ~ 1 + (1 | g), one grouping factor, no
covariates), balanced or not -> the Hoffman & Kringle (2005) closed form
("anova-mls"). 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.
Any other random-intercept model, no fixed slope (one-way with covariates, nested, crossed) -> EMS engine.
For slope models the between-group variance V_G(t0) is quadratic in the
time covariate, so evaluating at a t0 outside the observed time range is
an extrapolation of that quadratic and should be done knowingly (the interval
is computed without a guard or warning). The same applies to the other slope
verbs (ci_lmm(), pi_lmm(), new_group_mean_lmm()).
An lmm_interval object (a data frame), one row per evaluation point,
with columns, in order:
the eval-point column(s), named by the actual model predictor(s)
(e.g. the time covariate for a slope model, or each newdata column);
type ("ci", "pi", "ti", or "new_group_mean"), estimate,
lower, upper;
level (the confidence, 1 - alpha); P (content proportion —
the value for ti, NA for the coverage intervals); sides;
method (the engine: "ems-mls", "reml-mls", "anova-mls", or
"gpq"); design (the route-independent model class, see
reintervals-models);
the per-row flags singular, boundary, vg_floored.
attr(., "diagnostics") is a list of engine-specific extras (degrees of
freedom df; for the random-intercept confidence interval its source
df_method — "satterthwaite", "containment", or "kenward-roger";
for the random-slope tolerance interval the GPQ route_reason; standard
error se; and any GPQ / ANOVA intermediates);
attr(., "grouping") is the random-intercept topology ("oneway",
"nested", "crossed", or NA for slope models).
Tolerance intervals require a closed-form variance decomposition. They are
available for one-way, nested, and crossed-with-interaction random-intercept
designs, the fixed-slope stability design, and random-slope models. For a
design without such a decomposition (two crossed factors with no interaction
term, or four or more grouping factors), ti_lmm() and
new_group_mean_lmm() signal an error; ci_lmm() and pi_lmm() remain
available for those models.
Hoffman D (2010). One-sided tolerance limits for balanced and unbalanced random effects models. Technometrics 52(3):303-312. doi:10.1198/TECH.2010.09171
Hoffman D, Kringle R (2005). Two-sided tolerance intervals for balanced and unbalanced random effects models. Journal of Biopharmaceutical Statistics 15(2):283-293. doi:10.1081/BIP-200048826
ci_lmm(), pi_lmm(), new_group_mean_lmm(), lmm_predict(),
reintervals-models.
# intercept-only one-way -> Hoffman-Kringle (anova-mls) fh <- lme4::lmer(conc ~ 1 + (1 | run), data = hk_assay) ti_lmm(fh, P = 0.95, level = 0.90) # random intercept + fixed slope (clean balanced) -> EMS engine fi <- lme4::lmer(Reaction ~ Days + (1 | Subject), data = lme4::sleepstudy) ti_lmm(fi, newdata = data.frame(Days = 0)) # random slope, future-observation -> REML closed form fs <- lme4::lmer(Reaction ~ Days + (1 + Days | Subject), data = lme4::sleepstudy) ti_lmm(fs, newdata = data.frame(Days = 5)) # random slope, batch-mean -> GPQ ti_lmm(fs, newdata = data.frame(Days = 5), over = "group_mean", control = lmm_interval_control(seed = 1))# intercept-only one-way -> Hoffman-Kringle (anova-mls) fh <- lme4::lmer(conc ~ 1 + (1 | run), data = hk_assay) ti_lmm(fh, P = 0.95, level = 0.90) # random intercept + fixed slope (clean balanced) -> EMS engine fi <- lme4::lmer(Reaction ~ Days + (1 | Subject), data = lme4::sleepstudy) ti_lmm(fi, newdata = data.frame(Days = 0)) # random slope, future-observation -> REML closed form fs <- lme4::lmer(Reaction ~ Days + (1 + Days | Subject), data = lme4::sleepstudy) ti_lmm(fs, newdata = data.frame(Days = 5)) # random slope, batch-mean -> GPQ ti_lmm(fs, newdata = data.frame(Days = 5), over = "group_mean", control = lmm_interval_control(seed = 1))