vgmsfh_numpyro {vmsae} | R Documentation |
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
)
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 |
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 |
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 |
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.
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, includingmu
,delta
, and other intermediate quantities.
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
## Not run:
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)
## End(Not run)