# Getting Started with spatialAtomizeR

#### Yunzhe Qian (Bella) and Rachel Nethery

#### 2025-12-17

## 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.