Skip to contents

One shared spatial-field variance across traits: spatial_scalar(0 + trait | coords)

Source: R/brms-sugar.R
spatial_scalar.Rd

Canonical name for the SPDE / GMRF Matern spatial random field with one shared variance \(\tau^{2}\) across all traits and a shared range parameter \(\kappa\). Each trait carries its own independent field draw on the mesh, but every trait's field has the same marginal variance and the same correlation length. Implementation: the same SPDE engine as spatial_unique(), with the per-trait log_tau_spde parameters tied via TMB's map mechanism so they collapse to a single estimable scalar.

Usage

spatial_scalar(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).

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

Optional fmesher mesh object built via make_mesh(). If NULL, the engine constructs a default mesh from coords.

Value

A formula marker; never evaluated.

Details

Use this when domain knowledge (or parsimony) says all traits should share the same amount of spatial structure. Compare to spatial_unique() (D independent variances) and spatial_latent() (K-dim factor decomposition).

Formula orientation

The canonical orientation is 0 + trait | coords (parallel to latent() / unique() and glmmTMB's spatial keywords). The earlier orientation coords | trait is accepted as a deprecated alias and emits a one-shot lifecycle::deprecate_warn() per session (introduced at gllvmTMB 0.1.4).

See also

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

Examples

if (FALSE) { # \dontrun{
  sim <- simulate_site_trait(
    n_sites = 20, n_species = 4, mean_species_per_site = 4,
    spatial_range = 0.4, sigma2_spa = rep(0.3, 4), seed = 1
  )
  fit <- gllvmTMB(
    value ~ 0 + trait +
            spatial_scalar(0 + trait | site, coords = c("lon", "lat")),
    data = sim$data
  )
} # }