---
title: "Structural dependence overview"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Structural dependence overview}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

<style>
@media (max-width: 575.98px) {
  main h1 {
    hyphens: none;
    overflow-wrap: normal;
    word-break: normal;
  }

  main table {
    display: block;
    max-width: 100%;
    overflow-x: auto;
  }
}
</style>

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](location-scale.html), 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)`, `spatial(1 + depth | site, coords = coords)`, or the fixed-kappa mesh intercept | 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, fixed-kappa Gaussian `mu` intercept at local-fit level. 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. Mesh slopes/range and other mesh fields, additional multiple or labelled coordinate-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](https://itchyshin.github.io/drmTMB/articles/phylogenetic-spatial.html)
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](animal-models.html) when your
first question is specifically about `animal()`, `pedigree`, `A`, or `Ainv`.
Read [phylogenetic structured effects](phylogenetic-models.html) when your
first question is specifically about `phylo()`, tree-based covariance,
`sd_phylo*()`, or phylogenetic `corpair()` rows.
Read [two-tree phylogenetic interactions](bipartite-phylogenetic-interactions.html)
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](spatial-models.html) 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](relmat-known-matrices.html) 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](formula-grammar.html) when you want the compact
implemented-versus-planned syntax table. Read the
[figure gallery](https://itchyshin.github.io/drmTMB/articles/figure-gallery.html) 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](meta-analysis.html)
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](model-selection.html).