Skip to contents

Bayesian CAR / BYM Disease Mapping with Climate Covariates

Source: R/sus_mod_spatial_bayes.R
sus_mod_spatial_bayes.Rd

Fits a Bayesian hierarchical spatial model for disease mapping using Conditional Autoregressive (CAR) priors implemented in the CARBayes package, or the reparameterised BYM2 model via INLA. Four model specifications are available: the Besag-York-Mollie (BYM) model with structured and unstructured random effects, the Leroux model with a mixing parameter for spatial dependence, the independent random effects model (all via CARBayes/MCMC), and the BYM2 model (via INLA with penalised complexity priors). Climate and environmental covariates stored in a climasus_df can be passed directly as fixed effects.

Usage

sus_mod_spatial_bayes(
  df,
  outcome,
  W,
  covariates = NULL,
  offset = NULL,
  family = c("poisson", "binomial", "gaussian"),
  model = c("bym", "leroux", "independent", "bym2"),
  n_iter = 10000L,
  burnin = 2000L,
  thin = 10L,
  prior_tau2 = c(1, 0.01),
  seed = 42L,
  lang = "pt",
  verbose = TRUE
)

Arguments

df

A data.frame or climasus_df at the aggregate pipeline stage. Must contain code_muni (7-digit IBGE code), the outcome column, all columns named in covariates, and optionally an offset column. Rows are sorted by code_muni internally to align with W.

outcome

Character. Name of the response variable column in df (e.g. "deaths", "hospitalizations").

W

A climasus_weights object produced by sus_mod_spatial_weights(). Must contain either a $W dense matrix or a $nb neighbour list from which a binary adjacency matrix is built.

covariates

Character vector of covariate column names in df to include as fixed effects. Default NULL (intercept-only model).

offset

Character. Name of an expected counts column in df (on the natural scale, not log-transformed). Used as log(offset) in the linear predictor for Poisson models. Default NULL.

family

Character. Response distribution. One of "poisson" (default), "binomial", or "gaussian". Note: "gaussian" is not supported for model = "bym2".

model

Character. Spatial model structure. One of:

  • "bym" (default) – Besag-York-Mollie model via CARBayes/MCMC.

  • "leroux" – Leroux CAR model via CARBayes/MCMC.

  • "independent" – Independent random effects via CARBayes/MCMC.

  • "bym2" – Reparameterised BYM2 model via INLA with penalised complexity priors. Requires the INLA package (not on CRAN; see https://www.r-inla.org/download-install).

n_iter

Positive integer. Total number of MCMC iterations (including burn-in). Used only for CARBayes models ("bym", "leroux", "independent"). Default 10000. Ignored for model = "bym2".

burnin

Positive integer. Number of initial MCMC iterations to discard as burn-in. Must be less than n_iter. Used only for CARBayes models. Default 2000. Ignored for model = "bym2".

thin

Positive integer. Thinning interval. Used only for CARBayes models. Default 10. Ignored for model = "bym2".

prior_tau2

Numeric vector of length 2. Shape and rate parameters of the Inverse-Gamma prior for the variance of spatial random effects. Used only for CARBayes models. Default c(1, 0.01) (weakly informative). Ignored for model = "bym2" (which uses PC priors instead).

seed

Integer. Random seed passed to base::set.seed() for reproducible MCMC (CARBayes models) or to INLA::inla.set.control.compute via inla.seed (BYM2). Default 42.

lang

Character. Language for CLI messages: "pt" (default), "en", "es".

verbose

Logical. If TRUE (default), print progress messages via cli.

Value

A named list of class c("climasus_spatial_bayes", "list") with slots $fixed (posterior fixed effects), $random (spatial random effects per municipality), $rr (posterior relative risk with 95\ credible intervals), $fitted (posterior mean fitted values), $dic (Deviance Information Criterion; for BYM2 a named numeric with both DIC and WAIC), $model, $family, $n_iter_effective, and $call.

Model specifications

Smoothed relative risks are computed as:

$$RR_i = \frac{\hat{Y}_i}{E_i}$$

where \(\hat{Y}_i\) are the posterior mean fitted counts and \(E_i\) are the expected counts (offset on the original scale). When no offset is supplied, \(E_i\) is set to the overall mean of the fitted values, which is equivalent to a standardised mortality/morbidity ratio. Credible intervals for the RR are derived from the 2.5th and 97.5th percentiles of the MCMC samples for fitted values divided by the expected (CARBayes models), or from the INLA marginal posterior quantiles (BYM2 model).

BYM2 model (INLA)

The BYM2 model of Riebler et al. (2016) reparameterises the original Besag-York-Mollie model into a single precision parameter \(\tau\) and a mixing parameter \(\phi \in [0,1]\) that quantifies the proportion of variance attributable to structured spatial variation. The latent field is:

$$u_i = \frac{1}{\sqrt{\tau}} \left(\sqrt{\phi} v_i^* + \sqrt{1-\phi} w_i\right)$$

where \(v_i^*\) is the scaled ICAR component and \(w_i \sim N(0,1)\). Penalised complexity (PC) priors are placed on \(\phi\) and \(\tau\): \(P(\phi > 0.5) = 0.5\) and \(P(1/\sqrt{\tau} > 1) = 0.01\).

Prior specification (CARBayes models)

prior_tau2 specifies the shape and rate parameters of an Inverse-Gamma prior for the variance component \(\tau^2\): \(\tau^2 \sim \text{Inv-Gamma}(\text{shape}, \text{rate})\). The default c(1, 0.01) is weakly informative. Fixed-effect coefficients receive flat (improper) priors.

References

Besag, J., York, J., & Mollie, A. (1991). Bayesian image restoration, with two applications in spatial statistics. Annals of the Institute of Statistical Mathematics, 43(1), 1-20.

Leroux, B. G., Lei, X., & Breslow, N. (2000). Estimation of disease rates in small areas: a new mixed model for spatial dependence. In Statistical Models in Epidemiology, the Environment, and Clinical Trials (pp. 179-191). Springer.

Lee, D. (2013). CARBayes: an R package for Bayesian spatial modelling with conditional autoregressive priors. Journal of Statistical Software, 55(13), 1-24.

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.

Rue, H., Martino, S., & Chopin, N. (2009). Approximate Bayesian inference for latent Gaussian models by using integrated nested Laplace approximations. Journal of the Royal Statistical Society: Series B, 71(2), 319-392.

See also

sus_mod_spatial_weights() to build the required adjacency object, sus_mod_spatial_moran() for exploratory spatial autocorrelation, sus_mod_spatial_scan() for cluster detection.

Examples

if (FALSE) { # \dontrun{
library(climasus4r)
library(geobr)

# Build spatial weights for Nordeste
shp <- geobr::read_municipality(code_muni = "all", year = 2022)
shp_ne <- shp[shp$abbrev_state %in% c("CE", "RN", "PB", "PE"), ]
W <- sus_mod_spatial_weights(shp_ne, return_matrix = TRUE)

# Prepare aggregated health-climate data (must have code_muni)
# agg <- sus_data_aggregate(cleaned_df) |> sus_climate_aggregate()

# BYM Poisson model with temperature as covariate (CARBayes/MCMC)
result_bym <- sus_mod_spatial_bayes(
  df         = agg,
  outcome    = "deaths",
  W          = W,
  covariates = c("temp_mean", "prec_total"),
  offset     = "expected_deaths",
  family     = "poisson",
  model      = "bym",
  n_iter     = 10000,
  burnin     = 2000,
  thin       = 10,
  seed       = 42,
  lang       = "pt"
)
print(result_bym)

# BYM2 Poisson model with PC priors (INLA) - requires INLA package
result_bym2 <- sus_mod_spatial_bayes(
  df         = agg,
  outcome    = "deaths",
  W          = W,
  covariates = c("temp_mean", "prec_total"),
  offset     = "expected_deaths",
  family     = "poisson",
  model      = "bym2",
  seed       = 42,
  lang       = "pt"
)
print(result_bym2)
result_bym2$rr
result_bym2$fixed
} # }