This map answers one practical question: what model surface can an
applied user fit today, and which neighbouring syntax is still planned?
It is a status ledger rather than a tutorial. Start here when a model
combines random effects, structured dependence, response-specific scale,
zero inflation, hurdle probability, or corpairs().
The words below are used literally. “Fitted” means likelihood code, parser support, extractors or diagnostics, tests, and user-facing documentation are in place. “Planned” means the package may reserve syntax or describe the design, but an analysis should not interpret that surface yet.
| Status word | Meaning |
|---|---|
| Stable | Routine fitted path with tests, diagnostics or interval status, and a reader-facing example or guide. |
| First slice | Fitted and tested inside a deliberately narrow boundary. Stay inside the named family, formula, q, and data-shape limits. |
| Fixed-effect only | Formula coefficients are fitted for this distributional parameter, but random effects or structured dependence for that parameter are not fitted. |
| Planned or reserved | Syntax, roadmap wording, or a parser guard may exist, but
drmTMB() should reject it or treat it as design-only until
likelihood, tests, docs, and after-task evidence land. |
| Unsupported or blocked | Do not use as analysis syntax; choose the nearest fitted route or check the roadmap. |
Location means the expected response (mu,
mu1, mu2). Scale means residual standard
deviation, dispersion, or an equivalent response-family scale
(sigma, sigma1, sigma2). Shape
means a family-specific tail, cutpoint, or overdispersion control such
as Student-t nu. Coscale means the residual correlation
layer, currently rho12 in bivariate Gaussian models.
How to read the project maps
The public site has three maps with different jobs. Use
model-map when the question is “what should I fit?”. Use
this implementation map when the question is “is this surface fitted or
planned?”. Use the source map when the
question is “where are the code, tests, and docs?”. The validation-debt
register is the evidence ledger behind these pages. The roadmap records
sequence and future work; it is not the current-status authority.
When you are closing out a slice from this ledger and need to plot its recovery evidence, see Simulation plot grammar for the shared bias/RMSE/coverage display contract.
Every status row should be read across the same dimensions:
| Dimension | What it records |
|---|---|
| Family or component | Gaussian, Poisson, NB2, ordinal, zi, hu,
shape, known V, or another fitted component. |
| Dependence layer | ordinary group, phylogenetic, coordinate spatial, animal,
relmat(), known sampling covariance, or residual
rho12. |
| Formula route | The public syntax that fits the row, such as
(1 + x | id),
spatial(1 | p | site, coords = coords), or
rho12 ~ x. |
| q or endpoint class | q=1 intercept, independent slope, q=2, q>2, q=4, or future p8/q8 endpoint work. |
| Random-effect scope | Whether random intercepts, random slopes, and cross-parameter or bivariate combinations are fitted, first-slice, planned, or blocked. |
| Extractor route | Which of sdpars, corpars,
ranef(), corpairs(),
summary()$covariance, profile_targets(), and
check_drm() exposes the result. |
| Evidence tier | Whether the surface has smoke evidence, artifact writers, small-grid admission, formal operating-characteristic evidence, or only diagnostic/failure-ledger evidence. |
| Interval tier | Whether intervals are fast Wald, direct profile-ready, profile-proven, direct bootstrap, derived-unavailable, private bootstrap smoke, not requested, or unavailable. |
| User route | What to fit now, and what smaller fitted route to use when the requested model is planned. |
Simulation and interval evidence are deliberately separate from fitted support. A model can be fitted and still have only smoke or diagnostic evidence.
| Evidence tier | Meaning |
|---|---|
| Formal small grid | Likelihood, parser, extractors, diagnostics, interval status, focused recovery tests, and an ADEMP sheet exist. |
| Smoke/artifact only | The route is fitted and inspectable, but it does not yet have enough recovery or coverage evidence for broad claims. |
| Interval-heavy opt-in | Profiles or bootstrap checks are expensive or partial; status tables must show success, failure, or not-requested rows. |
| Diagnostic/failure ledger | The fit teaches us about boundaries or hard cases, but it is not a user-facing operating-characteristic claim. |
| Planned/blocked | Syntax or design may exist, but the fitter should reject the route or route users to a supported alternative. |
Use fast Wald intervals for routine fixed-effect coefficients and
selected direct fitted targets when TMB::sdreport()
supplies the optimized-parameter covariance. Direct SD intervals use the
fitted log-SD scale before exponentiating, and direct correlation
intervals use the guarded atanh correlation-link scale before returning
to the correlation scale. Do not use Wald intervals as a shortcut for
derived q=4 correlations, repeatability, phylogenetic signal,
unavailable rows, or weak-Hessian fits that need fit-specific
diagnostics. Direct profile targets can be mechanically available but
still fail in a given fit. confint(method = "bootstrap")
now provides a narrow public simulate/refit route for selected direct
targets, while Phase 18 bootstrap artifacts remain private simulation
infrastructure and do not imply bootstrap support in
summary(), corpairs(), prediction tables, or
derived summaries.
Family and component map
Use this table before combining a family with a random-effect or dependence surface.
| Model family or component | Fitted formulas today | Random effects today | Dependence or correlation today | Main planned boundary |
|---|---|---|---|---|
| Gaussian, one response |
mu and sigma
|
ordinary mu intercepts, independent slopes, one-slope
correlated blocks, q > 2 numeric mu blocks,
sigma intercepts, independent sigma slopes,
unlabelled correlated sigma intercept-slope and multi-slope
blocks, and sd(group) ~ x for unlabelled mu
intercept SDs |
ordinary group-level corpairs() rows for fitted
covariance blocks |
labelled or cross-formula sigma slope covariance,
coefficient-specific sd(group, coef = "x"), and broad p8
location-scale slope endpoints |
| Student-t | fixed-effect mu, sigma, and
nu
|
ordinary unlabelled mu random intercepts and
independent numeric slopes |
the spatial() q1 mu intercept and
phylo() nu intercept are diagnostic-only; the
spatial intercept-plus-one-slope route is recovery-grade; no labelled
covariance |
sigma or other nu random effects,
correlated slopes, skewness, and structured Student-t effects beyond
those exact gates |
| Lognormal and Gamma | fixed-effect mu and family-specific sigma
scale |
separate gates for ordinary unlabelled mu random
intercepts/independent numeric slopes or one ordinary sigma
random intercept; the two sides cannot be combined |
lognormal sigma intercept is inference-ready with
caveats only in its exact ledger domain; Gamma sigma
intercept is inference-ready with caveats only at true SD 0.40,
n_each=12, and M >= 32 (M=16
borderline); Gamma also has a recovery-grade relmat() q=1
mu intercept/one-slope |
sigma slopes, combined
mu+sigma random effects, correlated or
labelled slopes, known covariance, and further structured
dependence |
| Beta | fixed-effect mu and sigma
|
ordinary unlabelled mu random intercepts and
independent numeric slopes |
recovery grade: animal() q=1 mu
intercept/one-slope and sigma intercept |
ordinary sigma random effects, correlated slopes,
bounded-response known covariance, and further structured
dependence |
| Tweedie | fixed-effect mu, sigma, and intercept-only
nu ~ 1
|
ordinary unlabelled mu random intercepts and
independent numeric slopes; exact mc-0539 is
inference-ready with caveats for true SD 0.50 and M>=16 |
none | predictor-dependent power, sigma random effects,
correlated/labelled mu slopes, structured dependence, and
bivariate or mixed-response Tweedie |
| Zero-one beta | fixed-effect mu, sigma, zoi,
and coi
|
ordinary unlabelled mu random intercepts and
independent numeric slopes; exact mc-0575 is
inference-ready with caveats for true SD 0.50 and M>=16, under its
generator-qualified evidence |
none |
sigma/zoi/coi random effects,
covariance blocks, known covariance, denominator syntax, bivariate
bounded responses, and structured dependence |
| Beta-binomial | fixed-effect mu and sigma with row
trials |
ordinary unlabelled mu random intercepts and
independent numeric slopes |
none | correlated slopes, sigma random effects, zero-one
inflation, and structured dependence |
| Binomial | fixed-effect mu for 0/1 or
cbind(successes, failures) responses |
ordinary unlabelled mu random intercepts and
independent numeric slopes |
the exact independent-slope ledger domain is inference-ready with caveats | correlated or labelled slopes, structured effects, non-logit links, and bivariate or mixed responses |
| Poisson and NB2 | fixed-effect mu; NB2 also has fixed-effect
sigma and the first ordinary log-sigma
random-intercept gate |
ordinary non-zero-inflated mu random intercepts/slopes;
Poisson/NB2 single-provider q1 structured mu; NB2 q1
structured sigma; one exact crossed NB2
spatial-plus-relatedness mu route |
single-provider routes have row-specific source/smoke/recovery evidence; the exact crossed NB2 route is recovery-only with no intervals or coverage | correlated ordinary count slopes, unsupported inflation/hurdle
count-mu effects, plain NB2 sigma slopes,
richer/labelled structured routes, simultaneous structured types beyond
the exact crossed NB2 gate, and broader count covariance |
| Zero-inflated Poisson and zero-inflated NB2 | fixed-effect mu; zi ~ ...; NB2 also has
fixed-effect sigma
|
exact diagnostic-only q=1 Poisson
zi ~ spatial(1 | id, coords = coords) intercept only |
same exact structured intercept only (no NB2 zi
structure) |
random effects in zi beyond the exact Poisson spatial
intercept, structured zero inflation beyond the Poisson
zi ~ spatial() intercept, NB2 zi structure,
and corpairs() for count latent effects |
| Truncated NB2 and hurdle NB2 | fixed-effect mu; fixed-effect sigma;
hurdle NB2 also has hu ~ ...
|
ordinary unlabelled zero-truncated NB2 mu random
intercepts and independent numeric slopes for non-hurdle models |
diagnostic-only: one relmat() q=1 hu
intercept with K or Q (hurdle NB2, inherited
by the alias) |
random effects in hu beyond the exact
relmat() q=1 intercept, random effects in hurdle count
mu, correlated zero-truncated slopes, and other structured
hurdle effects |
| Cumulative-logit ordinal | fixed-effect ordinal location with estimated cutpoints | ordinary unlabelled mu random intercepts and
independent numeric slopes, plus one exact q1
mu ~ phylo(1 | id, tree = tree) intercept |
exact phylogenetic intercept is diagnostic-only | other structured ordinal effects, scale or discrimination formulas, intervals/coverage for the phylogenetic gate, and bivariate ordinal models |
| Gaussian meta-analysis |
meta_V(V = V) or deprecated compatibility alias
meta_known_V(V = V)
|
ordinary Gaussian random effects may be combined with estimated residual terms where supported | known sampling covariance is observation-level input, not a latent relatedness effect | non-Gaussian known covariance, proportional-variance
meta_V(w = w), sparse/block-sparse known covariance, and
dense known V with non-unit weights |
| Bivariate Gaussian |
mu1, mu2, sigma1,
sigma2, and fixed-effect rho12
|
ordinary bivariate random-intercept slices, same-response
mu/sigma intercept and slope-only covariance,
all-four q=4 intercept blocks, matching slope-only
mu1/mu2 and
sigma1/sigma2 blocks, matching q4/q6
mu1/mu2 location blocks with smoke artifact
routing, and the first ordinary q8 all-endpoint block with
smoke/recovery artifact routing |
residual rho12() and group-level
corpairs() stay separate |
random effects in rho12, mixed-response bivariate
families, broader p8/q8 endpoint variants, and broad q > 2
recovery |
zi is currently a fixed-effect probability component
except for the exact diagnostic-only Poisson spatial q=1 intercept.
hu is fixed-effect by default, with one diagnostic-only
truncated-NB2 q=1 hu ~ relmat(1 | id, K/Q = ...) intercept
route. Do not infer other random-effect or structured-dependence support
from either narrow gate.
Current capability and evidence map
This table connects fitted status to inference status. A first-slice fitted row is useful, but it is not the same as a formal coverage claim.
| Surface | Intercepts | Slopes | Combinations | Simulation or evidence tier | Interval tier |
|---|---|---|---|---|---|
Ordinary Gaussian mu
|
fitted | independent, one correlated slope, q>2 advanced | ordinary group covariance | formal small grids for named subsets; q>2 remains advanced | direct SD/profile targets; q>2 correlations derived-unavailable |
Ordinary Gaussian sigma
|
fitted | independent plus unlabelled correlated log(sigma)
intercept-slope and multi-slope blocks |
labelled blocks and cross-formula mu-sigma
slope covariance remain planned |
smoke and small-grid evidence for named independent routes; correlated blocks have fit/extractor contracts but no blanket interval claim | direct SD targets and Wald fixed effects where row-specific evidence allows |
sd(group) |
fitted for unlabelled Gaussian mu intercept SD |
no coefficient-specific slope SD yet | direct SD surface | focused recovery | coefficient intervals only where direct; row-specific SDs are derived |
| Bivariate ordinary Gaussian | q=2 intercepts fitted | matching slope-only mu1/mu2, same-response
q2 mu/sigma, q2
sigma1/sigma2, q4/q6 location
mu1/mu2, and the first ordinary q8
all-endpoint block fitted |
selected q=2, same-response mu/sigma,
all-four q=4 intercept blocks, q > 2 location blocks, and the first
q8 endpoint block |
q=2 admitted; same-response q2 and q2 scale-slope artifact-backed; q4/q6 location smoke only; q8 diagnostic artifacts only, with no coverage or power claim | q=2 direct profile; q > 2 location SDs and q8 endpoint SDs direct; q > 2 and q8 correlations derived-unavailable |
Residual rho12
|
not a random effect | predictor-dependent fixed effects | residual coscale only | admitted and interval-heavy | default direct Wald for constant rows; direct profile for constant
or supplied newdata rows; direct bootstrap only through
selected confint() targets |
| Phylogenetic Gaussian |
mu intercept fitted |
one mu slope fitted |
q=2 mu1/mu2 and q=4 location-scale fitted,
with Ayumi hard cases diagnostic |
small controlled grids; full-species hard cases stay diagnostic | direct targets for q=2; q=4 derived-unavailable |
| Coordinate spatial Gaussian |
mu intercept fitted |
one mu slope fitted |
q=2 mu1/mu2 fitted; constant all-four q=4
fitted |
q=2 admitted; q=4 extractor/diagnostic smoke only | fixed-effect Wald and opt-in profiles for q=2 artifacts; q=4 derived-unavailable |
| Animal Gaussian |
mu intercept fitted |
one mu slope fitted |
q=2 and q=4 fitted for small dense or known-matrix routes | q=2/q=4 smoke artifacts, not broad coverage | q=2 fixed-effect Wald plus opt-in profile status; q=4 derived-unavailable |
relmat() Gaussian |
mu intercept fitted |
one mu slope fitted |
q=2 and q=4 fitted for known matrices | q=2/q=4 smoke artifacts, not broad coverage | same as animal |
Poisson/NB2 ordinary mu
|
fitted | independent numeric slopes fitted | no labelled or correlated count blocks | first small count grids | Wald fixed effects; direct SD profile artifacts |
NB2 ordinary sigma
|
fitted for independent log-sigma random intercepts |
no plain sigma slopes yet |
recovery-grade q=1 structured sigma one-slope slices
(phylo()/spatial()/animal()/relmat());
no labelled, joint mu/sigma, zero-inflated,
truncated, or hurdle scale blocks |
separate overdispersion-random-intercept smoke lane | Direct log_sd_sigma profile target |
| Non-Gaussian structured dependence | Poisson/NB2 q1 single-provider mu routes, NB2 q1
structured sigma, and one exact crossed NB2
spatial-plus-relatedness mu route |
unlabelled single-provider intercept-plus-one-slope blocks are fitted; the crossed two-provider route is intercept-only on each field | pure, labelled, or multiple slopes, richer covariance, and simultaneous providers beyond the exact crossed gate remain planned | focused tests cover extraction/diagnostics; the crossed design has recovery-only evidence | Direct log_sd_phylo targets where exposed; no
crossed-route interval/coverage promotion |
zi, hu, zoi, and
coi
|
fixed effects where supported | exact diagnostic-only q=1 intercept gates for Poisson
zi ~ spatial() and truncated-NB2
hu ~ relmat(K/Q) only |
no labelled or correlated covariance layer | fixed-effect tests plus focused local-fit/extractor tests for the two exact q=1 gates; zero-one beta carries Phase 18 artifact helpers | Wald fixed effects where implemented; the q=1 gates are feasibility routes without recovery, interval, or coverage promotion |
| Ordinal, shape, bounded scale | fixed effects where supported; eligible cumulative-logit, Student-t,
beta, Tweedie, skew-normal, and zero-one-beta routes also fit ordinary
mu intercepts/slopes |
diagnostic-only cumulative-logit q1 mu ~ phylo();
recovery-grade Student-t mu ~ spatial(1 + x | ...) and beta
mu/sigma ~ animal() gates; Student-t
intercept-only mu ~ spatial(1 | ...) and
nu ~ phylo() are diagnostic-only |
other distributional-parameter random effects, correlated/labelled slopes, and structured neighbours beyond the exact gates remain planned | family recovery tests plus route-specific source/local-fit tests | retain each live-ledger tier; no blanket recovery, interval, or coverage promotion |
meta_V(V = V) |
estimated effects plus known sampling covariance | ordinary Gaussian random effects only where otherwise supported |
V is input data, not latent dependence |
formal small grids for vector/dense known V;
predictor-dependent sigma needs fit-specific Hessian
checks |
never interval-target V; Wald SEs and intervals for
sigma ~ moderator are unreliable when
pdHess = FALSE
|
Random-effect and dependence map
Here q is the number of latent endpoints in one covariance block. A
q=2 block has two endpoints, such as mu1 and
mu2 random intercepts. A q=4 block has four endpoints, such
as mu1, mu2, sigma1, and
sigma2 random intercepts. The q8 language now includes one
fitted ordinary all-endpoint diagnostic lane with smoke/recovery
artifacts. The broader p8/q8 roadmap still refers to future all-endpoint
location-scale slope variants, not routine tutorial or
coverage-supported routes.
| Layer | Fitted q and slope support | Main extractors or diagnostics | Planned or blocked neighbours |
|---|---|---|---|
Ordinary Gaussian mu
|
q=1 random intercepts and independent slopes; q=2 intercept-slope
correlations; q > 2 numeric mu blocks |
sdpars$mu, corpars$mu or
corpars$re_cov, ranef(),
corpairs(), summary()$covariance,
profile_targets(), check_drm()
|
q > 2 correlations are derived-unavailable for direct profile intervals and larger q blocks remain advanced |
Ordinary Gaussian sigma
|
q=1 residual-scale intercepts, independent numeric slopes, and
unlabelled correlated intercept-slope and multi-slope blocks on
log(sigma)
|
sdpars$sigma, corpars$sigma,
profile_targets(), check_drm(),
sigma()
|
labelled residual-scale blocks and cross-formula
mu-sigma slope covariance |
| Random-effect SD surface |
sd(group) ~ x_group for unlabelled Gaussian
mu random intercepts |
predict_parameters(dpar = "sd(group)"),
marginal_parameters(), fixed-effect summaries |
coefficient-specific sd(group, coef = "x"),
spatial/animal/relmat direct-SD siblings, and generic sd*()
unification |
Ordinary bivariate mu1/mu2
|
q=2 matching labelled random intercepts, q=2 matching slope-only random-slope blocks, q4/q6 location blocks with smoke artifact routing, and the location endpoints of the first q8 diagnostic lane |
corpairs(class = "mean-mean"),
summary()$covariance, profile_targets(),
check_drm()
|
broader p8/q8 endpoint variants and predictor-dependent slope
corpair() regressions |
Ordinary bivariate sigma1/sigma2
|
q=2 matching labelled random intercepts, slope-only scale-slope blocks, and the scale endpoints of the first q8 diagnostic lane |
corpairs(class = "scale-scale"),
summary()$covariance, profile_targets()
|
broader p8/q8 endpoint variants |
Same-response mu/sigma
|
one or more q=2 matching random-intercept blocks, plus matching slope-only blocks within a response |
corpairs(class = "mean-scale"),
corpairs(class = "mean-scale-slope"),
corpars$mu_sigma, summary()$covariance
|
cross-response and mismatched-coefficient covariance |
| All-four ordinary location-scale | constant q=4 random-intercept block across mu1,
mu2, sigma1, and sigma2, plus the
first q8 all-endpoint diagnostic lane with matching
(1 + x | p | id) terms |
corpairs() and summary()$covariance report
derived latent correlations; Phase 18 q8 recovery artifacts report bias,
RMSE, MCSE, and interval unavailability |
derived q=4/q8 correlation intervals and broader p8/q8 random-slope endpoint variants |
| Residual coscale | fixed-effect rho12 ~ ...
|
rho12(),
confint(..., parm = "rho12", newdata = ...),
summary()
|
random effects or structured dependence in rho12
|
Ordinary corpair() regression |
q=2 predictor-dependent group-level correlation for an already fitted block |
corpairs(newdata = ...),
plot_corpairs()
|
q=4 correlation regressions and slope-level corpair()
regressions |
| Phylogenetic structure | Gaussian q=1 univariate mu and sigma
intercepts with optional matching mu/sigma
correlation; one numeric mu slope; the exact q1
sigma one-slope route; Gaussian q=2 bivariate
mu1/mu2; Gaussian constant q=4 location-scale
intercept block; ordinary Poisson/NB2 q=1 mu
intercept-plus-one-slope routes; separate recovery-grade NB2 q1
structured sigma intercept-plus-one-slope |
sdpars$mu, sdpars$sigma, marker-specific
ranef() blocks,
corpairs(level = "phylogenetic") for Gaussian q>=2,
profile_targets(), check_drm(); the Gaussian
sigma slope is inference-ready with caveats |
pure, multiple, or labelled Poisson/NB2 phylogenetic slopes,
zero-inflated phylogenetic effects, multiple or labelled Gaussian
phylogenetic slopes, phylogenetic slope correlations, direct-SD formulas
combined with structured sigma, and structured
rho12
|
| Phylogenetic direct SD |
sd_phylo(), sd_phylo1(), and
sd_phylo2() direct-SD surfaces where documented |
fixed-effect summaries, prediction helpers, profile targets where direct | generic sd*() naming across phylo, spatial, animal, and
relmat() remains a future unification lane |
| Coordinate spatial structure | q=1 univariate mu and sigma intercepts
with optional matching mu/sigma correlation;
one numeric mu slope; a q1 sigma one-slope
point-fit/extractor route; q=2 bivariate
mu1/mu2 intercept covariance; constant q=4
location-scale intercept block; ordinary Poisson/NB2 q=1 mu
intercept-plus-one-slope routes; separate recovery-grade NB2 q1
structured sigma intercept-plus-one-slope; the exact
diagnostic-only Poisson zi ~ spatial() intercept; the exact
diagnostic-only fixed-zi Poisson
mu ~ spatial() intercept; and the exact diagnostic-only
fixed-zi NB2 mu ~ spatial() intercept |
sdpars$mu, sdpars$sigma, marker-specific
ranef() blocks, corpairs(level = "spatial"),
summary()$covariance, profile_targets(),
check_drm()
|
the Gaussian spatial sigma-slope interval gate, mesh/SPDE, multiple
or labelled Gaussian slopes, slope correlations, direct-SD surfaces,
spatial corpair() regression, pure, multiple, or labelled
count spatial slopes, and zero-inflated spatial effects outside the
exact Poisson zi, fixed-zi Poisson
mu, and fixed-zi NB2 mu gates;
both fixed-zi routes have no recovery, interval, or
coverage promotion |
| Animal-model structure | q=1 univariate mu and sigma intercepts
with optional matching mu/sigma correlation;
one numeric mu slope for pedigree,
A, or Ainv; the exact A-matrix q1
sigma one-slope route; q=2 bivariate
mu1/mu2; constant q=4 location-scale intercept
block; ordinary Poisson/NB2 q=1 mu intercept-plus-one-slope
routes; separate recovery-grade NB2 q1 structured sigma
intercept-plus-one-slope |
sdpars$mu, sdpars$sigma, marker-specific
ranef() blocks, corpairs(level = "animal"),
profile_targets(), check_drm(); the Gaussian
sigma slope is inference-ready with caveats |
pedigree/Ainv bridge marshalling, sparse large-pedigree
construction, multiple or labelled Gaussian slopes, slope correlations,
predictor-dependent corpair() regression, direct-SD
grammar, pure, multiple, or labelled count animal slopes, and labelled
count covariance |
relmat() known latent relatedness |
q=1 univariate mu and sigma intercepts
with optional matching mu/sigma correlation;
one numeric mu slope for K or Q;
the exact K/Q q1 sigma one-slope route; q=2 bivariate
mu1/mu2; constant q=4 location-scale intercept
block; ordinary Poisson/NB2 q=1 mu intercept-plus-one-slope
routes; separate recovery-grade NB2 q1 structured sigma
intercept-plus-one-slope |
sdpars$mu, sdpars$sigma, marker-specific
ranef() blocks, corpairs(level = "relmat"),
profile_targets(), check_drm(); the Gaussian
sigma slope is inference-ready with caveats |
broader K/Q bridge claims, multiple or labelled Gaussian slopes,
slope correlations, predictor-dependent corpair()
regression, direct-SD grammar, pure, multiple, or labelled count
relmat() slopes, and labelled count covariance |
Non-Gaussian ordinary mu
|
Ordinary mu intercepts/slopes for every fitted
univariate family; Poisson/NB2 q1 single-provider structured
mu; exact recovery-grade Gamma-phylo,
lognormal-phylo/relmat, Gamma-relatedness, Student-spatial, beta-animal,
and ordinal-phylo gates; and one crossed NB2 spatial-plus-relatedness
route |
sdpars$mu, marker-specific ranef() blocks,
direct targets, and check_drm() where exposed; crossed NB2
recovery is design-dependent |
correlated/labelled non-Gaussian slopes, pure/multiple structured slopes, simultaneous count types beyond the exact crossed NB2 gate, unsupported inflation/hurdle neighbours, and cross-parameter covariance |
| Non-Gaussian scale, shape, zero-inflation, and hurdle | fixed-effect formulas where the family supports the component;
ordinary NB2, lognormal, and Gamma log-sigma random
intercepts, plus recovery-grade NB2 q=1 structured sigma
one-slope slices from
phylo()/spatial()/animal()/relmat()
and one diagnostic-only truncated-NB2 q=1 hu ~ relmat(K/Q)
intercept |
fixed-effect coefficient tables and Wald intervals where
implemented; NB2/lognormal/Gamma sdpars$sigma,
random_effects$sigma, direct log_sd_sigma, and
check_drm() for the intercept gates; only the exact
lognormal and Gamma (M >= 32) ledger domains are
inference-ready with caveats |
sigma slopes, structured scale routes outside the NB2
q=1 one-slope gate, and random effects in nu,
zi, zoi, coi, or latent skewness,
plus hu random effects beyond the exact q=1
relmat() intercept |
Slope coverage at a glance
| Random-effect type | At least one random slope fitted? | Current fitted scope | Not yet fitted |
|---|---|---|---|
Ordinary Gaussian mu
|
Yes | independent slopes, one-slope correlated blocks, q > 2 numeric
mu blocks |
routine high-q teaching and direct q > 2 correlation profiles |
Ordinary Gaussian sigma
|
Yes | independent slopes plus unlabelled correlated intercept-slope and multi-slope blocks | labelled residual-scale and cross-formula
mu-sigma slope covariance |
| Ordinary bivariate Gaussian | Yes | matching slope-only mu1/mu2, same-response
mu/sigma, and
sigma1/sigma2 q=2 blocks plus q4/q6 location
blocks and the first q8 all-endpoint diagnostic lane with smoke/recovery
artifact routing |
broader p8/q8 all-endpoint variants, q8 coverage or power evidence,
and slope-level corpair() regressions |
| Coordinate spatial | Yes | one univariate Gaussian mu slope plus a q1
sigma one-slope point-fit/extractor route and constant q=4
bivariate Gaussian location-scale intercepts |
spatial sigma-slope intervals, multiple or labelled slopes, slope
correlations, and non-Gaussian spatial effects outside the exact
ordinary Poisson/NB2 q1 spatial mu
intercept-plus-one-slope, recovery-grade NB2 q1 spatial
sigma, Student-t spatial mu, Poisson spatial
zi, fixed-zi Poisson spatial mu,
and fixed-zi NB2 spatial mu gates |
| Phylogenetic | Yes | one univariate Gaussian mu slope plus the exact q1
sigma one-slope route, inference-ready with caveats; exact
non-Gaussian gates include ordinary Poisson/NB2 q1 phylogenetic
mu intercept-plus-one-slope, recovery-grade NB2 q1
phylogenetic sigma, diagnostic-only Student-t q1
phylogenetic nu, and diagnostic-only cumulative-logit q1
phylogenetic mu
|
multiple or labelled slopes, slope correlations, direct-SD formulas
combined with structured sigma, and non-Gaussian
phylogenetic effects outside those exact row-specific gates |
| Animal-model relatedness | Yes | documented Gaussian routes plus exact ordinary Poisson/NB2 q1 animal
mu intercept-plus-one-slope, NB2 q1 animal
sigma, and beta animal gates |
pedigree/Ainv bridge marshalling, sparse large-pedigree scaling, multiple or labelled slopes, slope correlations, and non-Gaussian animal neighbours outside exact gates |
relmat() known latent relatedness |
Yes | documented Gaussian routes plus exact ordinary Poisson/NB2 q1 relmat
mu intercept-plus-one-slope, NB2 q1 relmat
sigma, Gamma q1 relmat mu, and truncated-NB2
q1 relmat hu gates |
broader bridge claims, multiple or labelled slopes, slope correlations, direct-SD grammar, and non-Gaussian relmat neighbours outside exact gates |
Non-Gaussian ordinary mu
|
Yes | Ordinary intercepts/slopes for every fitted univariate family;
Poisson/NB2 q1 single-provider structured mu; exact
non-count gates; one recovery-only crossed NB2 spatial-plus-relatedness
mu route |
correlated slopes, unsupported inflation/hurdle
count-mu effects, pure/multiple/labelled structured slopes,
simultaneous structured types beyond the exact crossed NB2 gate, and
broader bounded-response dependence |
Non-Gaussian scale, shape, zi, hu,
ordinal, or bounded-response components |
First NB2/lognormal/Gamma scale-intercept slices; exact q1 NB2
structured sigma routes at recovery grade; Poisson
zi ~ spatial(), truncated-NB2
hu ~ relmat(K/Q), and cumulative-logit
mu ~ phylo() routes are diagnostic-only |
fixed effects where implemented; ordinary NB2, lognormal, and Gamma
log-sigma random intercepts; exact NB2
phylo()/spatial()/animal()/relmat()
structured sigma intercept-plus-one-slope routes; exact
diagnostic-only Poisson q1 spatial-zi, truncated-NB2 q1
relatedness-hurdle, and cumulative-logit q1 phylogenetic-mu
intercepts |
ordinary non-Gaussian scale slopes, richer or labelled structured
sigma, structured-sigma intervals/coverage, and random effects for
shape, inflation beyond the exact spatial-zi gate, ordinal
routes beyond the exact phylogenetic-mu gate, or
bounded-response components |
Roadmap use
The next implementation work should move only one boundary at a time. The detailed slice history lives in the roadmap and design ledgers. This page keeps only the current user-facing lanes:
| Current lane | Why it helps users | Done when |
|---|---|---|
Generic sd*() direct-SD design |
Users should not need separate direct-SD names for phylo, spatial,
animal, and relmat() routes forever. |
The grammar, compatibility route for existing
sd_phylo*() helpers, examples, tests, and reference-index
plan are explicit before parser work. |
| Broader p8/q8 location-scale slope planning | Full individual-difference location-scale slope models are scientifically attractive but weakly identified. | The first q8 diagnostic lane stays separate from coverage and power claims, and any broader p8/q8 variant has endpoint classes, parameterization, diagnostics, sample-size gates, and interval policy written before syntax opens. |
| q=4 interval policy | Users need to know which q=4 rows are point estimates and which have real intervals. | q=4 rows keep derived_interval_unavailable until a
validated derived-profile or bootstrap route exists. |
| Non-Gaussian structured q1 gate | Count users need realistic structural-dependence paths before broad non-Gaussian parity. | Poisson and NB2 q1 phylogenetic mu intercepts are
fitted as narrow first slices; broader promotion waits for formal
recovery, diagnostics, extractor rows, and interval-status
evidence. |
| Route-specific non-Gaussian issues | Developers need a narrow implementation issue before touching code. | The issue names one family, component, layer, q, comparator, extractor contract, diagnostic contract, interval status, simulation artifact, and user fallback. |
| Poisson q1 runner contract | The fitted Poisson phylogenetic q1 route needs schema checks before broader simulation claims. | Direct target, extractor, manifest, warning/error, smoke-grid, formal-grid, malformed-neighbour, diagnostic, and artifact tests are specified before the route is promoted beyond smoke evidence. |
| Map and evidence maintenance | The site should help users fit a supported model rather than read a project diary. |
model-map, this article, source-map, the
validation-debt register, and stale scans agree after each substantial
feature slice. |
Common planned requests
Use this table when a desired model is not fitted yet.
| If you want… | Fit now | Planned boundary |
|---|---|---|
| zero-inflated counts with predictors in the zero process | fixed-effect zi ~ predictors in the supported count
family; diagnostic-only Poisson
zi ~ spatial(1 | id, coords = coords) q=1 structured
intercept |
random effects in zi, NB2 zi structure,
and Poisson zi structure beyond the first
spatial() intercept |
| hurdle counts with a modelled hurdle probability | fixed-effect hu ~ predictors in hurdle NB2, or one
diagnostic-only q=1 hu ~ relmat(1 | id, K/Q = ...)
intercept |
hu random effects or structured dependence beyond the
exact relatedness intercept |
| phylogenetic or spatial count dependence | ordinary Poisson/NB2 q1 single-provider mu; separate
NB2 q1 structured sigma; exact crossed NB2
spatial-plus-relatedness mu when the crossed design
identifies both fields |
pure, multiple, or labelled structured count slopes, unsupported
zero-inflation, richer NB2 structured sigma, simultaneous
types beyond the exact crossed gate, and labelled count covariance |
| full individual-difference location-scale slopes | fitted q2 slope-only mu1/mu2 covariance,
smaller univariate pieces, or the first ordinary q8 diagnostic artifact
lane when all four endpoints use matching (1 + x | p | id)
terms |
q8 coverage or power evidence, broader p8/q8 location-scale slope variants, and interval support for derived q8 correlations |
| structured direct-SD surfaces outside phylogeny | fitted structured intercept/slope SDs and
profile_targets() where available |
generic spatial, animal, or relmat() direct-SD
regression |
| spatial q4 location-scale covariance | fitted bivariate Gaussian q4 spatial location-scale block when all
four endpoints use matching labelled
spatial(1 | p | site, coords = coords) terms; treat current
q4 evidence as extractor/diagnostic smoke; the separate q1 spatial
sigma one-slope route has point-fit/extractor evidence |
mesh/SPDE, spatial sigma-slope intervals, multiple or labelled
spatial slopes, direct-SD surfaces, predictor-dependent spatial
corpair() regression, q4 coverage evidence, and
non-Gaussian spatial routes outside the exact ordinary Poisson/NB2 q1
spatial mu intercept-plus-one-slope, recovery-grade NB2 q1
spatial sigma, Student-t spatial mu, Poisson
spatial zi, fixed-zi Poisson spatial
mu, and fixed-zi NB2 spatial mu
gates |
| NB2 structured count model | single-provider q1 mu intercept-plus-one-slope routes,
ordinary NB2 mu, separate recovery-grade q1 structured
sigma, or the exact recovery-only crossed
spatial-plus-relatedness mu route |
pure/multiple/labelled structured mu slopes,
unsupported zero-inflated structure, richer structured
sigma, simultaneous types beyond the exact crossed gate,
and labelled count covariance |
| Poisson structured count slopes | ordinary Poisson/NB2 q=1 unlabelled
phylo()/spatial()/animal()/relmat()
intercept-plus-one-slope terms, or independent numeric mu
slopes when the grouping is exchangeable |
pure, multiple, or labelled structured count slopes need their own recovery and diagnostic evidence |
Poisson animal() or relmat() count
dependence |
ordinary Poisson/NB2 q1 animal/relatedness mu, ordinary
count mu, Gaussian animal/relatedness, or the exact crossed
NB2 spatial-plus-relatedness mu route |
pure/multiple/labelled known-relatedness count slopes, unsupported zero-inflation, and simultaneous types beyond the exact crossed NB2 gate remain planned |
| non-Gaussian structured scale or shape effects | fixed-effect sigma, nu, zi,
or hu formulas where the family supports them; ordinary
NB2, lognormal, and Gamma log-sigma random intercepts for
plain grouping; separate recovery-grade NB2 q=1
phylo()/spatial()/animal()/relmat()
structured sigma intercept-plus-one-slope routes; one
diagnostic-only truncated-NB2 q=1 hu ~ relmat(K/Q)
intercept |
richer or labelled structured scale and shape, zero-inflation, and hurdle random effects beyond the exact relatedness intercept need family-specific likelihood, extractor, diagnostic, and recovery contracts |
| known sampling covariance plus latent relatedness | Gaussian meta_V(V = V) for known sampling covariance,
or Gaussian relmat() for latent relatedness when that is
the scientific target |
non-Gaussian known covariance and latent relatedness should stay separate until each has its own issue and simulation gate |
| unsupported structured count syntax | fit the nearest fixed-effect or ordinary random-effect model and
read check_drm() before interpretation |
future error messages should name the unsupported family, component, layer, q, and nearest fitted alternative |