Specify a multi-scale spatial random effect that decomposes spatial variation into local (fine-scale) and regional (broad-scale) components. Each scale has its own range and variance parameters.
This is particularly useful for large datasets (>100k observations) where spatial patterns exist at multiple scales.
Usage
spatial_multiscale(
coords,
scales = c("local", "regional"),
range_local = c(0.01, 1),
range_regional = c(1, 10),
cov = c("exponential", "matern", "gaussian", "spherical"),
nu = 1.5,
nn_local = 10,
nn_regional = 30,
shared = TRUE,
scale_coords = TRUE,
sampler = c("auto", "noncentered", "centered", "interweaved", "adaptive", "riemannian",
"lbfgs")
)Arguments
- coords
A one-sided formula specifying coordinate columns (e.g.,
~ lon + lat), or a character vector of length 2 with column names.- scales
Character vector specifying scale names. Default:
c("local", "regional").- range_local
Prior range for local scale as
c(lower, upper)in coordinate units. Default:c(0.01, 1)(after scaling).- range_regional
Prior range for regional scale as
c(lower, upper). Default:c(1, 10)(after scaling).- cov
Covariance function:
"exponential"(default),"matern","gaussian", or"spherical".- nu
Smoothness parameter for Matern covariance.
- nn_local
Number of nearest neighbors for local scale. Default 10.
- nn_regional
Number of nearest neighbors for regional scale. Default 30.
Logical; if TRUE (default), spatial effects enter both numerator and denominator.
- scale_coords
Logical; if TRUE (default), coordinates are scaled to unit variance before computing distances.
- sampler
HMC sampler / parameterization strategy. One of
"auto"(default),"noncentered","centered","interweaved","adaptive","riemannian", or"lbfgs"."auto"selects based on identifiability diagnostics.
Details
The multi-scale model decomposes spatial variation additively:
$$\eta(s) = X\beta + w_{local}(s) + w_{regional}(s)$$
where each component follows an independent Gaussian process: $$w_{local}(s) \sim GP(0, \sigma^2_{local} C(\phi_{local}))$$ $$w_{regional}(s) \sim GP(0, \sigma^2_{regional} C(\phi_{regional}))$$
Identifiability: With sufficient data (>500 locations), the two scales are typically well-identified when prior ranges are non-overlapping. PC priors on variance components help prevent overfitting.
Computational cost: Approximately 1.5-2x the cost of single-scale GP, as two NNGP likelihoods must be evaluated.
See also
spatial_gp() for single-scale GP, temporal_multiscale() for
multi-scale temporal effects
Examples
# Create multi-scale spatial structure
ms <- spatial_multiscale(
~ lon + lat,
range_local = c(0.1, 0.5),
range_regional = c(1, 5)
)
print(ms)
#> tulpaRatio Multi-Scale spatial specification
#> ========================================
#>
#> Coordinates: lon, lat
#> Scales: local + regional
#>
#> Local scale:
#> Range prior: [0.1, 0.5]
#> Neighbors: 10
#>
#> Regional scale:
#> Range prior: [1, 5]
#> Neighbors: 30
#>
#> Covariance: exponential
#> Shared: Yes (enters both processes)
if (FALSE) { # \dontrun{
# Generate synthetic spatial data (not run - multiscale not fully supported)
set.seed(101)
n <- 60
df <- data.frame(
lon = runif(n, 0, 10),
lat = runif(n, 0, 10),
depth = rnorm(n),
temp = rnorm(n),
count = rpois(n, 30),
effort = rgamma(n, shape = 5, rate = 1)
)
# Multi-scale spatial with local and regional components
fit <- tratio(
count | effort ~ depth + temp,
data = df,
family = ratiod_poisson_gamma(),
spatial = spatial_multiscale(
~ lon + lat,
range_local = c(0.1, 0.5),
range_regional = c(1, 5)
),
control = list(iter = 200, warmup = 100, chains = 1)
)
summary(fit)
} # }