Structural dependence overview

Choose the structure that matches your scientific question. Use this overview when observations, species, individuals, sites, or lines are not independent after the fixed effects have been included and you need a structured random effect instead of an ordinary random intercept.

This overview assumes you have already fit and interpreted a plain location-scale model, for example the Gaussian tutorial in When variance carries signal, Part 1, and now need one of the structured layers below because your observations are grouped, related, or spatially structured.

In drmTMB, a structural-dependence term is a latent random effect with a known relationship structure. It is separate from residual coscale rho12, which is the within-observation residual correlation between two responses. Use corpairs() for fitted latent random-effect correlations and rho12() for fitted residual response-response correlations.

A successful fit does not show that every related model is reliable. Each row below names the exact family, mean, residual scale, and correlation structure that has a worked example and its own checks. Before reporting an estimate or interval from any of these routes, read Can I fit and report this model?.

In this table, “q1” means one distributional parameter carries the structured effect, “q2” means two response means share one structured correlation, and “q4” means all four parameters of a two-response model (mu1, mu2, sigma1, sigma2) share one structured block; “zi” names a zero-inflation model and “hu” names a hurdle model; “diagnostic-only” means a fit can be obtained and inspected, but is not yet a scientific reporting route.

Pick the route

Your question	A sensible starting point	What to check before reporting	Read next
Do related individuals share additive genetic deviations, such as heritable trait differences?	animal(1 | individual, pedigree = pedigree), animal(1 | individual, A = A), or animal(1 | individual, Ainv = Ainv)	Fitted for the documented Gaussian mu/sigma, slope, q2, and q4 routes. The supported non-Gaussian models fit ordinary Poisson/NB2 q1 animal mu intercept-plus-one-slope, NB2 q1 animal sigma (point estimate only; see the guide), and the beta animal models described in the guide. Pedigree and Ainv inputs are fitted, but interval results checked with an A matrix do not yet carry over to pedigree or Ainv input for the one-slope sigma route. Sparse large-pedigree construction, additional multiple or labelled slope layouts outside the documented fitted models, and non-Gaussian neighbours outside those models are not available yet.	Animal models and additive relatedness
Do related species share evolutionary deviations?	phylo(1 | species, tree = tree)	Fitted for the documented Gaussian mu/sigma, slope, q2/q4, direct-SD, and corpair() routes. The supported non-Gaussian models fit ordinary Poisson/NB2 q1 phylogenetic mu intercept-plus-one-slope and NB2 q1 phylogenetic sigma (point estimate only; see the guide); Student-t q1 phylogenetic nu is diagnostic-only, while cumulative-logit q1 phylogenetic mu is diagnostic-only. Neighbouring non-Gaussian routes are not available yet.	Phylogenetic structured effects
Do nearby sites share smooth deviations, either through coordinates or a smooth field fitted from a mesh?	spatial(1 | site, coords = coords), spatial(1 + depth | site, coords = coords), or spatial(1 | site, mesh = mesh) for a mesh-based option with a fixed spatial range	Fitted for the documented coordinate-spatial Gaussian mu/sigma, slope, q2, and q4 routes. The separate mesh route is only bf(y ~ spatial(1 | site, mesh = mesh), sigma ~ 1) for a projected-coordinate Gaussian mu intercept with a spatial range you set rather than estimate, for the tested designs. The supported non-Gaussian models fit ordinary Poisson/NB2 q1 spatial mu intercept-plus-one-slope and NB2 q1 spatial sigma (point estimate only; see the guide); Student-t q1 spatial mu is diagnostic-only for the intercept and point estimate only for the intercept-plus-one-slope route. All three spatial-inflation models (Poisson zi, fixed-zi Poisson mu, and fixed-zi NB2 mu) are diagnostic-only routes checked on a single example. Mesh slopes/range and other mesh fields, additional multiple or labelled coordinate-slope layouts outside the documented fitted models, non-Gaussian routes outside those exact models, and spatial corpair() routes are not available yet.	Coordinate-spatial structured effects
Does the same response need both species and site structure at once?	Fit separate phylo() and spatial() sensitivity models for now	A combined route is not available yet. Report each fit as a sensitivity analysis and state which structure it omits; simultaneous structural layers need their own identifiability checks before use.	Structural dependence tutorial
Is the known matrix neither a pedigree, species tree, nor spatial coordinate surface?	relmat(1 | id, K = K) or relmat(1 | id, Q = Q)	Fitted for the documented Gaussian mu/sigma, slope, q2, and q4 routes. The supported non-Gaussian models fit ordinary Poisson/NB2 q1 relmat mu intercept-plus-one-slope, NB2 q1 relmat sigma (point estimate only; see the guide), Gamma q1 relmat mu, and truncated-NB2 q1 relmat hu (diagnostic-only). Additional multiple or labelled slope layouts outside the documented fitted models, other K/Q uses, predictor-dependent corpair() routes, and non-Gaussian neighbours outside those models are not available yet.	Known-matrix relatedness with relmat

What to read next

Read the detailed structural-dependence tutorial when you need fitted examples, equations, diagnostics, and interval guidance. That article is still the detailed page for animal, phylogenetic, spatial, combined-layer, and relmat() material while the topic is being split into smaller articles.

Read animal models and additive relatedness when your first question is specifically about animal(), pedigree, A, or Ainv. Read phylogenetic structured effects when your first question is specifically about phylo(), tree-based covariance, sd_phylo*(), or phylogenetic corpair() rows. Read two-tree phylogenetic interactions when one observation belongs to a pair of partner species drawn from two phylogenies, such as plant-pollinator or host-parasite pairs. Read coordinate-spatial structured effects when your first question is specifically about spatial(), site coordinates, coordinate-spatial slopes, spatial q=2 corpairs() rows, or the constant spatial q=4 location-scale block. Read known-matrix relatedness with relmat when the matrix is a lower-level latent covariance or precision matrix that does not belong to the animal, phylogenetic, or spatial routes.

Read the formula grammar when you want the compact implemented-versus-planned syntax table. Read the figure gallery when you want to see how rho12, ordinary group, phylogenetic, spatial, animal-model, and relmat() correlation rows should stay visually separate.

Fitted versus planned

A route one step away from the exact combination named in the table above, a different family, an extra slope, or a combined structure, needs its own check before you trust its numbers: start with check_drm() and the guide the route links to.

The routes fitted so far are useful for applied work, but they do not cover every structure equally. Fitting matching structured terms in two Gaussian response means links those two traits through one shared structured correlation. Adding matching structured terms to all four pieces of a two-response Gaussian model, both means and both residual scales, links them through one block across all four pieces (four standard deviations and six correlations). The univariate intercept route can also enter sigma for phylo(), spatial(), animal(), and relmat(). The exact Gaussian one-slope sigma route also fits for all four structures: for phylo(), animal() with an additive relatedness matrix, and relmat() with K or Q, that route has an interval you can report, with caveats explained in each guide; for spatial(), you can fit and inspect the estimate, but do not report an interval for it yet. None of this implies multiple or labelled structured slopes, non-Gaussian structural effects outside the exact model-specific support named above, or predictor-dependent corpair() regressions unless the route table explicitly names that support.

Known sampling covariance belongs to the meta-analysis route, not relmat(). Use relmat() for latent random-effect relatedness matrices; use meta_V(V = V) and the meta-analysis documentation when the covariance matrix describes known observation-level sampling error.

With one or more structured fits in hand, the next stage in the reader path is checking whether they are trustworthy and comparing candidates: continue with Model selection with AIC and BIC.

Working in Julia? The DRModels.jl companion page mirrors this article with Julia syntax and states which parts DRModels.jl supports today. DRModels.jl is a separate package with its own fitting and inference routes; Julia is optional for drmTMB users.