Getting Started with spatialAtomizeR

Overview

spatialAtomizeR implements atom-based Bayesian regression methods (ABRM) for spatial data with misaligned grids. This vignette demonstrates the basic workflow for analyzing misaligned spatial data.

Installation

# Install from GitHub
devtools::install_github("bellayqian/spatialAtomizeR")

Load Packages

Important: Always load nimble before using spatialAtomizeR functions.

library(spatialAtomizeR)
library(nimble)  # Required for ABRM models

Basic Workflow

Step 1: Simulate Misaligned Data

Generate spatial data with misaligned grids and specify all parameters:

sim_data <- simulate_misaligned_data(
  seed = 42,
  res1 = c(5, 5),    # Y grid resolution (coarser)
  res2 = c(10, 10),  # X grid resolution (finer)
  
  # Distribution specifications
  dist_covariates_x = c('normal', 'poisson', 'binomial'),
  dist_covariates_y = c('normal', 'poisson', 'binomial'),
  dist_y = 'poisson',
  
  # Intercepts (critical parameters)
  x_intercepts = c(4, -1, -1),
  y_intercepts = c(4, -1, -1),
  beta0_y = -1,
  
  # Spatial correlation
  x_correlation = 0.5,
  y_correlation = 0.5,
  
  # True effect sizes
  beta_x = c(-0.03, 0.1, -0.2),
  beta_y = c(0.03, -0.1, 0.2)
)

Step 2: Get Model Code

model_code <- get_abrm_model()

Step 3: Run ABRM Analysis

results <- run_abrm(
  sim_data = sim_data,
  model_code = model_code,
  
  # Map distribution indices to positions
  norm_idx_x = 1,   # 'normal' is 1st in dist_covariates_x
  pois_idx_x = 2,   # 'poisson' is 2nd
  binom_idx_x = 3,  # 'binomial' is 3rd
  norm_idx_y = 1,
  pois_idx_y = 2,
  binom_idx_y = 3,
  
  # Outcome distribution: 1=normal, 2=poisson, 3=binomial
  dist_y = 2,
  
  # MCMC parameters
  niter = 50000,
  nburnin = 30000,
  nchains = 2
)

Step 4: Examine Results

# Parameter estimates
print(results$parameter_estimates)

# Convergence diagnostics
print(results$mcmc_results$convergence)

Understanding Distribution Indices

When you specify dist_covariates_x = c('normal', 'poisson', 'binomial'), the indices correspond to positions:

norm_idx_x = 1 (first position)
pois_idx_x = 2 (second position)
binom_idx_x = 3 (third position)

Advanced: Step-by-Step Control

For more control over the analysis pipeline:

# Prepare spatial structure
bookkeeping <- prepare_spatial_bookkeeping(sim_data)

# Create adjacency matrices
adjacency <- prepare_adjacency_matrices(
  bookkeeping$gridy_yorder, 
  bookkeeping$gridx_xorder
)

# Prepare NIMBLE inputs
nimble_inputs <- prepare_nimble_inputs(
  bookkeeping, adjacency, sim_data,
  norm_idx_x = 1, pois_idx_x = 2, binom_idx_x = 3,
  norm_idx_y = 1, pois_idx_y = 2, binom_idx_y = 3,
  dist_y = 2
)

# Run NIMBLE MCMC
sim_metadata <- list(
  sim_number = 1,
  x_correlation = 0.5,
  y_correlation = 0.5
)

mcmc_results <- run_nimble_model(
  constants = nimble_inputs$constants,
  data = nimble_inputs$data,
  inits = nimble_inputs$inits,
  sim_metadata = sim_metadata,
  model_code = model_code,
  niter = 50000,
  nburnin = 30000,
  nchains = 2,
  thin = 10,
  save_plots = TRUE
)

Sensitivity Analysis

Test model performance across different correlation structures:

# Define base parameters
base_params <- list(
  res1 = c(5, 5),
  res2 = c(10, 10),
  dist_covariates_x = c('normal','poisson','binomial'),
  dist_covariates_y = c('normal','poisson','binomial'),
  dist_y = 'poisson',
  x_intercepts = c(4, -1, -1),
  y_intercepts = c(4, -1, -1),
  beta0_y = -1,
  beta_x = c(-0.03, 0.1, -0.2),
  beta_y = c(0.03, -0.1, 0.2)
)

# Run sensitivity analysis
sensitivity_results <- run_sensitivity_analysis(
  correlation_grid = c(0.2, 0.6),
  n_sims_per_setting = 3,
  base_params = base_params,
  model_code = model_code,
  base_seed = 123
)

# View summary
print(sensitivity_results$summary_by_correlation)

Key Parameters Reference

Critical Parameters (Don’t Omit!)

x_intercepts: Intercepts for X covariates (must match length of dist_covariates_x)
y_intercepts: Intercepts for Y covariates (must match length of dist_covariates_y)
beta0_y: Outcome model intercept

Distribution Types

Code	Distribution	String
1	Normal	‘normal’
2	Poisson	‘poisson’
3	Binomial	‘binomial’

Troubleshooting

Error: “could not find function ‘getNimbleOption’” - Load nimble before calling get_abrm_model(): library(nimble)

Warning: “pop_atoms length doesn’t match D!” - Usually harmless, model should still run correctly

Getting Help

Function documentation: ?simulate_misaligned_data, ?run_abrm
Report issues: https://github.com/bellayqian/spatialAtomizeR/issues
Package help: ?spatialAtomizeR

Citation

citation("spatialAtomizeR")

Qian, Y., & Nethery, R. (2025). spatialAtomizeR: Atom-Based Regression Models for Misaligned Spatial Data. R package version 0.2.1.