vmsae (version 0.1.2)

vgmsfh_numpyro: Run VGMSFH Using NumPyro

Description

This function runs the Variational Generalized Multivariate Spatil Fay-Herriot model (VGMSFH) using NumPyro as the inference backend. It loads pretrained VAE decoder weights, prepares the data, and performs posterior sampling.

Usage

vgmsfh_numpyro(
  y,
  y_sigma,
  X,
  W,
  GEOID,
  model_name,
  save_dir = NULL,
  num_warmup = 1000,
  num_samples = 1000,
  verbose = TRUE,
  use_gpu = FALSE
)

Value

An object of class VGMSFH, which contains:

• direct_estimate: the observed response data,

• yhat_samples: posterior samples of the latent population process,

• phi_samples: posterior samples of spatial random effects (CAR),

• beta_samples: posterior samples of fixed effect coefficients,

• other_samples: a list containing all sampled parameters, including mu, delta, and other intermediate quantities.

Arguments

y

Matrix. Response variables (direct estimates).

y_sigma

Matrix. Reported standard deviations of the responses.

X

Matrix. Covariate matrix.

W

Matrix. Proximity or adjacency matrix defining spatial structure.

GEOID

Character vector. FIPS codes or other region identifiers used to match with the pretrained VAE model.

model_name

Character. The name of the pretrained VAE model.

save_dir

Character. The directory where the VAE model is stored. If NULL, a default pretrained model directory is used.

num_warmup

Integer. Number of warmup (burn-in) iterations. Default is 1000.

num_samples

Integer. Number of posterior samples to draw. Default is 1000.

verbose

Logical; if TRUE (default), prints progress.

use_gpu

Boolean. Use GPU if available. GPU support is recommended only for high-dimensional datasets (e.g., those with more than 1,000 areas). Default is FALSE.

Details

This function uses a pretrained VAE decoder to parameterize the CAR prior and enables scalable inference through NumPyro. It is suitable for both univariate and multivariate response modeling in spatial domains.

References

Wang, Z., Parker, P. A., & Holan, S. H. (2025). Variational Autoencoded Multivariate Spatial Fay-Herriot Models. arXiv:2503.14710. https://arxiv.org/abs/2503.14710

Examples

if (FALSE) {
library(sf)
library(vmsae)
# this function is time consuming for the first run
install_environment()
load_environment()

acs_data <- read_sf(system.file("example", "mo_county.shp", package = "vmsae"))
y <- readRDS(system.file("example", "y.Rds", package = "vmsae"))
y_sigma <- readRDS(system.file("example", "y_sigma.Rds", package = "vmsae"))
X <- readRDS(system.file("example", "X.Rds", package = "vmsae"))
W <- readRDS(system.file("example", "W.Rds", package = "vmsae"))

num_samples <- 1000 # set to larger values in practice, e.g. 10000.
model <- vgmsfh_numpyro(y, y_sigma, X, W,
  GEOID = acs_data$GEOID,
  model_name = "mo_county", save_dir = NULL,
  num_samples = num_samples, num_warmup = num_samples)
y_hat_np <- model@yhat_samples
y_hat_mean_np <- apply(y_hat_np, c(2, 3), mean)
y_hat_lower_np <- apply(y_hat_np, c(2, 3), quantile, 0.025)
y_hat_upper_np <- apply(y_hat_np, c(2, 3), quantile, 0.975)

plot(model, shp = acs_data, type = "compare", var_idx = 2)
}