Deprecated alias for one shared spatial-field variance

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: 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_scalar() is soft-deprecated compatibility syntax in gllvmTMB 0.2.0. Write spatial_indep(0 + trait | coords, common = TRUE) in new code. The two spellings fit the same SPDE / GMRF Matérn model 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_indep(), with the per-trait log_tau_spde parameters tied via TMB's map mechanism so they collapse to a single estimable scalar.

Use spatial_indep(..., common = TRUE) when domain knowledge (or parsimony) says all traits should share the same amount of spatial structure. Omit common = TRUE for separate trait-specific spatial variances, or use spatial_latent() for a reduced-rank cross-trait decomposition.

Formula orientation

The canonical orientation is 0 + trait | coords (parallel to latent() / indep() 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).

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, common = TRUE),
  data  = sim$data,
  trait = "trait",
  unit  = "site"
)
# }