BYM2 spatial structure — spatial

Specify a Besag-York-Mollie 2 (BYM2) spatial random effect. BYM2 decomposes the spatial effect into a structured (ICAR) component and an unstructured (IID) component, with a mixing parameter controlling the proportion of variance attributable to spatial structure.

BYM2 is preferred over plain CAR when you want to:

Distinguish structured vs unstructured spatial variation
Have an interpretable spatial fraction parameter
Use the scaling from Riebler et al. (2016)

Usage

spatial_bym2(
  adjacency,
  level = c("group", "obs"),
  group_var = NULL,
  shared = TRUE,
  scale_factor = NULL,
  parameterization = c("standard", "collapsed")
)

Arguments

adjacency

Adjacency matrix (sparse or dense). A symmetric matrix where entry (i,j) is 1 if areas i and j are neighbors, 0 otherwise.

level

Level at which spatial structure applies:

"group": Spatial effect at the grouping variable level (e.g., sites). Requires group_var to be specified.
"obs": Spatial effect at the observation level.

group_var

Name of the grouping variable in data (required if level = "group").

shared

Logical; if TRUE (default), spatial effect enters both numerator and denominator linear predictors identically.

scale_factor

Scaling factor for the ICAR component. If NULL (default), computed from the adjacency matrix following Riebler et al.

parameterization

Parameterization of the spatial random effect. Either "standard" (default) or "collapsed" to marginalize the spatial variance for improved mixing in sparse-graph regimes.

Value

A ratiod_spatial object

References

Riebler, A., Sorbye, S. H., Simpson, D., & Rue, H. (2016). An intuitive Bayesian spatial model for disease mapping that accounts for scaling. Statistical Methods in Medical Research, 25(4), 1145-1165.

Examples

# Create adjacency matrix for 10 regions (chain structure)
adj <- matrix(0, 10, 10)
for (i in 1:9) {
  adj[i, i+1] <- adj[i+1, i] <- 1
}

# Create BYM2 spatial structure
bym2 <- spatial_bym2(adj, level = "group", group_var = "region")
print(bym2)
#> tulpaRatio spatial specification
#> ===========================
#> 
#> Type: BYM2 
#> Level: group 
#> Spatial units: 10 
#> Shared: Yes (enters both processes) 
#> Group variable: region 
#> Scale factor: 1.2915 

if (FALSE) { # \dontrun{
# Generate synthetic epidemiological data (not run - requires laplace backend)
set.seed(456)
n_regions <- 10
epi_data <- data.frame(
  region = factor(1:n_regions),
  age = rnorm(n_regions, 50, 10),
  cases = rbinom(n_regions, size = 100, prob = 0.15),
  population = rep(100L, n_regions)
)

# Disease mapping with BYM2 spatial smoothing
fit <- tratio(
  cases | population ~ age,
  spatial = spatial_bym2(adj, level = "group", group_var = "region"),
  data = epi_data,
  family = ratiod_binomial(),
  mode = "laplace"
)
summary(fit)
} # }