Articles • gllvmTMB

Getting started

Get started with gllvmTMB: Fit the smallest Gaussian multivariate model, inspect numerical health, and read covariance before moving to a specialist guide.
Current limitations and boundaries: Decide which gllvmTMB models and results are ready for your analysis, which remain experimental, and what to check before interpretation.
Function map and cheat sheet: Find the documented function for preparing, fitting, checking, interpreting, or reporting a stacked-trait GLLVM.

General model guides

Reusable multivariate models and methods, starting with continuous Gaussian traits before choosing a response-specific observation model.

Individual morphometrics: the simplest GLLVM: Use when continuous traits are measured once per individual; fit a Gaussian latent covariance and compare it with known simulation truth.
Behavioural syndromes in repeated measurements: Use repeated Gaussian behaviours to separate stable between-individual covariance from within-occasion covariance and point repeatability.
Behavioural reaction norms with random slopes: Use repeated Gaussian behaviours across an observed environment to estimate individual intercept-slope covariance and trait-specific reaction norms.
Temporal covariance for repeated multivariate measurements: Choose AR1 or OU covariance for repeatedly measured Gaussian traits, then fit a standalone temporal model in long or traits(…) wide data.
How many latent dimensions should I fit?: Compare predeclared Gaussian latent ranks with ML information criteria and fit-health checks, then refit the selected covariance model deliberately.
Explaining Latent Ecological Axes With Predictors: Relate an observed environmental gradient to a shared latent ecological axis, then interpret the rotation-invariant trait-scale effect.
Explore loading constraints with suggest_lambda_constraint(): Explore pre-specified and data-derived loading constraints without turning selected pins into biological hypotheses.
Cross-family correlations and environmental predictors: Fit one predictor-informed latent model across five response families, use one seeded known-truth check, and interpret rotation-invariant trait effects.
Choose a response family: Match the response support and sampling process to a family before adding multivariate covariance, and stop at the documented specialist boundaries.
Unordered categories with multinomial(): Model an unordered categorical response as baseline-category log-odds, read its fixed-effect contrasts and probabilities, and distinguish the covered core from two partial covariance routes.
Multivariate spatial models with an SPDE mesh: Build a mesh, fit equivalent long- and wide-format Gaussian spatial models, interpret the practical range, and understand the current evidence boundary.
Handling missing data: Choose among omitted, retained, or explicitly modelled missing values: omitting and retaining reach the same estimates and differ in which rows you can predict, while modelling a missing predictor changes the estimand.
How strongly does a known source connect groups?: Separate source correlation from trait covariance using fixed attenuation and the admitted replicated Gaussian estimator.

Species distribution models

From a joint model of one community to integrated models that combine opportunistic records with designed surveys. The integrated route is experimental.

Start here: which species distribution model do your data allow?: The front door to the species distribution articles. Counts, binary records, and repeated surveys do not identify the same ecological quantity: this page separates relative intensity, occurrence or observation probability, and detection, then routes readers from their data to the right worked article or a better tool elsewhere.
Joint ecological intensity from opportunistic records: Fit a joint relative-intensity model to GBIF-style records alone — many species, one shared gradient, an effort offset and a named recording-bias covariate — and read exactly what presence-only data can and cannot say.
Joint species distribution models for binary occurrence data: Fit a binary latent-factor JSDM in long or wide form and interpret residual species co-occurrence on a declared liability scale.
When a rare species breaks the JSDM: A species recorded only at one end of a gradient can have no finite ML slope — complete separation. Certify the problem with screen_gllvmTMB() and keep the species with the opt-in MSPL estimator. A loading ridge does not fix this, and the two are never combined in one fit.
Integrating opportunistic records with a designed survey: a small worked example: Fit a presence-only portal stream and a repeated presence/absence survey in one likelihood through the ordinary gllvmTMB() call, and read what the shared spatial gradient and the portal-only bias term do and do not tell you.
What do repeated survey visits add to an integrated model?: Separate a poor visit from genuinely low ecological intensity: repeated survey visits with visit-varying conditions, fitted through the ordinary gllvmTMB() call, and the boundary between this route and a separate-detection occupancy model.
Integrating three data sources at once: portal, atlas, and survey: Declare several named observation sources with isdm_sources() — portal counts, digitised atlas records, a small detection survey — and fit one shared ecological process across all of them through the ordinary gllvmTMB() call.
A conceptual integrated SDM case study for twelve species: An evidence-backed case study of combining eBird-style opportunistic counts with a structured detection survey for a twelve-species songbird community when the sources share no locations. It covers choosing the number of shared spatial gradients, handling overdispersion, and interpreting a map that carries no uncertainty.
When one data source knows where it is and the other does not: Monitoring programmes often publish survey coordinates deliberately blurred to protect sensitive sites, while an eBird or GBIF record carries a GPS fix. If you fuse the two, you are reading your habitat raster at the wrong place for one of the arms - and that drags the estimated habitat effect toward zero, by 57-79% in the blurred arm here. The combined fit inherits that in proportion to how much of the data the blurred arm supplies. Whether it matters for you comes down to one ratio you can compute from your own raster. And the answer flips - the blurred arm becomes worth keeping - when the surrogate you use to model where people record is both imperfectly measured and correlated with habitat, which is the usual situation with real data.
How big does an integrated survey design need to be?: Audit the per-cell support of a presence-only plus structured-survey design before you fit it, then read a known-truth design curve showing that spatial replication pays only when per-cell information is held fixed.

Phylogenetic comparative models

Stacked-trait models that use a known phylogeny as a relationship source; this is not a general single-response comparative-methods guide.

Where does the tree go?: Worked examples for phylogenetic and ordinary covariance on distinct model axes.
Phylogenetic covariance among traits: Use replicated Gaussian species traits and a supplied tree to estimate phylogenetically structured covariance with explicit label and health checks.
Cross-lineage covariance in a plant--bumblebee example: Build one fixed cross-lineage kernel and read its plant-by-bumblebee trait covariance block, with an explicit point-estimate boundary.
Phylogenetic ordinal and nominal PGLMMs: Fit phylogenetic threshold and unordered-category models with ordinal_probit() and multinomial(), following Mizuno et al. (2025) J. Evol. Biol.

Concepts and diagnostics

Supporting concepts, syntax, and fit checks that readers use across all three model routes.

What is a site? The unit of analysis, and why you probably do not need a grid: A count needs a place and an amount of looking. That pair is the unit of analysis — usually an observation event such as a checklist or a station visit, not a grid cell. This page separates the three different things people call a ‘cell’, shows on toy data that a site’s label never enters a prediction, and says when gridding is a reasonable choice and what it costs.
gllvmTMB vocabulary: Look up the model terms, covariance pieces, grouping tiers, identifiability concepts, and uncertainty language used across the guides.
Covariance and correlation: the model behind Sigma: Use as a technical reference for Sigma, Lambda, Psi, liability-scale residual conventions, and the limits of covariance comparisons.
Formula keyword grid: Choose a correlation source and covariance mode, then translate the intended model into matching long and traits(…) wide formulas.
Response-specific predictor effects: Specify which predictors affect which responses, including intentional zero coefficients, without confusing fixed-effect structure with covariance constraints.
Screen binary traits before fitting: Check prevalence, sparse outcomes, duplicated cells, and usable denominators before fitting a binary multivariate model.
Can I trust this fit?: Inspect optimiser, gradient, Hessian, residual, and fitted-model predictive signals before interpreting covariance or uncertainty.
Convergence and hard fits: Diagnose a numerically difficult fit and compare start or optimiser strategies without turning a small criterion into a validity certificate.
Confidence intervals: what can I report?: Choose a profile, Wald, or bootstrap interval for a specific result, and keep the returned bounds separate from a general coverage claim.
Common pitfalls and how to avoid them: Troubleshoot six common data, formula, covariance, and interpretation mistakes with concrete long-format checks and examples.

Specialist methods and evidence

Specialist case studies and evidence notes, not a beginner route. The rare-binary example uses an opt-in experimental estimator; the checking guide explains what has and has not been evaluated; and the structured-slope page states its current evidence and limits.

Rare items and runaway estimates in Paper × Items evidence synthesis: Ordinate a papers-by-items evidence table with a probit GLLVM, then meet the two ways such fits break — runaway loadings and separated rare items — and the matched remedy for each: an opt-in loading ridge for one, the opt-in MSPL estimator for the other, never both in one fit.
Validation oracles: what an external package can and cannot check: Why an independent implementation is stronger evidence than simulation recovery alone, and a source-by-mode map of which gllvmTMB covariance cells have one, which have a weaker one, and which have none.
Structured random slopes for non-Gaussian traits