Detailed model map for contributors

This is a contributor reference for the detailed combinations of family, distributional parameter, and dependence structure currently described by drmTMB. It preserves the exact boundaries behind the public guides; it is not the starting point for choosing an analysis.

To choose an analysis, begin with What can I fit today?, then use Can I fit and report this model? for the reporting boundary and its next-tutorial links. Return here when maintaining documentation or checking the exact public scope of a specialised combination.

How this reference is organised

1. Choose the response family. Match the support and measurement process: continuous, positive, count, proportion, success/trial, ordinal, or two responses.
2. Choose what changes. Model the expected response with mu; residual or family-specific variation with sigma; and a supported shape, zero, hurdle, boundary, or residual-correlation component only when the family defines it.
3. Choose the dependence structure. Use ordinary random effects for exchangeable groups, or phylo(), spatial(), animal(), or relmat() when the relationships among levels are known.
4. Choose an inference route. Fit and check the model first. Then inspect profile_targets(fit) and the reporting guide before assuming that every derived standard deviation or correlation has an interval.

Family and parameter guide

Data or question	Main fitted route	Parameters you can model	Learn from
Approximately continuous response	Gaussian	mu, residual sigma, and supported ordinary or structured random effects	When variance carries signal
Continuous response with heavy tails	Student-t	mu, sigma, and tail parameter nu; ordinary mu random effects are available within the stated scope	Robust continuous responses
Asymmetric continuous response	Skew-normal	mu, sigma, and slant parameter nu; ordinary mu random effects are available within the stated scope	Choosing response families
Positive continuous response	Lognormal, Gamma, or Tweedie	Family-specific mu, sigma, and, for Tweedie, power nu; random-effect support is narrower than for Gaussian models	Choosing response families
Counts	Poisson or negative-binomial 2	mu; NB2 also models overdispersion through sigma; offsets are supported for exposure	Count abundance and extra zeros
Counts with extra zeros or a separate zero process	Zero-inflated Poisson/NB2 or hurdle NB2	zi for structural-zero probability or hu for hurdle probability, alongside the supported count parameters	Count abundance and extra zeros
Positive counts with zeros excluded	Zero-truncated NB2	mu and sigma	Choosing response families
Continuous proportion strictly between zero and one	beta_family()	mu and beta scale sigma	Proportions and success rates
Continuous proportion with structural zero or one values	zero_one_beta()	Interior mu and sigma, boundary probability zoi, and conditional-one probability coi	Proportions and success rates
Binary data or successes out of known trials	Binomial or beta-binomial	Event probability mu; beta-binomial also models overdispersion with sigma	Proportions and success rates
Ordered categories	Cumulative logit	Ordinal location mu and estimated cutpoints	Choosing response families
Two continuous outcomes	Bivariate Gaussian, lognormal, or Student-t	Response-specific location and scale plus residual correlation rho12 within the stated family scope	Bivariate non-Gaussian models
Two reviewed outcomes of different kinds	biv_associate()	Marginal models fitted first, followed by a latent-normal association parameter	Association between mixed outcome pairs

The public name sigma does not have the same mathematical conversion in every family. For example, it is residual standard deviation in a Gaussian model, coefficient of variation in the Gamma model, and maps to precision in beta models. Read Choosing response families before comparing sigma across families.

Random effects and structured dependence

Scientific structure	What is available	Important boundary	Guide
Exchangeable groups	Gaussian location and scale models have the broadest intercept, slope, and covariance support. Several non-Gaussian families support ordinary mu intercepts and independent slopes.	Do not assume that a random effect fitted for mu is also fitted for sigma, nu, zi, hu, zoi, or coi.	Formula grammar
Phylogeny	Gaussian location and selected scale effects; selected Poisson/NB2 location effects and narrowly documented non-Gaussian routes.	Multiple or labelled structured slopes, structured rho12, and many non-Gaussian combinations are not currently supported.	Phylogenetic structured effects
Coordinates	Gaussian location and selected scale effects; selected count and other narrowly documented routes.	Mesh or SPDE fields, broad spatial slope covariance, and spatial rho12 are not currently supported.	Coordinate-spatial structured effects
Pedigree or animal relatedness	Gaussian models have the broadest support; selected count, beta, and scale routes are available.	Large-pedigree, multiple-slope, and broad non-Gaussian combinations need the exact guide-specific support check.	Animal models and relatedness
Supplied latent covariance or precision matrix	relmat(K = K) or relmat(Q = Q) for supported latent random effects.	This is not a substitute for observation-level sampling covariance.	Known-matrix relmat models
Known sampling variance or covariance	Gaussian meta_V(V = V) with vector or dense V where documented.	V is input sampling uncertainty, not a likelihood weight or a latent relatedness matrix; non-Gaussian known covariance is not currently supported.	Meta-analysis with known sampling variances

When several structures seem plausible, read the Structural dependence overview before adding terms. A simpler model that answers the biological question clearly is usually a better starting point than an unlisted combination.

Exact extensions that need a guide-specific check

Some useful routes are deliberately narrow. For Gaussian scale models, there is a q1 sigma one-slope point-fit/extractor route for each documented structured provider; this does not imply interval or coverage support. Ordinary Gaussian scale models also include unlabelled correlated intercept-slope and multi-slope blocks, but labelled and cross-formula covariance remains outside the supported surface.

For phylogenetic count and shape models, the exact available extensions are Poisson/NB2 q1 phylogenetic mu intercept-plus-one-slope, NB2 q1 phylogenetic sigma, Student-t q1 phylogenetic nu, and cumulative-logit q1 phylogenetic mu. Each has the evidence and inference scope stated in its linked guide; do not treat the list as approval for another parameter, covariance structure, or slope pattern.

Across providers, Poisson/NB2 q1 single-provider structured mu routes remain restricted to their documented intercept-plus-one-slope forms. For hurdle models there is one diagnostic-only truncated-NB2 q=1 hu ~ relmat(K/Q) intercept; broader hurdle random effects remain unsupported.

For extra-zero count models, fixed-zi NB2 and fixed-zi Poisson location models are separate documented routes. The structured Poisson zi extension is diagnostic-only and limited to its stated spatial intercept; it does not establish a general random-effect or structured-inflation model.

Keep the correlation targets distinct

drmTMB exposes several correlations because they describe different levels of the model:

• rho12 is residual correlation between two responses within an observation.
• corpairs() reports correlations among fitted group-level random effects, such as correlation between two trait means across individuals.
• biv_associate() estimates a latent-normal association after the two marginal models have been fitted and fixed.

Use Changing residual coupling with rho12 for the first target, the random-effect sections of that guide for corpairs(), and Association between mixed outcome pairs for the third. Reporting one as though it were another changes the scientific claim.

Fitted does not mean every interval is available

A model may produce trustworthy point estimates while a particular derived correlation or variance share has no supported interval. Start with check_drm(fit), then use profile_targets(fit) to see which quantities can be profiled directly. The ordinary summary provides coefficient estimates and Wald intervals where available; profile and bootstrap intervals have a narrower target-specific scope.

Checking and using fitted models shows the full workflow. Can I fit and report this model? states the exact limits for specialised effects, small-group settings, boundary estimates, missing responses, and derived quantities.

Common requests and the nearest documented route

If you want to model…	Start with…	Current boundary
Predictors of extra-zero probability	A supported count family with fixed-effect zi ~ predictors	Broad random or structured effects in zi are not currently supported.
Predictors of hurdle probability	Hurdle NB2 with fixed-effect hu ~ predictors	Broad random or structured effects in hu are not currently supported.
Phylogenetic or spatial count variation	The exact Poisson or NB2 route shown in the relevant structural guide	Do not generalise a documented single structured effect to multiple, labelled, or zero-inflated combinations.
A changing random-effect standard deviation	Gaussian sd(group) ~ predictors	Coefficient-specific and general spatial, animal, or relmat() direct-SD formula surfaces are not currently supported.
Two-response residual association	A fitted bivariate family with rho12 ~ predictors	Random or structured effects in rho12 are not currently supported.
Known sampling covariance and latent relatedness together	Begin with either meta_V(V = V) or relmat() according to the scientific target	Do not treat the two matrices as interchangeable; check the exact combined route before fitting.

If a requested combination is absent from the public guides, treat it as not currently supported. Use the nearest documented model, state the simplification, and avoid interpreting syntax that is not listed in What can I fit today?.