Spatial random field: lme4-bar mode-dispatch wrapper

spatial() is a unified entry point for the package's four taught spatial modes (spatial_scalar, spatial_indep, spatial_latent, spatial_dep). It accepts an lme4-bar formula on the first argument and dispatches to the appropriate canonical keyword based on the LHS shape and the optional mode = ... argument. The four current keywords stay first-class – spatial() is an additive alias matching the lme4 / brms / drmTMB convention.

Usage

spatial(
  formula,
  mesh = NULL,
  coords = NULL,
  mode = NULL,
  d = 1,
  unique = FALSE
)

Arguments

formula: An lme4-bar formula. The bar's RHS is the spatial coordinate placeholder (typically coords or site); the LHS determines the covariance structure (combined with mode, see Dispatch rules). For backward compatibility, 0 + trait | coords and coords | trait (no mode) also work as deprecated aliases for the per-trait diagonal spatial field.
mesh: A fmesher mesh constructed via make_mesh(). Canonical. Required for the new dispatch path; optional for the legacy bare-formula form (where the mesh is passed at the top level of gllvmTMB()).
coords: Optional, retained as a hint of which coordinate columns correspond to the spatial grouping. The mesh actually used is whatever is passed to the mesh argument of gllvmTMB() or this function.
mode: One of "scalar" / "indep" / "latent" / "dep". Optional when LHS is 1 (defaults silently to "scalar"). Mandatory when LHS is 0 + trait.
d: Latent rank for mode = "latent". Default 1.
unique: Logical; forwarded to spatial_latent() when mode = "latent". The default FALSE keeps the low-rank-only path.

Value

A formula marker; never evaluated.

Details

This is the spatial parallel of the phylo() mode-dispatch wrapper: same dispatch logic, different engine slots (SPDE Matern instead of Hadfield A^-1).

Dispatch rules

Form	Mode default	Rewrites to
`spatial(1 \\| site)`	`"scalar"`	`spatial_scalar(0 + trait \\| coords)`
`spatial(0 + trait \\| coords, mode = "indep")`	(mandatory)	`spatial_indep(0 + trait \\| coords)`
`spatial(0 + trait \\| coords, mode = "latent", d = K)`	(mandatory)	`spatial_latent(0 + trait \\| coords, d = K)`
`spatial(0 + trait \\| coords, mode = "dep")`	(mandatory)	`spatial_dep(0 + trait \\| coords)`

When the LHS expands to a single column (1, intercept-only), mode is degenerate: it defaults silently to "scalar", and explicit mode = "scalar" is accepted (no warning). When the LHS is 0 + trait, mode is mandatory – choosing between "indep" / "latent" / "dep" is a meaningful decision (per-trait marginal vs reduced-rank decomposition vs full unstructured) and the parser refuses to silently default.

Backward compatibility

Legacy bare-formula calls spatial(0 + trait | coords) and spatial(coords | trait) (no mode argument) continue to work as deprecated aliases for the per-trait diagonal spatial field (with an additional orientation-flip lifecycle warning for the pre-0.1.4 orientation). The legacy form rewrites to spde() internally, picking up the SPDE mesh from the top-level mesh = argument to gllvmTMB().

Intercept-and-slope terms

The unified spatial() wrapper is limited to intercept-only trait covariance. For an intercept and slope, use an explicit structured mode such as spatial_indep(), spatial_latent(), or spatial_dep(); unsupported LHS forms fail with a message showing the accepted syntax.

Cross-package coexistence

drmTMB also exposes spatial(1 | site, mesh = mesh) with the same SPDE Matern internal path. Both packages share the same calling convention; user muscle memory transfers.

Examples

if (FALSE) { # \dontrun{
library(fmesher)
# Single shared spatial-field variance (= spatial_scalar)
fit_s <- gllvmTMB(value ~ 0 + trait + spatial(1 | site, mesh = mesh),
                  data  = df,
                  trait = "trait",
                  unit  = "site")
# Per-trait independent fields on a shared mesh
fit_u <- gllvmTMB(value ~ 0 + trait +
                    spatial(0 + trait | coords, mode = "indep",
                            mesh = mesh),
                  data  = df,
                  trait = "trait",
                  unit  = "site")
# Reduced-rank shared spatial latent factors (= spatial_latent)
fit_l <- gllvmTMB(value ~ 0 + trait +
                    spatial(0 + trait | coords, mode = "latent",
                            d = 2, mesh = mesh),
                  data  = df,
                  trait = "trait",
                  unit  = "site")
# Backward-compat: legacy bare-formula form
fit_legacy <- gllvmTMB(value ~ 0 + trait + spatial(0 + trait | coords),
                       data  = df,
                       trait = "trait",
                       unit  = "site",
                       mesh  = mesh)
} # }

Form	Mode default	Rewrites to
`spatial(1 \\| site)`	`"scalar"`	`spatial_scalar(0 + trait \\| coords)`
`spatial(0 + trait \\| coords, mode = "indep")`	(mandatory)	`spatial_indep(0 + trait \\| coords)`
`spatial(0 + trait \\| coords, mode = "latent", d = K)`	(mandatory)	`spatial_latent(0 + trait \\| coords, d = K)`
`spatial(0 + trait \\| coords, mode = "dep")`	(mandatory)	`spatial_dep(0 + trait \\| coords)`