---
title: "Can I fit and report this model?"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Can I fit and report this model?}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```

Use this page before putting a fitted `drmTMB` model in a manuscript. A
successful fit is not, by itself, permission to report its point estimate or
interval; each route below answers those questions separately and names an
exact fallback.

<details class="drmtmb-notation">
<summary>Terms used on this page</summary>

`mu` is the **location** parameter: the family-specific centre of the response.
`sigma` is **scale**: residual variability. `nu` is **shape**: a feature beyond
location and scale in families such as Student-t. **Coscale** includes residual
correlation `rho12`, the association left between two responses after their
locations and scales are modelled. `sd(group)` is among-group random-effect
variation, not residual `sigma`. `phylo()` and `spatial()` specify phylogenetic
and coordinate-structured random effects. `meta_V(V = V)` supplies known
sampling covariance; `meta_known_V(V = V)` is its deprecated compatibility
alias. This page does not use `tau`, because it is not a general drmTMB
parameter name.

</details>

```{r capability-ledger-summary, echo = FALSE, results = "asis"}
cat(readLines("includes/capability-ledger-summary.md", warn = FALSE), sep = "\n")
```

## Before reporting

Apply the page's evidence boundary literally:

- An inference-ready exact scope permits the point estimate and only the
  specifically named interval.
- A recovery-only scope permits the point estimate, but not a calibrated-
  interval claim.
- A diagnostic-only scope is for feasibility or debugging, not a scientific
  estimate.
- An unsupported scope should not be fitted; use the named fallback.

Before copying a result, run `check_drm(fit)`. Check convergence, the fixed-
effect gradient, and Hessian diagnostics; then inspect `conf.status`,
`profile.boundary`, and any failed bootstrap refits for the interval you plan
to report. A printed interval is not permission to ignore a boundary or failed
refit warning.

## Evidence and exact tested scopes

The sections below retain the technical evidence behind the reader summary.
They use internal evidence tiers, fit labels, and campaign details only to
state the exact boundary of a claim; they do not change a cell's status.

### Capability tiers, defined once

The historical ledger uses the following labels. Reporting permission is not
monotone in that legacy order; use the separate point and interval answers
above.

1. **Supported (legacy ledger label).** This historical label predates the
   current separation of fit maturity from inference maturity. It does not, by
   itself, authorize an interval: use the reader-facing point and named-
   interval permissions above. Census rows carrying this label are
   point-trustworthy in their exact scopes, with interval coverage still
   planned.
2. **Inference-ready with caveats.** The confidence/compatibility interval has
   been coverage-checked by simulation and holds in a named domain. You can
   report the point estimate and interval together with the stated limits.
3. **Interval-feasible.** A real standard-error or interval method is publicly
   available and passes fit-specific numerical checks, but route-specific
   coverage has not yet been established. Use it experimentally and retain the
   warning in interpretation; this is a capability, not a block.
4. **Point-fit recovery.** The point estimate has been checked against a known
   simulated truth and recovers it. The interval has not been
   coverage-checked and should be treated as provisional: report the
   point estimate, and treat any interval on the same row as a plausible
   range rather than a calibrated one.
5. **Diagnostic-only.** A deterministic or single-smoke fit verifies that the
   route is wired to the requested parameter and that its extractors work, but
   no retained-denominator seed ladder supports recovery. Treat the estimate as
   a debugging or feasibility result, not as a recovery-backed scientific
   estimate.
**Not available / rejected by design** is outside the capability ladder:
`drmTMB` refuses to fit the
   request outright. Some of these routes are planned for a later release;
   some are out of scope for the package's current design. Either way,
   fitting it anyway is not an option -- use the alternative named below
   each entry.

The generated census preserves historical statuses while their rows are
audited against this ladder. Read the evidence and caveat columns when a legacy
`supported` label conflicts with an interval or coverage note; the stricter
meaning above is the forward definition.


### Historical capability skim (technical evidence)

This historical skim records the technical routes described below. It is not a
current census: use the generated reader summary above for current counts and
reporting boundaries.

**Historical ledger order:** supported > inference-ready with caveats >
interval-feasible > point-fit recovery > diagnostic-only. This order is kept
for provenance, not as reporting permission; the separate point and interval
answers above are authoritative.

::: {.table-responsive}

| Family / route | Main dpars | Ordinary RE (`mu`) | Structured RE | Highest model-surface evidence |
| --- | --- | --- | --- | --- |
| `gaussian` | `mu`, `sigma` | intercept + independent slope | `phylo` / `spatial` / `animal` / `relmat` (scoped) | supported (exact ordinary-RE cells) |
| `biv_gaussian` | `mu1`, `mu2`, `sigma1`, `sigma2`, `rho12` | matching labelled intercepts / slopes (scoped) | matching structured q2+ (scoped) | supported (exact ordinary-RE cells) |
| `student` | `mu`, `sigma`, `nu` | `mu` intercept + slope | limited spatial / phylo-`nu` gates | interval-feasible |
| `lognormal` | `mu`, `sigma` | `mu` + `sigma` intercept | limited `phylo` / `relmat` on `mu` | inference-ready with caveats (`sigma` RE) |
| `gamma` | `mu`, `sigma` | `mu` + `sigma` intercept | limited `phylo` / `relmat` | inference-ready with caveats (`sigma` RE) |
| `poisson` / `nbinom2` | `mu`, `sigma` (NB2) | `mu` intercept + slope; NB2 `sigma` intercept | q1 structured `mu` (scoped) | inference-ready with caveats (unstructured) |
| `binomial` | `mu` | `mu` intercept + slope | not generally available | inference-ready with caveats under ML; REML diagnostic-only |
| `beta` / `beta_binomial` / `zero_one_beta` | family-specific `mu`/`sigma`/(atoms) | ordinary `mu` gates; atom gates scoped | mostly unavailable / recovery exceptions | inference-ready with caveats (scoped) |
| `tweedie` / `skew_normal` / `cumulative_logit` | family-specific | ordinary `mu` intercept + slope | mostly unavailable | inference-ready with caveats (scoped) |
| zero-inflated / hurdle / truncated counts | `mu`, `sigma`, `zi`/`hu` | limited diagnostic or recovery gates | mostly unavailable | interval-feasible or recovery-only |

:::

**How to read the last column.** "Highest evidence" is the best tier present
for that route on the model surface, not a blanket family claim. Interval
feasibility means a public interval method exists for some cells; it does not
imply coverage. For current counts, open the **Technical ledger snapshot**
above; the long caveat table stays on this page.

### Detailed route evidence

::: {.table-responsive}

| Model / effect | Tier | What you can trust |
| --- | --- | --- |
| Frozen-margin latent-normal association -- all admitted pair classes, plus the Bernoulli x ordinary-NB2 fixed-effect association formula | Interval-feasible | Alpha-scale `vcov()` and Wald `confint()`, plus derived eta standard errors and transformed pointwise intervals, when fit-specific Godambe diagnostics pass; coverage is uncalibrated outside the next row and the method warns accordingly |
| Frozen-margin literal-Bernoulli x ordinary-NB2 intercept association | Inference-ready with caveats | Alpha and derived eta uncertainty in the retained high-information `n = 480` or `960` domain; lower-information fits warn and fail closed if covariance diagnostics do not pass |
| Census-supported ordinary Gaussian `mu` random effects and matching bivariate-Gaussian `mu1`/`mu2` intercepts | Point-trustworthy (census "supported", coverage planned) | Point estimate for the exact supported rows; their intervals are not yet coverage-verified |
| Gaussian `mu` q1 intercept -- `phylo()`, `spatial()`, `relmat()` | Inference-ready | Point estimate and the default location-axis bias-corrected, small-sample-t Wald interval; coverage is mildly conservative in the tested campaigns |
| Gaussian `sigma` q1 one-slope -- `phylo()`, `animal()`, `relmat()` | Inference-ready | Point estimate and raw uncorrected log-SD Wald-z interval; profile is diagnostic-only at `g = 8` |
| Bivariate Gaussian slope-only `mu1:x`/`mu2:x` q2 mean-mean -- `phylo()`, `relmat()` | Inference-ready (default-corrected channel only) | Point estimate and interval from plain `confint(fit)`; intercept-only and explicitly uncorrected Wald intervals are not promoted by this evidence |
| binomial / Poisson / beta / nbinom2 unstructured `mu` | Inference-ready | Point estimate and Wald interval in the tested designs (`n = 50`, `150`, or `500`); this is not a universal sample-size threshold |
| nbinom2 unstructured location-scale (`mu` and `sigma ~ x`) | Inference-ready | Point estimate and Wald interval on both formulas |
| beta unstructured location-scale, interior proportions | Inference-ready | Point estimate and Wald interval; exact 0 or 1 needs `zero_one_beta()` instead |
| Ordinary independent `mu` random slope `(0 + x \| id)` -- binomial, skew-normal, Tweedie, zero-one-beta | Inference-ready with caveats | Profile interval for the natural-scale slope SD under ML only, not `supported`, with no Wald or point-bias claim. The tested floor differs by family, so do not generalize one number: skew-normal / Tweedie / zero-one-beta at `M >= 16` (true SD 0.50, ML-Laplace) and binomial at `M >= 32` (true SD 0.6, ML-Laplace). Zero-one-beta is generator-qualified (see the caveat below) |
| Binomial ordinary `mu` random intercept or independent slope with `REML = TRUE` | Diagnostic-only | The random-effect SD agrees with the overlapping `glmmTMB(REML = TRUE)` route in deterministic Bernoulli and grouped-binomial checks, and drmTMB's uncertainty calculation is finite. Use this only to compare estimator behaviour; it is not recovery- or coverage-backed reporting permission. Fixed-only, multiple-term, correlated, labelled, structured, and missing-response binomial REML routes are unavailable |
| Cumulative-logit ordinary `mu` random slope evaluated with internal AGHQ plus a Cox-Reid adjustment | Internal evidence only; no public fit/report route | The retained campaign is technical evidence about an internal estimator. `drmTMB()` does not expose that estimator, so the campaign does not authorize a cumulative-logit interval or scientific report from a public fitted object. Use the public ML-Laplace route only at its separately documented evidence tier |
| Gamma `sigma` ordinary random intercept `(1 \| id)` | Inference-ready with caveats | ML-Laplace profile interval only for the exact iid, uncentred coverage fixture (true SD 0.40, 12 observations/group, `M = 32` or `64`); `M = 16` is borderline and `M = 8` is excluded |
| Poisson / nbinom2 structured `mu` q1 -- `phylo()`, `spatial()`, `animal()`, `relmat()` | Recovery-only | Point estimate only |
| nbinom2 structured `sigma` -- `phylo()`, `spatial()`, `animal()`, `relmat()` | Recovery-only | Point estimate only; scale-targeting bug fixed in 0.4.0 |
| Row-specific recovery slices: beta `animal()` on `mu`/`sigma`, Student-t `mu ~ spatial(1 + x | ...)`, and Gamma `mu ~ relmat()` | Recovery-only | Point estimate only; no interval or coverage promotion |
| Bivariate Gaussian spatial q2 location-intercept REML -- matching labelled `spatial(1 | p | site, coords = coords)` in `mu1` and `mu2` | Recovery-only | Point estimates for both structured SDs and their latent correlation; requires intercept-only `sigma1`, `sigma2`, and `rho12`, complete pairs, unit weights, no known `meta_V()`, and no additional ordinary random, direct-SD, or `corpair()` layer; no interval or coverage promotion |
| Bivariate Gaussian supplied-`K` relmat q2 location-intercept REML -- matching labelled `relmat(1 | p | id, K = K)` in `mu1` and `mu2` | Recovery-only (`point_fit_recovery`) | Point estimates for both structured SDs and their latent relatedness correlation; requires the same named `K`, group ordering, and label in both formulas, intercept-only `sigma1`, `sigma2`, and `rho12`, complete pairs, unit weights, and no additional random-effect, scale-side, `meta_V()`, direct-SD, or `corpair()` layer; no interval or coverage promotion |
| Row-specific single-smoke slices: ordinal `mu ~ phylo()`, truncated-nbinom2 `hu ~ relmat()`, Student-t `nu ~ phylo()`, Student-t intercept-only `mu ~ spatial(1 | ...)`, Poisson slope-only `mu ~ spatial(0 + x | ...)`, Poisson labelled-scalar `mu ~ spatial()`, Poisson `mu ~ spatial(1 | ...) + (1 | id)`, Poisson `zi ~ spatial()`, fixed-`zi` Poisson `mu ~ spatial()`, and fixed-`zi` NB2 `mu ~ spatial()` | Diagnostic-only | Use only to confirm fit/extractor feasibility; no recovery, interval, or coverage claim |
| Structured effects for lognormal, skew-normal, and Tweedie; zero-one-beta routes outside the exact q1 gates | Not generally available | Zero-one-beta has point-recovery q1 intercept gates on `mu` and `sigma` for `phylo()`, `animal()`, `relmat()`, `spatial()`, and `phylo_interaction()`, plus selected q1 `zoi` and `coi` gates. Its `sigma`-`relmat()` and `sigma`-`spatial()` profile targets are interval-feasible, not coverage-calibrated. For other families or structures, use a named admitted route or fixed effects |
| Gaussian pure-`mu` univariate REML -- `spatial()`, `animal()`, `relmat()` | Inference-ready with caveats | Unlabelled intercept or independent intercept plus one numeric slope, with `sigma ~ 1`; report a direct structured-SD profile interval only inside the tested discrete domains below |
| REML outside the admitted Gaussian routes and ordinary binomial `mu` intercept/slope diagnostic | Not available (rejected by design) | Use `REML = FALSE` (maximum likelihood). In particular, fixed-only and structured binomial REML are unavailable |
| `q4`/`q6`/`q8`/`q12` covariance interval promotion; derived-correlation intervals | Not available (planned) | Use the fitted point estimate; try `profile_targets()` for a direct target |

:::

The rest of this page expands each row with the caveat that changes how you
should read it.

### Tier 1: inference-ready

### Gaussian structured random effects: selected anchor cells

Selected structured Gaussian-family random-effect routes are inference-ready
within their recorded scopes. The ML model-surface anchors include univariate
Gaussian `mu` or `sigma` formulas at q1 and bivariate-Gaussian slope-only
`mu1:x`/`mu2:x` q2 mean-mean blocks. The same evidence record also includes
the Arc 1a REML estimator routes for pure-`mu` univariate `spatial()`,
`animal()`, and `relmat()` routes:

- q1 mean-intercept rows -- `phylo()`, `spatial()`, `relmat()` on
  univariate Gaussian `mu`;
- q1 sigma one-slope rows -- `phylo()`, `animal()`, `relmat()` on
  univariate Gaussian `sigma`;
- slope-only q2 mean-mean rows -- `phylo(0 + x | ...)` and
  `relmat(0 + x | ...)` on bivariate Gaussian `mu1`/`mu2`, a joint
  cross-response covariance block. The intercept-only bivariate q2 rows are
  not inference-ready. The univariate
  Gaussian single-response q2 mean-slope route is recovery-only, not
  inference-ready;
- Arc 1a REML rows -- `spatial()`, `animal()`, and `relmat()` on
  univariate Gaussian `mu`, restricted to an unlabelled intercept or an
  independent intercept plus one numeric slope with `sigma ~ 1`. Each provider
  is one ledger cell that covers both admitted shapes; the cell count is not a
  count of formula shapes.

The machine ledger records endpoint rows separately for bivariate provider
blocks. That storage detail does not create additional scientific covariance
blocks.

Each route has a caveat, and the caveat is different for
each group. The q1 `mu` intercept rows are backed by the default
location-axis bias-corrected, small-sample-t Wald channel, with coverage of
0.9705-0.9832 in the retained-denominator campaigns. The q1
`sigma` one-slope rows are backed by raw, uncorrected log-SD Wald-z intervals:
intercept-SD coverage is 0.9388-0.9633 and slope-SD coverage is
0.9895-0.9957 at `g = 8`, with material miss asymmetry for some intercept
targets. Profile intervals for these q1 `sigma` rows are diagnostic-only at
`g = 8` because their finite-interval rates do not clear the promotion gate.
These are the documented small-sample limitations; do not replace either
evidence channel with a general profile recommendation.

The Arc 1a REML cells are coverage-backed only over discrete campaign
domains. Here `M` is the number of structured levels (sites, animals, or
relatedness levels, and therefore the structured matrix dimension), while
`n_each` is the number of observations per structured level. Spatial and
`relmat()` use `n_each = 20` and exactly `M = {8, 16, 32}`, while the
`animal(A = A)` campaign uses `n_each = 20` and one fixed `M = 8` matrix.
Coverage clears the pre-specified small-sample floors but is not nominal-exact;
upper-tail miss asymmetry and zero-lower-bound slope profiles remain material.
Do not rewrite these as continuous `M >= ...` claims or treat other pedigrees,
matrices, or sample sizes as coverage-checked.

These are copy-paste forms of the three admitted independent one-slope REML
cells (replace the object names with objects from your analysis):

```r
fit_spatial_reml <- drmTMB(
  bf(y ~ x + spatial(1 + x | site, coords = coords), sigma ~ 1),
  family = gaussian(), data = dat, REML = TRUE
)
fit_animal_reml <- drmTMB(
  bf(y ~ x + animal(1 + x | id, A = A), sigma ~ 1),
  family = gaussian(), data = dat, REML = TRUE
)
fit_relmat_reml <- drmTMB(
  bf(y ~ x + relmat(1 + x | id, K = K), sigma ~ 1),
  family = gaussian(), data = dat, REML = TRUE
)
```

The multi-seed campaigns used exactly the coordinate, `A`, and `K`
representations shown above. Pedigree and `Ainv` animal inputs and relmat `Q`
have deterministic representation-parity evidence only; they do not inherit
the multi-seed campaign claim. Intercept-only versions replace `1 + x` with
`1`; slope-only, labelled, and multiple-slope shapes remain rejected.

For every admitted Arc 1a term, the fitted structured SD scale `s_j` is the
latent-field scale: the covariance is `s_j^2 K_h`, and node `i` has marginal
SD `s_j sqrt(K_h[ii])`. The fitted `s_j` is therefore equal to a node marginal
SD only when the corresponding diagonal entry of `K_h` is one.

The bivariate-Gaussian slope-only q2 mean-mean rows are inference-ready only
because `confint()`'s defaults already correct for known small-sample bias
on location-axis structured-SD targets: `bias_correct = "location"` shifts the log-scale
point estimate to counter ML shrinkage, and `small_sample_df = "location"`
widens the interval with a `t(df = g - 1)` reference instead of a normal
quantile. Calling plain `confint(fit)` gives you this corrected interval
automatically. If you explicitly turn the correction off
(`bias_correct = "none"`, `small_sample_df = "none"`), the resulting raw
Wald interval under-covers on these rows -- do not do that for a
bivariate `phylo()`/`relmat()` q2 mean-mean report.

None of these structured cells carries the legacy `supported` evidence tier
the census reserves for the package's ordinary (unstructured) Gaussian and
bivariate-Gaussian random effects -- and even those supported cells are
point-trustworthy with interval coverage still planned, not
coverage-verified. Report these structured intervals as inference-ready, not
as a fully mature fixed-effect-grade interval.

### Ordinary (unstructured) random effects: point-trustworthy, coverage pending

A group of cells deserves explicit mention even though its interval does
not yet meet the coverage bar for this tier. The census-supported rows are
the Gaussian `mu` random intercept, its independent `(0 + x | id)` slope,
and the matching bivariate-Gaussian `mu1`/`mu2` intercept block. They are
the package's highest fit-maturity random-effect rows, so their point
estimates are the most trustworthy ordinary random-effect estimates
`drmTMB` produces. This does not extend to other bivariate blocks or to an
arbitrary intercept-plus-slope formula. Their interval coverage is still
planned rather than simulation-verified: until that campaign lands, read
any interval on these rows the way you would a recovery-only row below, and
report the point estimate with confidence.

### Unstructured non-Gaussian fixed effects

A retained multi-seed coverage campaign checked the fixed-effect mean
coefficients of `binomial()`, `poisson()`,
`beta()`, and `nbinom2()` across `n` in `{50, 150, 500}`, 400 seeds per
cell. Every cell cleared the bar: finite rate at 1.00 and Wald coverage
between 0.922 and 0.973, with no worsening at the smallest sample size and
no systematic under-coverage. That holds even under stress -- a rare-event
binomial design with an approximately 8% base rate, and a low-count
Poisson design with a mean near 1 -- so a scarce or noisy field dataset is
not, by itself, a reason to distrust these intervals.

The same campaign extended to `nbinom2()` location-scale models, where
both the mean coefficients and the `sigma ~ x` dispersion coefficients are
calibrated (coverage 0.93-0.97 across `n`), and to `beta()` location-scale
models on interior proportions, where mean and `sigma ~ x` coefficients are
also calibrated (coverage 0.93-0.95). The `beta()` result carries one hard
requirement: the family strictly needs responses in the open interval
`(0, 1)`. An observation with an exact 0 or exact 1 -- a boundary
proportion that arises naturally from rounding at extreme covariate
values -- produces a non-finite result by design, not a bug to route
around. If your proportions can legitimately sit at the boundary, fit
`zero_one_beta()` instead of `beta()`.

### Ordinary non-Gaussian random slopes: profile intervals with caveats

The following non-Gaussian families carry an inference-ready-with-caveats interval
for the standard deviation of a single ordinary independent `mu` random slope,
`(0 + x | id)`: binomial, skew-normal, Tweedie, and
zero-one-beta. The claim is narrow and the same in shape across them -- a profile interval for
the *natural-scale* slope SD, ML only, no Wald-interval or point-bias claim --
but the tested floor and design differ by family and should not be generalized
to a single number. Skew-normal, Tweedie, and zero-one-beta are certified at
`M >= 16` groups (true slope SD 0.50) with the standard ML-Laplace profile.
Binomial is certified at `M >= 32` (true SD 0.6).

The retained cumulative-logit campaign used adaptive Gauss-Hermite quadrature
with a Cox-Reid adjustment, but that estimator is package-private and cannot be
requested through `drmTMB()`. The campaign remains useful technical evidence;
it does not grant reporting permission to the public ML-Laplace fit. Do not
report a cumulative-logit random-slope interval on the strength of that
campaign.

Zero-one-beta carries an extra caveat and is **generator-qualified**. Its
coverage campaign was designed with a fixed 15% structural boundary mass and
interior draws from a beta density, but the interior draws leaked rare
machine-exact ones -- 50, 87, and 193 of them across the `M = 16`, `32`, and
`64` replicate banks -- because the sampler's precision parameter pushes the
beta shape toward a boundary in the upper tail. The reported coverage (0.929,
0.940, 0.952 at `M = 16 / 32 / 64`) therefore describes *the generator as
executed*, not an exactly-15%-boundary design. The leak is not independent of
the estimand: affected replicates carry systematically larger slope-SD
estimates, so the effect of the defect under the intended generator is
unquantified and cannot be recovered from the retained campaign. One of the
three independent promotion reviewers withheld this cell on exactly that ground;
it promotes under the frozen two-withhold rule, and the caveat travels with it.
This is a principled boundary, not a temporary one. At the beta shapes where the
leak occurs, the intended distribution genuinely places a large share of its mass
within one machine-precision step of the boundary, so no strictly-interior
sampler can faithfully reproduce the intended design; a rerun would answer a
different, convention-dependent question rather than certify the intended one. The
generator-qualified reading is therefore the correct terminal statement for this
cell.

### Gamma `sigma` random intercept: narrow coverage-backed interval

The Gamma `sigma ~ (1 | id)` random-intercept standard deviation has a separate,
narrower result. Its ML-Laplace profile interval was assessed only in an iid,
uncentred fixture with true SD 0.40 and 12 observations per group. `M = 32` and
`64` groups met the retained coverage rule; `M = 16` is borderline and `M = 8`
is excluded because boundary behaviour made that arm unsuitable for reporting.
This is not evidence for Gamma `sigma` slopes, labelled blocks, joint `mu` and
`sigma` random effects, REML, or other sampling designs.

### Tier 2: recovery-only

A larger set of non-Gaussian structured random-effect routes has verified
point-estimate recovery but no coverage evidence at all. Trust the
coefficient; do not report the interval as calibrated.

This covers Poisson and nbinom2 q1 structured `mu` intercepts and
one-slopes for `phylo()`, `spatial()`, `animal()`, and `relmat()`, and
nbinom2 structured `sigma` for the same four providers. The nbinom2
structured-`sigma` route deserves a specific caution: through 0.3.x, a
`sigma ~ phylo()`/`spatial()`/`animal()`/`relmat()` formula silently
modified the *mean* predictor instead of the scale predictor, so a fitted
model reported a `sigma`-labelled standard deviation that was actually
changing `mu`. That mis-targeting is fixed in 0.4.0, and the route now
correctly modifies scale with verified point-fit recovery -- but intervals
and coverage remain out of scope, so this row stays recovery-only even
after the fix.

Zero-one-beta also has exact q1 structured-intercept gates. Point-recovery
evidence covers `mu` under `phylo()`, `animal()`, `relmat()`, `spatial()`, and
`phylo_interaction()`; `sigma` has the same five point-fit gates. The
`sigma`-`relmat()` and `sigma`-`spatial()` direct profile targets are
interval-feasible, not coverage-calibrated. Selected q1 `zoi` and `coi`
structured intercepts have point-recovery evidence, but several provider
combinations remain unavailable. These exact cells do not extend to slopes,
labels, q2 or larger covariance blocks, simultaneous atom effects, REML, or a
family-wide structured-effect claim.

A further handful of row-specific slices sit at the same tier: beta `animal()`
structured effects on `mu` and on `sigma`, Student-t
`mu ~ spatial(1 + x | ...)`, and Gamma `mu ~ relmat()` (unlabelled intercept
and one-slope). Each of these fits and has point-recovery evidence; none has a
coverage study behind its interval. If your
scientific question turns on the width of a confidence/compatibility
interval rather than the sign and rough size of an effect, do not build
the argument on one of these rows yet.

### Tier 3: diagnostic-only

Some exact structured routes currently have deterministic or single-smoke
fit/extractor evidence without a retained-denominator recovery ladder:
ordinal `mu ~ phylo()`, truncated-nbinom2 `hu ~ relmat()`, Poisson
`zi ~ spatial()`, fixed-`zi` Poisson `mu ~ spatial()`, Student-t
`nu ~ phylo(1 | ...)`, Student-t intercept-only `mu ~ spatial(1 | ...)`,
Poisson slope-only `mu ~ spatial(0 + x | ...)`, Poisson labelled-scalar
`mu ~ spatial()`, Poisson `mu ~ spatial(1 | ...) + (1 | id)`, and fixed-`zi`
NB2 `mu ~ spatial(1 | ...)`. These
routes establish that the parser, likelihood target, and extractors connect.
They do **not** establish point-estimate recovery. Use them for feasibility or
debugging only, and do not report an interval or coverage claim.

### Tier 4: not available or rejected by design

**Structured random effects outside the narrow gates above.** `drmTMB`
does not currently accept structured `phylo()`, `spatial()`, `animal()`,
or `relmat()` random effects for lognormal, skew-normal, or Tweedie families.
Zero-one-beta accepts only the exact q1 structured-intercept cells described
under Tier 2; it does not provide blanket structured support. Gamma is another
partial exception: it accepts
`relmat()` on `mu` (recovery-only, listed under Tier 2 above) but rejects
`phylo()`, `spatial()`, and `animal()`. Try instead: model the same
structural dependence through a Gaussian route (for example a log- or
logit-transformed response under `gaussian()`), fall back to the ordinary
Poisson/nbinom2 structured routes described above for count data, or drop to
fixed effects for the family you need while structured support catches up.

**REML outside its admitted scope.** REML is implemented across a bounded
Gaussian surface and a diagnostic-only ordinary binomial slice. Inside
Gaussian models it accepts a specific boundary rather than every structured
shape. It accepts univariate
phylogenetic mean-side, scale-side, and matched q2 mean-and-scale blocks,
plus univariate spatial, animal, and `relmat()` structured effects on the
scale side, bivariate phylogenetic structured effects in every covariance
layout, and heteroscedastic `sigma ~ x` formulas together with ordinary
(non-phylogenetic) `sigma` random effects. Arc 1a additionally accepts a
pure-`mu`, univariate `spatial()`, `animal()`, or `relmat()` term as an
unlabelled intercept or an independent intercept plus one numeric slope, but
only with constant `sigma ~ 1` and no sigma random effect. Arc 1b-S1 accepts
matching labelled fixed-covariance
`spatial(1 | p | site, coords = coords)` intercepts in bivariate `mu1` and
`mu2`, with intercept-only `sigma1`, `sigma2`, and `rho12`, complete response
pairs, unit weights, no known `meta_V()` covariance, and no additional ordinary
random, direct-SD, or `corpair()` layer, at recovery-only grade. Arc 1b-S2R
admits the analogous location-only supplied-relatedness cell only when both
formulas contain the same labelled `relmat(1 | p | id, K = K)` intercept and
the named `K`, group ordering, and label match exactly. This relmat route has
`point_fit_recovery` evidence: report its two structured SDs and latent
relatedness correlation as point estimates, not calibrated intervals.

The relmat REML exception does not admit `Q = Q`, slopes, q4 or larger blocks,
scale-side terms, extra random effects, incomplete response pairs, non-unit
weights, nonconstant residual formulas, direct-SD models, `meta_V()`, or
`corpair()`. Animal-model bivariate REML remains rejected.

For binomial responses, `REML = TRUE` accepts one ordinary unlabelled `mu`
random intercept or independent slope. That O2 joint-Laplace route is
diagnostic-only: deterministic comparator and uncertainty checks show that it
is wired correctly, but no recovery or coverage campaign authorizes a
scientific estimate. A fixed-only binomial model has no random-effect variance
component for REML to target. Multiple-term, correlated, labelled, structured,
and missing-response binomial REML routes remain unavailable. Every other
non-Gaussian family remains outside the public REML surface. Try instead: fit
the same model with `REML = FALSE` (maximum likelihood); ML is the route to use
for any model REML rejects or for reportable binomial inference.

**Higher-order covariance promotion.** `q4`, `q6`, `q8`, and `q12`
covariance-interval promotion, plus derived-correlation intervals more
broadly for non-Gaussian structured covariance, remain planned rather than
implemented. Try instead: use the fitted point estimate for the
covariance or correlation summary you need, and check
`profile_targets(fit)` for any direct target that already has an interval
route before assuming none exists.

### Known limitations for 0.7.0

If you are deciding whether a specific `drmTMB` output belongs in a
manuscript, read this section next. It names four gaps between what an
extractor currently returns and what the underlying fit actually supports,
and what to do about each one.

**Regression-parameterised coscale intervals are computable, but not
coverage-certified.** If your `rho12` formula depends on a covariate
(`rho12 ~ x`), `corpairs(fit, conf.int = TRUE)` reports
`conf.status = "derived_interval_unavailable"` because its one-row summary
averages a fitted surface. Use `confint(fit, parm = "rho12", newdata = grid,
method = "profile")` for row-specific profile intervals, or
`predict_parameters(fit, newdata = grid, dpar = "rho12", conf.int = TRUE)`
for the corresponding Wald intervals. The same evidence boundary applies to
the constant `rho12 ~ 1` profile interval: it is available, but the current
ledger records no committed bivariate fixed-effect CI-coverage simulation.
Treat either result as an interval-feasibility output, not a calibrated
reporting guarantee. Tracked as issue #802.

**The certified Arc 4c `mu`-slope cells make no point-bias or Wald
claim.** The skew-normal (mc-0464), Tweedie (mc-0539), and zero-one-beta
(mc-0575) cells described under "Ordinary non-Gaussian random slopes" above
come from a coverage campaign whose reporting extractor had a disclosed
defect: it recorded `NA` for the point estimate (`sd_hat`) and every Wald
column, across the whole campaign. The defect is repaired going forward,
but the immutable campaign artifact was not backfilled, so these named
cells carry only the certified ML-Laplace profile interval described above
-- not a point-bias number and not a Wald interval. What to try next: read
and report the profile interval for these cells, and treat any
point-bias or Wald claim about them as unavailable, not merely uncertain.

**Profile-interval endpoints no longer depend on your `iter.max` budget
(issue #710.5).** A previously reported numerical-stability issue -- a
tight `iter.max`/`eval.max` on the profile-endpoint refit could bias a
profile CI inward -- is fixed: the endpoint refit now floors its own
inner-iteration budget regardless of what you pass in, so tightening your
fit's control settings no longer distorts a profile interval. One related
item stays open after 0.7.0, a `sigma`-slope start-value correction (issue
#710.2), but it does not touch the certified profile-CI cells described
above.

**Julia cross-family fitting is deferred.** Legacy Julia-bridge objects may
still be readable for compatibility, but they are not a current analysis route
and do not establish cross-family inference. Their compatibility extractors
return only `u = 0` response-scale means and response residuals for `mu1` /
`mu2`; `vcov()` and fixed-effect Wald intervals explicitly report unavailable
rather than returning an empty value. What to try next: use the native TMB
engine, `drmTMB`'s default, for current supported models. For the bounded
post-0.7 development association route, see the frozen-margin article; it is a
separate staged interface and is not a Julia fit.

### Frozen-margin association intervals

All admitted fixed-effect, complete-pair association classes are
**interval-feasible** for their association-link coefficients `alpha`.
`vcov()` returns the relevant block of the two-stage Godambe covariance and
`confint()` returns alpha-scale Wald intervals whenever the fit-specific
calculation succeeds. This includes the admitted Bernoulli x ordinary-NB2
association-slope formula. Routes without a coverage campaign warn that the
interval is experimental; they are not withheld.

For an intercept-only association, `confint(object, type = "eta")` transforms
the alpha interval to the bounded latent-association scale. For association
regression, `predict(object, newdata = ..., type = "eta", se.fit = TRUE,
interval = "confidence")` supplies pointwise delta-method eta standard errors
and transformed confidence limits. These derived results inherit the alpha
route's evidence tier; they do not add a new coverage or simultaneous-band
claim.

Within that surface, literal-Bernoulli x ordinary-NB2 with
`association = ~ 1` is **inference-ready with caveats**. A 16-cell,
16,000-attempt high-information campaign (`n = 480` or `960`) passed its
predeclared bias, availability, SE-calibration, and coverage gates. This
positive scoped evidence supports the stronger tier; it does not require
unrestricted calibration over every possible dataset.

The earlier lower-information campaign found five primary coverage failures
driven by unavailable intervals. drmTMB therefore warns on lower-information
fits and returns an interval only when the fit-specific covariance diagnostics
pass. It does not manufacture bounds for an unstable or unresolved result.
Simultaneous eta bands, profiles, random effects, missingness, weights,
offsets, and REML remain outside this interval surface.

### Missing data

Missing-data support is a separate axis from the tiers above: it is likelihood
based (missing responses are marginalised, missing predictors are modelled inside
the same likelihood), not multiple imputation and not a posterior. It is
validated against two single-source-of-truth inventories. A positive runtime
test reconciles all currently fitted response routes with the response ledger;
predictor-family tests still require every family outside
`drm_missing_predictor_families()` to reject. Route-specific tests cover
unsupported response neighbours, so an unsupported request is a clear error,
never a silent wrong likelihood. The full worked walkthrough is in
`vignette("missing-data")`.

The response-missingness board below is generated from the response-route ledger
as the capability surface. It distinguishes code admission from completed
validation: a route receives a verified ✓ only at G3 recovery or above.

```{r capability-ledger-missing-response, echo = FALSE, results = "asis"}
cat(
  readLines("includes/capability-ledger-missing-response.md", warn = FALSE),
  sep = "\n"
)
```

Missing-predictor support is a different axis and is not managed by the new
response-missingness ledger:

| Response family | Missing predictor `mi()` (`predictor = "model"`) |
| --- | :---: |
| `gaussian()` | ✓ (broad predictor-model catalogue) |
| `binomial()`, `poisson()`, `nbinom2()`, `beta()` | ✓ (one binary predictor) |
| every other family | — (rejects) |

Two missing-predictor details:

- **Imputation-model catalogue.** When the *response* is a univariate Gaussian
  location model, the *missing predictor* can be modelled with a wide family set —
  Gaussian, Bernoulli/logit, ordered cumulative logit, unordered softmax, beta,
  zero-one beta, beta-binomial (known trials), Poisson, NB2, zero-truncated NB2,
  lognormal, Gamma, and fixed-power Tweedie. The non-Gaussian *responses* above
  currently model **one binary** (Bernoulli/logit) missing predictor each.
- **Structured / multivariate `mi()`.** One intercept-only structured predictor
  model (`phylo()`, `spatial()`, `animal()`, `relmat()`) is available for the
  Gaussian-response `mi()` route only. Multivariate/bivariate missing-predictor
  modelling is not available (that is `gllvmTMB`'s lane).

Not available anywhere yet, and rejected with a family-specific message:
non-binary missing predictors on non-Gaussian responses; multiple missing
predictors; `mi()` with random-effect, structured, or zero-inflated response
terms; response masking combined with `mi()` in the same fit; and EM, profile,
or REML missing-data engines. No fitted response route remains at G0 on the
generated board, but each G3 tick applies only to the route and effect structure
named in its evidence row.

### Full per-family capability map

The table below preserves the original whole-package view alongside the
missing-response board. It shows distributional parameters, fixed and random
effects, structured providers, REML, inference maturity, and both missing-data
axes. Its missing-response column is generated from the response-route ledger.

```{r capability-ledger-family-map, echo = FALSE, results = "asis"}
cat(
  readLines("includes/capability-ledger-family-map.md", warn = FALSE),
  sep = "\n"
)
```

### Choosing an interval method

`confint()`'s default method is Wald (`method = "wald"`), and for most
unstructured fixed-effect rows in Tier 1 that default is already calibrated.
Do not collapse the four structured-anchor evidence channels into one method:
q1 `mu` and the exact phylo/relmat slope-only q2 `mu1:x`/`mu2:x` SD rows use
the default location-axis bias-corrected, small-sample-t Wald channel; q1
`sigma` uses raw uncorrected log-SD Wald-z evidence, with profile
diagnostic-only at `g = 8`; and the Arc 1a REML cells use direct structured-SD
profile evidence only inside their tested discrete domains. Near a boundary,
`profile_targets(fit)` can identify a
direct target worth diagnosing, but that does not promote profile intervals
for a row whose ledger calls them diagnostic-only. When neither an admitted
Wald channel nor an admitted profile channel is available for a target,
`method = "bootstrap"` is the last-resort fallback.

For a structured `sigma` on count data where only the point estimate is
verified, prefer a better-tested alternative when the interval matters to
your conclusion: an ordinary `sigma ~ (1 | id)` random intercept, or a
fixed-effect `sigma ~ predictors` model, both of which carry stronger
evidence than the structured-`sigma` recovery-only routes above.

### Where the exhaustive detail lives

This page is the public reporting summary. Contributors who need to audit a
specific cell should use the repository's internal capability ledger; applied
readers do not need that development material to choose a fitted route. Start
from the generated summary above and use the exact caveat before interpreting
an estimate.