Structural dependence overview

Use this overview when observations, species, individuals, sites, or lines are not independent after the fixed effects have been included. The goal is to choose the structural layer that matches the scientific question before fitting a model.

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.

Pick the route

Question	Current route	Status
Do related individuals share additive genetic deviations?	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. Exact non-Gaussian gates fit ordinary Poisson/NB2 q1 animal mu intercept-plus-one-slope, recovery-grade NB2 q1 animal sigma, and the row-specific beta animal route recorded in the live ledger. Pedigree/Ainv bridge marshalling, sparse large-pedigree construction, additional multiple or labelled slope layouts outside the exact fitted ledger cells, and non-Gaussian neighbours outside those gates remain planned.
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. Exact non-Gaussian gates fit ordinary Poisson/NB2 q1 phylogenetic mu intercept-plus-one-slope and recovery-grade NB2 q1 phylogenetic sigma; Student-t q1 phylogenetic nu is diagnostic-only, while cumulative-logit q1 phylogenetic mu is diagnostic-only. Neighbouring non-Gaussian routes remain planned.
Do nearby sites share smooth deviations?	spatial(1 | site, coords = coords) or spatial(1 + depth | site, coords = coords)	Fitted for the documented coordinate-spatial Gaussian mu/sigma, slope, q2, and q4 routes. Exact non-Gaussian gates fit ordinary Poisson/NB2 q1 spatial mu intercept-plus-one-slope and recovery-grade NB2 q1 spatial sigma; Student-t q1 spatial mu is diagnostic-only for the intercept and recovery-grade for the intercept-plus-one-slope route. All three spatial-inflation gates—Poisson zi, fixed-zi Poisson mu, and fixed-zi NB2 mu—are diagnostic-only single-smoke routes. The spatial sigma-slope interval gate remains blocked; mesh/SPDE, additional multiple or labelled slope layouts outside the exact fitted ledger cells, non-Gaussian routes outside those exact gates, and spatial corpair() routes remain planned.
Does the same response need both species and site structure?	planned phylo() plus spatial() route	Planned. Fit separate sensitivity models for now; simultaneous structural layers need identifiability checks before use.
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. Exact non-Gaussian gates fit ordinary Poisson/NB2 q1 relmat mu intercept-plus-one-slope, recovery-grade NB2 q1 relmat sigma, Gamma q1 relmat mu, and truncated-NB2 q1 relmat hu. Additional multiple or labelled slope layouts outside the exact fitted ledger cells, broader K/Q bridge claims, predictor-dependent corpair() routes, and non-Gaussian neighbours outside those gates remain planned.

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

The fitted first slices are useful for applied work, but they are not full parity across every structural layer. A fitted q=2 location-location row means that two Gaussian response means can share a latent structured correlation for that layer. A fitted q=4 route means the all-four endpoint block named above is available for constant location-scale covariance. The univariate intercept route can also enter sigma for phylo(), spatial(), animal(), and relmat(). Exact q1 sigma one-slope routes also fit for all four providers: phylo, A-matrix animal, and K/Q relmat are inference-ready with caveats, while spatial remains point-fit/extractor only. These routes do not imply multiple or labelled structured slopes, non-Gaussian structural effects outside the exact row-specific gates 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.