Spatially-Varying Coefficients (SVC)

Specify spatially-varying coefficients for ratio models. SVCs allow regression coefficients to vary smoothly across space using a Gaussian process prior. This captures local effects that may differ from global relationships.

Uses Nearest Neighbor Gaussian Process (NNGP) approximation for computational efficiency with large datasets.

Usage

spatial_svc(
  coords,
  terms = 1,
  cov = c("exponential", "matern", "gaussian", "spherical"),
  nn = 15,
  shared = TRUE,
  scale_coords = TRUE,
  approx = c("nngp", "hsgp"),
  m = 6,
  c_boundary = 1.5
)

Arguments

coords

A one-sided formula specifying coordinate columns (e.g., ~ lon + lat), or a character vector of length 2 with column names.

terms

Which coefficients should vary spatially. Options:

Integer vector: Column indices of design matrix (1 = intercept)
Character vector: Coefficient names (e.g., "(Intercept)", "depth")
Formula: ~ 1 + depth for intercept and depth

cov

Covariance function: "exponential" (default), "matern", "gaussian", or "spherical".

nn

Number of nearest neighbors for NNGP approximation. Default 15. Larger values give better approximation but slower computation.

shared

Logical; if TRUE (default), SVC effects enter both numerator and denominator. Set to FALSE for process-specific SVCs (triggers warning about potential confounding).

scale_coords

Logical; if TRUE (default), coordinates are scaled to unit variance before computing distances.

approx

Spatial GP approximation. One of "nngp" (default, Nearest Neighbor GP) or "hsgp" (Hilbert Space GP, basis-function approximation suitable for moderate N with strong smoothness).

m

Number of basis functions per coordinate for HSGP (used only when approx = "hsgp"). Default 6.

c_boundary

Boundary scaling factor for HSGP. The HSGP domain is extended to c_boundary times the half-range of scaled coordinates. Default 1.5.

Value

A ratiod_svc object

Details

The SVC model extends the linear predictor:

$$\eta(s) = X\beta + \tilde{X}(s)w(s)$$

where:

$\beta$ are global (non-spatial) coefficients
$\tilde{X}(s)$ is the subset of covariates with SVCs
$w(s)$ are spatially-varying adjustments at location s

Each SVC follows an independent Gaussian process: $$w_j(s) \sim GP(0, \sigma^2_j \cdot C(\phi_j))$$

where $C(\phi)$ is the correlation function with range parameter $\phi$.

NNGP approximation: For computational tractability, we use the Nearest Neighbor Gaussian Process (Datta et al., 2016), which conditions each location on its k nearest neighbors. This reduces complexity from O(n^3) to O(n*k^2), enabling models with thousands of locations.

Interpretation: A positive SVC for depth at location s means the depth effect is stronger at s than the global average. The spatial variance $\sigma^2_j$ quantifies how much the effect varies across space.

References

Datta, A., Banerjee, S., Finley, A. O., & Gelfand, A. E. ( 2016). Hierarchical nearest-neighbor Gaussian process models for large geostatistical datasets. Journal of the American Statistical Association, 111(514), 800-812.

Examples

# Create SVC specification
svc_spec <- spatial_svc(~ lon + lat, terms = 1)
print(svc_spec)
#> tulpaRatio spatially-varying coefficients
#> =====================================
#> 
#> Coordinates: lon, lat 
#> Covariance: exponential 
#> Neighbors (NNGP): 15 
#> Shared: Yes (enters both processes) 
#> 
#> Terms: columns  1 

if (FALSE) { # \dontrun{
# Generate synthetic spatial data (not run - SVC not fully supported)
set.seed(202)
n <- 40
df <- data.frame(
  lon = runif(n, 0, 10),
  lat = runif(n, 0, 10),
  depth = rnorm(n),
  temp = rnorm(n),
  count = rpois(n, 20),
  effort = rgamma(n, shape = 4, rate = 1)
)

# Spatially-varying intercept (random spatial field)
fit <- tratio(
  count | effort ~ depth,
  data = df,
  family = ratiod_poisson_gamma(),
  svc = spatial_svc(~ lon + lat, terms = 1),
  control = list(iter = 200, warmup = 100, chains = 1)
)
summary(fit)

# Extract and plot the spatially-varying coefficients
svc_effects <- svc(fit)
plot(svc_effects, "depth")
} # }