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.

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

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.