Spatial random field: lme4-bar mode-dispatch wrapper

spatial() is a unified entry point for the package's five canonical spatial keywords (spatial_scalar, spatial_unique, 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 five canonical 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)

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 of spatial_unique.
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" / "diag" / "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.

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 = "diag")`	(mandatory)	`spatial_unique(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 "diag" / "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 of spatial_unique(0 + trait | coords) (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().

Augmented LHS (Stage 3, not yet shipped)

Augmented LHS forms — 1 + x (intercept + slope), 0 + trait + (0 + trait):x (per-trait intercepts + per-trait slopes on covariate x), x || coords (uncorrelated) — are reserved for Design 07 Stage 3 engine work. The parser currently raises an error pointing at this status.

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)
# Per-trait independent fields on shared mesh (= spatial_unique)
fit_u <- gllvmTMB(value ~ 0 + trait +
                    spatial(0 + trait | coords, mode = "diag",
                            mesh = mesh),
                  data = df)
# 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)
# Backward-compat: legacy bare-formula form
fit_legacy <- gllvmTMB(value ~ 0 + trait + spatial(0 + trait | coords),
                       data = df, mesh = mesh)
} # }

Form	Mode default	Rewrites to
`spatial(1 \\| site)`	`"scalar"`	`spatial_scalar(0 + trait \\| coords)`
`spatial(0 + trait \\| coords, mode = "diag")`	(mandatory)	`spatial_unique(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)`