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,
range = svc_default_range(),
parameterization = c("noncentered", "centered")
)
# S3 method for class 'ratiod_svc'
print(x, ...)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 + depthfor 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.
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_boundarytimes the half-range of scaled coordinates. Default 1.5.- range
Prior range for the SVC range parameter \(\phi\) as
c(lower, upper), in the units of the scaled coordinates. The prior is uniform on that interval and the density is-Infoutside it, so a posterior that piles up against either end is reporting that the data want a range the interval excludes. Defaultc(0.3, 30). Applies toapprox = "nngp"; the HSGP arm carries a LogNormal(0, 1) prior on its lengthscale instead and rejects arangeset here.- parameterization
Coordinate each NNGP term is sampled in.
"noncentered"(default) samples \(z_j \sim N(0, I)\) and builds \(w_j = L(\sigma^2_j, \phi_j) z_j\) through the NNGP autoregression, so the variance reaches the field through the transform rather than through the prior's quadratic form."centered"samples the field \(w_j\) directly under its NNGP prior, where the field's level and \(\sigma^2_j\) form a funnel that mixes slowly on small data. Both place the same prior on \(w_j\). Applies toapprox = "nngp"; the HSGP arm already samples standardised basis coefficients.- x
A ratiod_svc object
- ...
Ignored
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.
See also
spatial_car(), spatial_bym2() for areal spatial effects,
svc() for extracting SVC posteriors
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)
#> Range prior: [0.3, 30]
#>
#> Terms: columns 1
# \donttest{
# Generate synthetic spatial data
set.seed(202)
n <- 30
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(),
spatial = spatial_svc(~ lon + lat, terms = 1),
control = list(iter = 200, chains = 1, seed = 1)
)
summary(fit)
#> ratio model summary
#> ===================
#>
#> Inference: Exact (Tier 1) via hmc
#> Family: poisson_gamma
#>
#> Fixed effects (numerator):
#> parameter mean sd 2.5% 97.5% rhat ess_bulk
#> num:(Intercept) 2.907 0.049 2.811 2.989 0.995 152
#> num:depth -0.032 0.046 -0.109 0.040 0.994 87
#>
#> Fixed effects (denominator):
#> parameter mean sd 2.5% 97.5% rhat ess_bulk
#> denom:(Intercept) 1.473 0.096 1.306 1.658 1.057 16
#> denom:depth 0.070 0.108 -0.143 0.285 1.053 102
#>
#> Variance components:
#> parameter mean sd 2.5% 97.5% rhat ess_bulk
#> shape 4.683 1.068 2.709 7.061 1.061 77
#> sigma2_svc[1] 0.243 0.275 0.013 1.095 1.059 28
#>
#> Other parameters:
#> parameter mean sd 2.5% 97.5% rhat ess_bulk
#> phi_svc[1] 19.187 7.757 3.350 29.286 0.992 76
#> svc[1,10] 0.039 0.088 -0.117 0.207 1.046 93
#> svc[1,11] -0.099 0.083 -0.272 0.042 1.027 47
#> svc[1,12] -0.077 0.065 -0.254 0.062 1.000 80
#> svc[1,13] -0.083 0.068 -0.243 0.033 1.004 79
#> svc[1,14] 0.082 0.099 -0.057 0.277 1.069 25
#> svc[1,15] -0.136 0.118 -0.430 0.033 0.999 82
#> svc[1,16] 0.029 0.066 -0.071 0.151 1.004 80
#> svc[1,17] 0.007 0.070 -0.134 0.150 1.015 70
#> svc[1,18] -0.004 0.090 -0.185 0.180 1.000 102
#> svc[1,19] 0.024 0.080 -0.161 0.187 0.991 108
#> svc[1,1] 0.002 0.085 -0.184 0.166 0.999 78
#> svc[1,20] 0.022 0.078 -0.115 0.179 1.022 65
#> svc[1,21] 0.007 0.078 -0.125 0.174 1.013 81
#> svc[1,22] 0.059 0.098 -0.125 0.242 1.035 85
#> svc[1,23] 0.005 0.075 -0.155 0.114 1.030 85
#> svc[1,24] 0.014 0.081 -0.149 0.179 0.994 86
#> svc[1,25] -0.001 0.075 -0.123 0.189 1.051 77
#> svc[1,26] 0.065 0.088 -0.141 0.229 1.000 77
#> svc[1,27] 0.051 0.065 -0.056 0.202 0.993 109
#> svc[1,28] -0.046 0.081 -0.188 0.133 1.011 94
#> svc[1,29] 0.078 0.131 -0.154 0.328 0.991 86
#> svc[1,2] 0.047 0.090 -0.089 0.228 1.012 71
#> svc[1,30] 0.028 0.086 -0.180 0.191 0.996 144
#> svc[1,3] -0.090 0.082 -0.248 0.052 1.004 79
#> svc[1,4] -0.087 0.070 -0.215 0.046 1.003 65
#> svc[1,5] 0.070 0.082 -0.061 0.248 1.008 76
#> svc[1,6] 0.088 0.085 -0.050 0.255 1.000 90
#> svc[1,7] -0.077 0.064 -0.207 0.052 1.006 71
#> svc[1,8] 0.043 0.086 -0.112 0.215 1.012 74
#> svc[1,9] -0.058 0.091 -0.230 0.109 0.990 85
#>
#> Diagnostics:
#> Divergences: 0
#> Avg. acceptance: 0.917
#> Chains: 1
#> Iterations: 200
#> Warmup: 100
#> R-hat > 1.01 for 16 parameter(s), largest 1.069 (svc[1,14]).
#> Bulk ESS < 100 for 31 parameter(s), smallest 16 (denom:(Intercept)).
#> Run longer chains or reparameterise before using these estimates.
# Extract and plot the spatially-varying coefficients
svc_effects <- svc(fit)
plot(svc_effects)
# }