Package {reintervals}


Title: Confidence, Prediction, Tolerance, and New-Group-Mean Intervals for Linear Mixed Models
Version: 0.2.0
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.
License: MIT + file LICENSE
Encoding: UTF-8
Language: en-US
LazyData: true
Depends: R (≥ 4.1)
Imports: lme4, Matrix, numDeriv, stats, withr (≥ 2.5.0)
Suggests: testthat (≥ 3.0.0), knitr, rmarkdown, pbkrtest
Config/testthat/edition: 3
VignetteBuilder: knitr
URL: https://github.com/percevalsondag/reintervals
BugReports: https://github.com/percevalsondag/reintervals/issues
Config/roxygen2/version: 8.0.0
NeedsCompilation: no
Packaged: 2026-11-02 15:24:42 UTC; percy
Author: Perceval Sondag ORCID iD [aut, cre, cph]
Maintainer: Perceval Sondag <reintervals@gmail.com>
Repository: CRAN
Date/Publication: 2026-11-20 13:00:02 UTC

reintervals: intervals for linear mixed models

Description

Confidence, prediction, tolerance, and new-group-mean (CInew / new-batch-mean) intervals for linear mixed models fitted with lme4::lmer(), returned through one uniform tidy interface. The right interval engine is selected automatically for the fitted model; but it can be changed.

The four interval verbs

ci_lmm()

confidence interval for the mean.

pi_lmm()

prediction interval for a future observation.

ti_lmm()

tolerance interval (content P); over = "group_mean" gives the batch-mean tolerance interval.

new_group_mean_lmm()

the CInew / new-batch-mean interval (an interval for the true mean of one new group: a new innermost cell, or a new lot at t0).

lmm_predict() is a predict()-style wrapper over the four, selected by ⁠interval =⁠. lmm_interval_control() supplies the GPQ tuning (seed, M) and the confidence-interval df rule (ci_df). Every verb returns the same lmm_interval data frame (see ci_lmm() for the column/attribute contract).

Engine and 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"); design tags in reintervals-models). Engines: "ems-mls" (expected-mean-square / modified large-sample), "anova-mls" (unweighted lot-mean ANOVA: Montes et al. with a fixed slope, Hoffman & Kringle without one), "reml-mls" (REML closed form), "gpq" (generalized pivotal quantity, Monte Carlo).

model / situation CI PI TI new-group mean
random intercept, one-way, intercept only (y ~ 1 + (1 | g)) ems-mls ems-mls anova-mls (Hoffman & Kringle) anova-mls
random intercept, one-way with covariates ems-mls ems-mls ems-mls ems-mls (Gm)
random intercept, nested ems-mls ems-mls ems-mls ems-mls (Gm)
random intercept, crossed with interaction ems-mls ems-mls ems-mls ems-mls (Gv)
random intercept, crossed without interaction or 4+ grouping factors ems-mls ems-mls error error
random intercept + fixed slope, clean balanced ems-mls ems-mls ems-mls anova-mls
random intercept + fixed slope, single-observation / staggered ems-mls (warns with single-observation lots) ems-mls (warns likewise) anova-mls anova-mls
random slope, future-observation, non-singular reml-mls reml-mls reml-mls reml-mls
random slope, singular fit or TI Satterthwaite df unavailable reml-mls reml-mls gpq reml-mls
random slope, batch-mean (over = "group_mean", TI only) --- --- gpq ---

The random-slope tolerance interval switches to GPQ when the fit is singular or, at a given t0, when the closed form's Satterthwaite df for the between-group or residual variance is unavailable (including when the variance-component covariance is not positive definite); the reason is in attr(., "diagnostics")$route_reason. The random-intercept 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 df is unavailable; Kenward-Roger df only on request (lmm_interval_control(ci_df = "kenward-roger")).

One-sided intervals (sides = "lower" / "upper") are available from every verb. CI, PI, and new-group mean keep the two-sided center, variance, and df with ⁠t_{1 - alpha}⁠. One-sided tolerance limits: anova-mls uses Hoffman's (2010) one-sided limit; ems-mls and random-slope models (reml-mls, the default on every fit) use the package's extension of Hoffman's limit to the Francq and REML closed-form bounds, validated by simulation. See reintervals-models.

Scope. General fixed effects are supported for random-intercept models; random-slope models are supported for a single continuous covariate (the stability design). The two tier-2 direct engines ti_anova_raw() and ti_gpq_raw() compute from raw ⁠(y, time, group)⁠ vectors without a fit.

Validation

Every shipped interval is checked against a published or external-source oracle on CI: the Francq, Lin & Hoyer (2019) worked numbers; the Montes-Burdick-Leblond (2019) Appendix A tolerance interval ⁠(57.25, 75.41)⁠; the random-slope intervals against committed reference values to ~1e-9; and the GPQ content variance against the Oliva-Aviles & Hauser (2025) closed form (tau^2 = 8.439).

Author(s)

Maintainer: Perceval Sondag reintervals@gmail.com (ORCID) [copyright holder]

Authors:

See Also

Useful links:


Confidence interval for the mean of a population, from a linear mixed model

Description

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.

Usage

ci_lmm(
  model,
  newdata = NULL,
  alpha = NULL,
  level = NULL,
  sides = c("two.sided", "lower", "upper"),
  method = "auto",
  control = lmm_interval_control()
)

Arguments

model

A fitted lmerMod (from lme4::lmer()).

newdata

Row(s) giving the fixed-effect combination(s) to evaluate at. NULL uses the first model-frame row.

alpha, level

The interval confidence, as a mutually-exclusive pair: give at most one. level is 1 - alpha; the default is alpha = 0.05 (95%).

sides

"two.sided" (default), "lower", or "upper". A one-sided interval keeps the two-sided interval's center, variance, and df and uses ⁠t_{1 - alpha}⁠ in place of ⁠t_{1 - alpha/2}⁠.

method

"auto" (default) chooses the algorithm by structure; one of "ems-mls", "reml-mls", "anova-mls", "gpq" forces that engine and errors if it is incompatible with the model.

control

An lmm_interval_control() object (the GPQ seed and M, and the confidence-interval df rule ci_df).

Value

An lmm_interval object (a data frame), one row per evaluation point, with columns, in order:

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

Known limitation

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.

See Also

pi_lmm(), ti_lmm(), new_group_mean_lmm(), lmm_predict(), reintervals-models.

Examples

fm <- lme4::lmer(Reaction ~ Days + (1 | Subject), data = lme4::sleepstudy)
ci_lmm(fm, newdata = data.frame(Days = 0))

Hoffman & Kringle (2007) Table III assay data

Description

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

Usage

hk_assay

Format

A data frame with 18 rows and 3 columns:

run

analytical run (factor, 6 levels).

replicate

replicate number within run (integer, 1-3).

conc

measured concentration.

Details

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.

Source

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.

References

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

See Also

ti_lmm(), ti_anova_raw(), reintervals-models.

Examples

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 controls for the interval engines

Description

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.

Usage

lmm_interval_control(
  seed = NULL,
  M = 10000L,
  ci_df = c("satterthwaite", "kenward-roger")
)

Arguments

seed

Optional integer seed for the GPQ draws (reproducibility / GxP traceability). NULL uses the ambient RNG state.

M

Number of GPQ Monte-Carlo realizations. Default 10000.

ci_df

Denominator-df rule for the confidence interval (ci_lmm()) on random-intercept models: "satterthwaite" (default; Satterthwaite with the observed-information covariance of the variance components, falling back to the SAS-style containment df — e.g. A - 1 for a one-way or nested design, min(A, B) - 1 for a crossed one — when it is unavailable, as on a singular fit) or "kenward-roger" (requires pbkrtest and errors if it is not installed; never a silent fallback). The df source is reported in attr(., "diagnostics")$df_method. Random-slope models use their own generalized Satterthwaite df and reject "kenward-roger".

Value

An lmm_interval_control list (passed to a verb's control argument); a list with elements seed, M, and ci_df.

See Also

ci_lmm(), ti_lmm(), ti_gpq_raw().

Examples

lmm_interval_control(seed = 1, M = 5000)
lmm_interval_control(ci_df = "kenward-roger")

Unified interface to the four interval verbs

Description

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.

Usage

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

Arguments

model

A fitted lmerMod.

interval

Which interval: "confidence", "prediction", "tolerance", or "new_group_mean".

newdata

Row(s) giving the fixed-effect combination(s); the time column supplies the evaluation point(s). NULL uses the first model-frame row.

P, over

Content proportion and tolerance target; honored only for interval = "tolerance" (forwarded to ti_lmm()). Supplying a non-default P/over with any other interval is an error.

alpha, level

The confidence, as a mutually-exclusive pair: give at most one. level is 1 - alpha; default alpha = 0.05.

sides

"two.sided" (default), "lower", or "upper". One-sided tolerance limits: anova-mls uses Hoffman's (2010) one-sided limit; ems-mls and random-slope models (reml-mls, the default on every fit) use the package's extension of it, validated by simulation. See reintervals-models.

method

"auto" (default) chooses the algorithm by structure; one of "ems-mls", "reml-mls", "anova-mls", "gpq" forces it and errors if incompatible with the model. "anova-mls" is available for fixed-slope models and for intercept-only one-way models (Hoffman-Kringle).

control

lmm_interval_control() tuning (GPQ seed / M).

Value

An lmm_interval object (a data frame), one row per evaluation point, with columns, in order:

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

See Also

ci_lmm(), pi_lmm(), ti_lmm(), new_group_mean_lmm(), reintervals-models.

Examples

fm <- lme4::lmer(Reaction ~ Days + (1 | Subject), data = lme4::sleepstudy)
lmm_predict(fm, interval = "confidence", newdata = data.frame(Days = 0))

Montes-Burdick-Leblond (2019) Appendix A stability data

Description

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.

Usage

mbl_appendix_a

Format

A data frame with 26 rows and 3 columns:

Lot

lot identifier (character), 11 lots A-K.

Month

time since release (numeric, months).

Y

measured response.

Source

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

See Also

ti_anova_raw(), ti_lmm(), reintervals-models.

Examples

fm <- lme4::lmer(Y ~ Month + (1 | Lot), data = mbl_appendix_a)
ti_lmm(fm, newdata = data.frame(Month = 12), P = 0.99)

New-group-mean (CInew / new-batch-mean) interval

Description

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

Usage

new_group_mean_lmm(
  model,
  newdata = NULL,
  alpha = NULL,
  level = NULL,
  sides = c("two.sided", "lower", "upper"),
  method = "auto",
  control = lmm_interval_control()
)

Arguments

model

A fitted lmerMod (from lme4::lmer()).

newdata

Row(s) giving the fixed-effect combination(s) to evaluate at. NULL uses the first model-frame row.

alpha, level

The interval confidence, as a mutually-exclusive pair: give at most one. level is 1 - alpha; the default is alpha = 0.05 (95%).

sides

"two.sided" (default), "lower", or "upper". A one-sided interval keeps the two-sided interval's center, variance, and df and uses ⁠t_{1 - alpha}⁠ in place of ⁠t_{1 - alpha/2}⁠.

method

"auto" (default) chooses the algorithm by structure; one of "ems-mls", "reml-mls", "anova-mls", "gpq" forces that engine and errors if it is incompatible with the model.

control

An lmm_interval_control() object (the GPQ seed and M, and the confidence-interval df rule ci_df).

Value

An lmm_interval object (a data frame), one row per evaluation point, with columns, in order:

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

Target

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.

Constructions

The interval is ⁠center +/- t_df * sqrt(W)⁠, with W, df and the rule reported in attr(., "diagnostics") (W, df, df_rule):

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}⁠.

See Also

ci_lmm(), pi_lmm(), ti_lmm(), lmm_predict(), reintervals-models.

Examples

fm <- lme4::lmer(Reaction ~ Days + (1 + Days | Subject),
                 data = lme4::sleepstudy)
new_group_mean_lmm(fm, newdata = data.frame(Days = 5))

Interval result object

Description

The shallow S3 value returned by the EMS method-pure constructors. It records the point estimate, the two-sided bounds, and the metadata identifying which interval was computed. It is internal plumbing: the user-facing verbs return the unified lmm_interval data frame, not this object.

Usage

new_re_interval(
  estimate,
  lower,
  upper,
  type,
  conf = NA_real_,
  level = NA_real_,
  content = NA_real_,
  df = NA_real_,
  sides = "two",
  target = NA_character_,
  design = "",
  call = NULL
)

Arguments

estimate

Numeric scalar point estimate (lb-hat).

lower, upper

Numeric scalar interval bounds.

type

Character: "CI", "PI", or "TI".

conf

Confidence level (CI: 1 - alpha; TI: gamma). NA if not used.

level

Prediction level (PI: 1 - psi). NA if not used.

content

Content fraction (TI: beta). NA if not used.

df

Degrees of freedom used for the bound (NA for the normal-based TI).

sides

Character: "two", "lower", or "upper".

target

Character target distribution ("observable" / "true_value"), or NA for the CI (which concerns the mean, not a future value).

design

Character naming the random structure, or "".

call

The originating call, or NULL.

Details

Provides print and as.data.frame methods.

Value

An object of class re_interval.


Oliva-Aviles & Hauser (2025) Section 5 DGP specification (GPQ reference)

Description

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.

Usage

oliva_hauser_dgp

Format

A named list:

beta0, beta1

fixed intercept and slope (100, -0.03).

s2_0, s01, s2_1

random intercept variance, intercept-slope covariance, slope variance of V (at kappa = 1).

s2e

residual variance (1).

kappa

the variance ratio (1).

times

the staggered measurement times.

t0

the evaluation time (20).

tau2_at_t0

the closed-form content variance at t0 (8.439388).

citation

the source reference.

Source

Oliva-Aviles C, Hauser P (2025). Technometrics 67(2):193-202 doi:10.1080/00401706.2024.2407324, Section 5.

See Also

ti_gpq_raw(), reintervals-models.

Examples

# the published content-variance functional, reproduced exactly:
oliva_hauser_dgp$tau2_at_t0

Prediction interval for a future observation of a linear mixed model

Description

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

Usage

pi_lmm(
  model,
  newdata = NULL,
  alpha = NULL,
  level = NULL,
  sides = c("two.sided", "lower", "upper"),
  method = "auto",
  control = lmm_interval_control()
)

Arguments

model

A fitted lmerMod (from lme4::lmer()).

newdata

Row(s) giving the fixed-effect combination(s) to evaluate at. NULL uses the first model-frame row.

alpha, level

The interval confidence, as a mutually-exclusive pair: give at most one. level is 1 - alpha; the default is alpha = 0.05 (95%).

sides

"two.sided" (default), "lower", or "upper". A one-sided interval keeps the two-sided interval's center, variance, and df and uses ⁠t_{1 - alpha}⁠ in place of ⁠t_{1 - alpha/2}⁠.

method

"auto" (default) chooses the algorithm by structure; one of "ems-mls", "reml-mls", "anova-mls", "gpq" forces that engine and errors if it is incompatible with the model.

control

An lmm_interval_control() object (the GPQ seed and M, and the confidence-interval df rule ci_df).

Value

An lmm_interval object (a data frame), one row per evaluation point, with columns, in order:

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

Known limitation (few top-level groups)

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

Known limitation

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.

See Also

ci_lmm(), ti_lmm(), new_group_mean_lmm(), lmm_predict(), reintervals-models.

Examples

fm <- lme4::lmer(Reaction ~ Days + (1 | Subject), data = lme4::sleepstudy)
pi_lmm(fm, newdata = data.frame(Days = 0))

Mixed-model classes reintervals computes intervals for

Description

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.

Model classes

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

Random-intercept topology (the 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.

Extrapolation in time (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 (CInew / new-batch-mean)

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

One-sided intervals

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

References

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

See Also

ci_lmm(), pi_lmm(), ti_lmm(), new_group_mean_lmm(), lmm_predict(), ti_anova_raw(), ti_gpq_raw().


ANOVA/MLS tolerance interval from raw data (direct engine, advanced)

Description

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

Usage

ti_anova_raw(
  y,
  time,
  lot,
  t0 = NULL,
  P = 0.95,
  alpha = NULL,
  level = NULL,
  sides = c("two.sided", "lower", "upper")
)

Arguments

y

Numeric response.

time

Numeric time/age covariate (same length as y), or NULL for the one-way (Hoffman-Kringle) interval with no covariate.

lot

Lot/batch (grouping) factor (same length as y).

t0

Time point(s) at which to evaluate the interval; must be NULL (the default) when time = NULL.

P

Content proportion (default 0.95; pharma stability typically 0.99).

alpha, level

Confidence as a mutually-exclusive pair (give at most one); level = 1 - alpha, default alpha = 0.05.

sides

"two.sided" (default), "lower", or "upper" (Hoffman's one-sided limit).

Details

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.

Value

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

References

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

See Also

ti_lmm() (the dispatcher), ti_gpq_raw() (the GPQ raw engine), hk_assay, reintervals-models.

Examples

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)

GPQ tolerance interval from raw data (direct engine, advanced)

Description

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.

Usage

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

Arguments

y

Numeric response.

time

Numeric time/age covariate (same length as y).

batch

Batch factor (same length as y).

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); level = 1 - alpha, default alpha = 0.05.

sides

"two.sided" (default), "lower", or "upper".

c_resid

Residual multiplier c in N(theta, tau2 + c*s2e): 1 (default) a future observation, 0 the batch-mean.

control

lmm_interval_control() tuning (the GPQ seed and M).

Value

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

References

Oliva-Aviles C, Hauser P (2025). Technometrics 67(2):193-202. doi:10.1080/00401706.2024.2407324

See Also

ti_lmm() (the dispatcher), ti_anova_raw() (the ANOVA raw engine), reintervals-models.

Examples

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

Tolerance interval for a linear mixed model

Description

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:

Usage

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

Arguments

model

A fitted lmerMod.

newdata

Row(s) giving the fixed-effect combination(s); the time column supplies the evaluation point(s). NULL uses the first model-frame row.

P

Content proportion (the population fraction covered). Default 0.95 (pharma stability work typically passes P = 0.99).

over

What the interval covers: "observation" (default; a proportion P of future observations — the ordinary tolerance interval) or "group_mean" (a proportion P of new group means — the batch-mean tolerance interval).

alpha, level

The confidence, as a mutually-exclusive pair: give at most one. level is 1 - alpha; default alpha = 0.05.

sides

"two.sided" (default), "lower", or "upper". One-sided tolerance limits: anova-mls uses Hoffman's (2010) one-sided limit; ems-mls and random-slope models (reml-mls, the default on every fit) use the package's extension of it, validated by simulation. See reintervals-models.

method

"auto" (default) chooses the algorithm by structure; one of "ems-mls", "reml-mls", "anova-mls", "gpq" forces it and errors if incompatible with the model. "anova-mls" is available for fixed-slope models and for intercept-only one-way models (Hoffman-Kringle).

control

lmm_interval_control() tuning (GPQ seed / M).

Details

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

Value

An lmm_interval object (a data frame), one row per evaluation point, with columns, in order:

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

Availability

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.

References

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

See Also

ci_lmm(), pi_lmm(), new_group_mean_lmm(), lmm_predict(), reintervals-models.

Examples

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