Per-trait independent spatial random fields: spatial_unique(0 + trait | coords)

Usage

spatial_unique(formula, coords = NULL, mesh = NULL)

Arguments

formula

0 + trait | coords style formula (LHS is the trait factor 0 + trait; RHS is the coords placeholder symbol that points at the make_mesh() coordinate columns).

coords

Character; the column-name pair of spatial coordinates in data (e.g. c("lon", "lat")). Resolved by the parser when supplied as keyword argument; NULL when the orientation expresses the coordinates via the formula RHS.

mesh

An fmesher mesh object built via make_mesh(). It may be supplied here or through the top-level mesh = argument to gllvmTMB(). The engine does not construct a mesh automatically from coords.

Value

A formula marker; never evaluated.

Details

spatial_unique() is soft-deprecated as compatibility syntax in gllvmTMB 0.2.0. Use spatial_indep() for standalone marginal diagonal spatial fields. Paired explicit-Psi use remains accepted; new decomposition code can use spatial_latent() with unique = TRUE.

Canonical name for the SPDE / GMRF Matern spatial random field with one independent field per trait (per-trait variance \(\tau^{2}_t\), shared range parameter \(\kappa\)). This is the "unique-rank" cell of the spatial column of the API grid.

Formerly spde(0 + trait | coords) and spatial(0 + trait | coords) – same engine, new name. See spde() for the technical details on the Matern \(\nu = 1\) kernel.

Compare to spatial_indep() with common = TRUE (one shared variance across traits) and spatial_latent() (K-dim spatial latent factors with a loading matrix).

Formula orientation

The canonical orientation is 0 + trait | coords (LHS = trait factor, RHS = the coords placeholder), parallel to latent(), unique(), and glmmTMB's gau(0 + trait | pos) / exp(0 + trait | pos). The earlier orientation coords | trait is accepted as a deprecated alias: it emits a one-shot lifecycle::deprecate_warn() per session (introduced at gllvmTMB 0.1.4) and is internally normalised to the canonical orientation, so existing fits remain byte-identical.

See also

spatial_indep(), spatial_latent(), spde() (deprecated alias).

Examples

sim <- simulate_site_trait(
  n_sites = 30, n_species = 6, n_traits = 3, mean_species_per_site = 5,
  spatial_range = 0.4, sigma2_spa = rep(0.5, 3), seed = 1
)
mesh <- make_mesh(sim$data, c("lon", "lat"), cutoff = 0.1)
# env_1 and env_2 are the simulated site covariates.
# \donttest{
fit <- gllvmTMB(
  value ~ 0 + trait + (0 + trait):(env_1 + env_2) +
          spatial_indep(0 + trait | coords, mesh = mesh),
  data  = sim$data,
  trait = "trait",
  unit  = "site"
)
# }