--- title: "Getting started with reintervals" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Getting started with reintervals} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include = FALSE} knitr::opts_chunk$set(collapse = TRUE, comment = "#>") old <- options(width = 90) library(reintervals) ``` `reintervals` computes four kinds of interval for a linear mixed model fitted with `lme4::lmer()`, through one uniform interface, and returns them in one tidy `lmm_interval` data frame. ## 1. The four interval types --- and when to use each | Verb | Answers | Use when you want... | |---|---|---| | `ci_lmm()` | confidence interval for the **mean** | uncertainty in the average response at a point | | `pi_lmm()` | prediction interval for **one future observation** | where a single new measurement will fall | | `ti_lmm()` | tolerance interval covering a proportion `P` of the **population** | a content/coverage statement (e.g. "99% of units, 95% confident") | | `new_group_mean_lmm()` | the **CInew / new-batch-mean** interval | where the mean of one new, unobserved group/batch will fall | `lmm_predict(model, interval = ...)` is a `predict()`-style wrapper over the four. The engine that computes each interval is chosen automatically from the fitted model; `method = ` can override it only within the engines allowed for that model's design (Section 4). ## 2. The four verbs on a random-intercept model We use `sleepstudy` (reaction time by `Days`, random intercept per `Subject`): ```{r ri-fit} fm <- lme4::lmer(Reaction ~ Days + (1 | Subject), data = lme4::sleepstudy) ci_lmm(fm, newdata = data.frame(Days = 5)) pi_lmm(fm, newdata = data.frame(Days = 5)) ti_lmm(fm, newdata = data.frame(Days = 5), P = 0.99) new_group_mean_lmm(fm, newdata = data.frame(Days = 5)) ``` ### Reading the output Every verb returns the same `lmm_interval` columns: * the **eval-point column(s)**, named by the actual predictor (`Days` here); * `type` (`ci`/`pi`/`ti`/`new_group_mean`), `estimate`, `lower`, `upper`; * `level` (the confidence, `1 - alpha`) and `P` (content proportion --- a value for `ti`, `NA` for the coverage intervals); `sides`; * `method` (the engine that ran) and `design` (the route-independent model class); * the per-row flags `singular`, `boundary`, `vg_floored`. Engine-specific extras (degrees of freedom, GPQ/ANOVA intermediates) live in an attribute, and the random-intercept topology in another: ```{r ri-attrs} ci <- ci_lmm(fm, newdata = data.frame(Days = 5)) str(attr(ci, "diagnostics")) attr(ci, "grouping") ``` ## 3. Stability worked examples that double as validation The next two examples are **not illustrations** --- they are the package reproducing its published validation oracles, live. ### Montes-Burdick-Leblond (2019) Appendix A `mbl_appendix_a` is the committed Appendix A dataset (11 lots, mixing multi-timepoint stability lots with release-only single-observation lots). The published two-sided 99%-content / 95%-confidence tolerance interval at month 12 is **(57.25, 75.41)**: ```{r mbl} head(mbl_appendix_a) fm_mbl <- lme4::lmer(Y ~ Month + (1 | Lot), data = mbl_appendix_a) ti_lmm(fm_mbl, newdata = data.frame(Month = 12), P = 0.99) ``` The dispatcher routes this single-observation design to the unweighted lot-mean ANOVA engine (`method = "anova-mls"`), which reproduces the published number. ### Oliva-Aviles & Hauser (2025) GPQ `oliva_hauser_dgp` is the published Section-5 data-generating specification. The content variance the GPQ method targets at `t0 = 20` has the closed form **`tau^2 = 8.439`**: ```{r gpq-closed} oliva_hauser_dgp$tau2_at_t0 ``` The GPQ engine is Monte Carlo: its `tau^2` estimate (`tau2_med`) is noisy on a single dataset but recovers the closed-form value **in expectation**. Simulating 20 datasets from the published DGP and averaging: ```{r gpq-recovery} d <- oliva_hauser_dgp sim_one <- function(seed, K = 40) { set.seed(seed) Lc <- chol(matrix(c(d$s2_0, d$s01, d$s01, d$s2_1), 2, 2)) do.call(rbind, lapply(seq_len(K), function(k) { a <- as.numeric(crossprod(Lc, rnorm(2))) # batch random effects data.frame(batch = k, time = d$times, y = (d$beta0 + a[1]) + (d$beta1 + a[2]) * d$times + rnorm(length(d$times), 0, sqrt(d$s2e))) })) } tau2_med <- vapply(1:20, function(s) { x <- sim_one(s) g <- ti_gpq_raw(x$y, x$time, x$batch, t0 = 20, P = 0.90, level = 0.95, c_resid = 0, control = lmm_interval_control(seed = s, M = 2000)) attr(g, "diagnostics")$tau2_med }, numeric(1)) c(closed_form = d$tau2_at_t0, mean_gpq_tau2 = mean(tau2_med)) ``` The mean GPQ `tau^2` recovers the published `8.439` (the package's test suite checks both the exact closed form and this expectation on CI). ## 4. The engine / scope map The engine is chosen from the fitted model's structure, and can differ between the verbs (full mapping in `vignette("choosing-an-interval")` and `?reintervals-models`): | Model class | CI / PI | new-group-mean | TI | |---|---|---|---| | random intercept, intercept-only one-way (`y ~ 1 + (1 | g)`) | `ems-mls` | `anova-mls` | `anova-mls` (Hoffman & Kringle 2005) | | random intercept, nested, crossed (with interaction), or one-way with covariates | `ems-mls` | `ems-mls` | `ems-mls` | | random intercept + fixed slope, clean balanced | `ems-mls` | `anova-mls` | `ems-mls` | | random intercept + fixed slope, single-observation / unbalanced | `ems-mls` (warns if any lot has a single observation) | `anova-mls` | `anova-mls` | | random slope, non-singular, future-observation | `reml-mls` | `reml-mls` | `reml-mls` | | random slope, future-observation, singular fit or TI df unavailable | `reml-mls` (flagged `singular`) | `reml-mls` (flagged `singular`) | `gpq` (two-sided TI only; one-sided tolerance intervals stay on `reml-mls`) | | random slope, batch-mean (`over = "group_mean"`, TI only) | --- | --- | `gpq` | The new-group-mean interval targets the true mean of a new innermost cell (a new group, a new B-within-A cell, a new (a, b) cell, or a new lot at `t0`); on fixed-slope and intercept-only one-way designs it uses the unweighted lot-mean (Montes) construction. Only the tolerance interval is re-routed: on a singular random-slope fit the TI moves to `gpq` while CI, PI, and new-group-mean stay on `reml-mls` (flagged `singular`), and it also moves to `gpq` at any `t0` where the closed form's Satterthwaite df for the between-group or residual variance is unavailable; on a single-observation / unbalanced fixed-slope design the TI moves to `anova-mls` while CI and PI stay on `ems-mls` (and warn when a lot has a single observation; see below). The intercept-only one-way TI uses `anova-mls`, the Hoffman & Kringle (2005) interval, balanced or not. On the random-intercept path the confidence interval uses a Satterthwaite df, falling back to the SAS-style containment df (`A - 1` one-way or nested, `min(A, B) - 1` crossed) when that is unavailable; Kenward-Roger df are used only on request (`lmm_interval_control(ci_df = "kenward-roger")`). The df source is in `attr(., "diagnostics")$df_method`. `method = "auto"` (the default) picks the engine in the table. Any other value is accepted only if it is in the allowed set for that model's design and interval; anything else is an error. For CI, PI, and new-group-mean the allowed engine is the one in the table, so there is no alternative. Only the tolerance interval offers a choice: on an intercept-only one-way model, `"anova-mls"` (Hoffman & Kringle, the default) and `"ems-mls"` (Francq et al.) are both allowed; on a fixed-slope model, `"ems-mls"` and `"anova-mls"` are both allowed (forcing `"ems-mls"` on single-observation / unbalanced data takes the anti-conservative path, mainly for comparison); on a random-slope model with the future-observation target, `"reml-mls"` and `"gpq"` are both allowed. Every other design (other random-intercept models without a fixed slope, and the random-slope batch-mean target) has a single allowed TI engine. **Scope:** general fixed effects for random-intercept models; a **single continuous covariate** for random-slope models (the stability design). ### A warning you should understand On a fixed-slope model with single-observation lots, the EMS confidence and prediction intervals can be **anti-conservative (too narrow)**, because REML precision-weighting down-weights the single-observation lots. `ci_lmm()` and `pi_lmm()` **warn** when at least one lot has a single observation (the interval is still returned). Here the warning fires on the MBL data: ```{r c1-warning} ci_lmm(fm_mbl, newdata = data.frame(Month = 12)) ``` The *tolerance* and *new-group-mean* intervals use the unweighted lot-mean (Montes) closed forms on this structure (Section 3) and do not warn; no validated alternative is currently available for the confidence or prediction interval. ## 5. Limitations * **The `vg_floored` flag is a defensive guard you should not normally see.** A valid `lmer` fit has a positive-semidefinite random-effect covariance, so the between-group variance `V_G(t0) = z0' Sigma z0` is non-negative at every `t0`. The floor-and-flag only triggers if a (numerically degenerate) fit drives it below zero; in normal use it stays `FALSE`/`NA`. Do not be alarmed by a guard you will not hit. * **`V_G` is quadratic in the time covariate.** Evaluating a slope interval at a `t0` outside the observed time range extrapolates that quadratic; do it knowingly. There is no guard or warning for extrapolation. ## 6. Where to go next * `?reintervals` --- package overview and the engine/scope map. * `?reintervals-models` --- the model-class to engine mapping and design tags. * `?ci_lmm` --- the full `lmm_interval` output contract (shared by all verbs). * `NEWS.md` --- the change log. ```{r teardown, include = FALSE} options(old) ```