Spatial structured-effect marker

spatial() marks structured spatial dependence. The supported base model is the univariate Gaussian location random intercept spatial(1 | site, coords = coords), where coords is a matrix or data frame with one row per site or one row per observation. The univariate Gaussian location path also supports one numeric slope, spatial(1 + x | site, coords = coords), as independent intercept and slope fields with separate SDs and no intercept-slope correlation. Matching labelled bivariate Gaussian mu1/mu2 terms fit the supported q=2 coordinate-spatial location covariance, matching univariate Gaussian mu and sigma intercept terms fit one spatial mean-scale correlation, and matching labelled all-four mu1/mu2/sigma1/sigma2 terms fit the supported constant q=4 location-scale block. Fitted non-Gaussian spatial routes cover the univariate student mu q=1 intercept or one-slope, ordinary Poisson and NB2 mu q=1 intercepts or one-slopes, zero-inflated Poisson zi q=1 intercept, and the NB2 sigma q=1 one-slope, all at recovery grade: trust the point estimate, not the interval.

Usage

spatial(term, coords = NULL, mesh = NULL)

Arguments

term

Structured random-effect term, such as 1 | site.

coords

Coordinate object, such as a data frame or matrix of spatial coordinates.

mesh

A fixed-kappa mesh object from make_mesh(). Fitted only for the univariate Gaussian mu intercept with sigma ~ 1 and the native Binomial mu spatial intercept or slope routes; see Description.

Value

A formula marker; never evaluated by users.

Details

A precomputed mesh from make_mesh() is fitted for two routes only, with kappa fixed at the value given to make_mesh(). The first is a univariate Gaussian, unlabelled mu intercept with constant residual scale, bf(y ~ x + spatial(1 | site, mesh = mesh), sigma ~ 1); its point estimates have recovery evidence for the tested designs, and intervals, coverage, and the spatial range are not claimed. The second is the native Binomial mu spatial intercept across logit, probit, and complementary log-log links. Native Binomial mesh slopes also support coefficient-specific predictor-dependent SD formulas for logit, probit, and complementary log-log links, for example spatial(0 + x | site, mesh = mesh) with sd(site, level = "spatial", coef = "x") ~ z. All three links have focused point-recovery checks; the logit route also has output-workflow checks. No interval-coverage or Julia parity claim is made. Any other mesh use, including sigma ~ z with a Gaussian mesh term, a Gaussian mesh slope, a labelled or bivariate mesh term, or another non-Gaussian family, is rejected; use coords = coords for those models where a coordinate route exists. Multiple structured slopes, residual-scale structured slopes beyond the supported NB2 slope, slope correlations, and predictor-dependent spatial corpair() regression are not supported.

The coords = route fits an exponential kernel, exp(-dist / range), with range fixed at the median positive pairwise distance between sites (the value drm_spatial_coords_precision() computes). The range is not estimated: only the sill (the spatial SD) and the residual nugget are estimated, so a fit can have a lower log-likelihood than a model that also estimates the range. If you need a different range or kernel, build the covariance yourself and pass it through relmat() with K =, which is the more flexible route. DRModels.jl (the Julia twin) estimates the range, so the twin spatial() fits of the same formula differ.

Examples

# Fitted for univariate Gaussian mu with coords:
bf(y ~ x + spatial(1 | site, coords = coords), sigma ~ z)
#> <drm_formula>
#> y ~ x + spatial(1 | site, coords = coords)
#> sigma ~ z
# Supported q=2 bivariate spatial location block:
bf(
  mu1 = y1 ~ x + spatial(1 | p | site, coords = coords),
  mu2 = y2 ~ x + spatial(1 | p | site, coords = coords),
  sigma1 = ~ 1,
  sigma2 = ~ 1,
  rho12 = ~ 1
)
#> <drm_formula>
#> mu1 = y1 ~ x + spatial(1 | p | site, coords = coords)
#> mu2 = y2 ~ x + spatial(1 | p | site, coords = coords)
#> sigma1 = ~1
#> sigma2 = ~1
#> rho12 = ~1
# Fixed-kappa mesh intercept (mesh from make_mesh()); requires sigma ~ 1:
bf(y ~ x + spatial(1 | site, mesh = mesh), sigma ~ 1)
#> <drm_formula>
#> y ~ x + spatial(1 | site, mesh = mesh)
#> sigma ~ 1
# Native Binomial logit mesh slope with a predictor-dependent SD:
bf(
  y ~ x + spatial(0 + x | site, mesh = mesh),
  sd(site, level = "spatial", coef = "x") ~ z
)
#> <drm_formula>
#> y ~ x + spatial(0 + x | site, mesh = mesh)
#> sd(site, level = "spatial", coef = "x") ~ z