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