Per-trait spatial marginal field: spatial_indep(0 + trait | coords)

Canonical name for T per-trait spatial fields coupled by the SPDE precision matrix \(\mathbf Q\); standalone = T univariate spatial fits stacked.

Usage

spatial_indep(formula, coords = NULL, mesh = NULL, common = FALSE, rho = 1)

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.

common

FALSE (default) for a separate spatial-field variance per trait; TRUE ties all traits to one shared spatial variance (intercept-only). spatial_indep(0 + trait | coords, common = TRUE) is the canonical one-shared-variance spelling and fits the same model as the soft-deprecated spatial_scalar().

rho

Source-strength attenuation between 0 and 1, or NULL to estimate it in a complete replicated multivariate Gaussian model without competing covariance. Omitted or explicit 1 preserves the existing model. Range remains a separate estimated parameter. Attenuation preserves the projected marginal variance at each modeled location and applies to the whole trait covariance, including Psi. The grouping column must identify locations consistently across replicates. Estimated latent models require rank one and at least four traits. The frozen spatial study found no passing recovery cell (14 partial and 2 blocked); rho intervals remain unvalidated. new-location prediction is not supported for attenuated models.

Value

A formula marker; never evaluated.

Details

Each trait \(t\) gets its own variance \(\tau^2_t\) on a Matern \(\nu = 1\) GMRF, with a shared range parameter \(\kappa\).

Use spatial_indep() for an explicit marginal-only spatial fit (no cross-trait spatial decomposition). Use spatial_latent() for K shared spatial fields driving all T traits via a T x K loading matrix.

Formula orientation

Same convention as the rest of the spatial_* keywords: the canonical orientation is 0 + trait | coords (LHS = trait factor, RHS = the coords placeholder). Spatial keywords adopted this orientation at gllvmTMB 0.1.4; spatial_indep is born with it (no legacy coords | trait orientation is accepted).

Mutual exclusion with spatial_latent()

Combining spatial_indep(0 + trait | coords) with spatial_latent(0 + trait | coords, d = K) is over-parameterised and the parser raises a cli::cli_abort().

See also

spatial_latent(), indep(), phylo_indep(), extract_Sigma().

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
  )
  mesh <- make_mesh(sim$data, c("lon", "lat"), cutoff = 0.1)
  fit <- gllvmTMB(
    value ~ 0 + trait +
            spatial_indep(0 + trait | site, mesh = mesh),
    data  = sim$data,
    trait = "trait",
    unit  = "site"
  )
} # }