Decoder S4 Class

Description

An S4 class to represent a neural network decoder, used for emulating spatial priors. The class includes parameters for input and output weight matrices and biases, as well as region identifiers.

Slots

GEOID

A character vector of region or area identifiers.

W_in

An array representing the input weight matrix of the decoder.

B_in

An array representing the input bias vector of the decoder.

W_out

An array representing the output weight matrix of the decoder.

B_out

An array representing the output bias vector of the decoder.

VGMSFH S4 Class

Description

An S4 class to store results from the Variational Gaussian Markov Small Area Estimation with Fay-Herriot model (VGMSFH). This class holds the posterior samples for various model components as well as the original direct estimates.

Slots

model_name

Character. The name of the trained VAE model.

direct_estimate

Array. Direct estimates of parameters.

yhat_samples

Array. Posterior samples of the estimated parameters.

phi_samples

Array. Posterior samples of the estimated spatial random effects.

beta_samples

Array. Posterior samples of the fixed effect coefficients.

other_samples

List. List of posterior samples of other parameters in the VGMSFH model.

Extract Coefficients from a VGMSFH Object

Description

This method extracts posterior mean estimates of model coefficients from a VGMSFH object. It can return either fixed effect coefficients or spatial random effects.

Usage

## S4 method for signature 'VGMSFH'
coef(object, var_idx = 1, type = "fixed")

Arguments

Value

A numeric vector of posterior means for the selected coefficient type.

Examples

library(vmsae)
example_model <- readRDS(system.file("example", "example_model.Rds", package = "vmsae"))
coef(example_model)  # Get fixed effect coefficients
coef(example_model, type = "spatial")  # Get spatial random effects

Compute Credible Intervals for VGMSFH Parameters

Description

This method computes 95\

Usage

## S4 method for signature 'VGMSFH'
confint(object, var_idx = 1, field = "yhat_samples")

Arguments

Details

The function extracts posterior samples for the specified variable and then computes quantiles to form 95\

Value

A data frame with two columns:

• lower: the 2.5\

• upper: the 97.5\

Examples

library(vmsae)
example_model <- readRDS(system.file("example", "example_model.Rds", package = "vmsae"))
confint(example_model)  # Get credible intervals for predicted values
confint(example_model, field = "beta_samples")  # For fixed effects

Download and Extract a Pretrained VAE Model

Description

This function downloads a pretrained VAE model archive from Zenodo, extracts its contents into a specified directory, and removes the downloaded ZIP file after extraction.

Usage

download_pretrained_vae(model_name, save_dir, verbose = TRUE)

Arguments

Value

No return value, called for side effects

Examples

## Not run: 
library(vmsae)
# this function is time consuming for the first run
install_environment()
load_environment()
download_pretrained_vae("mo_county", tempdir())

## End(Not run)

Install python environment.

Description

This function creates the vmsae python environment and installs required packages.

Usage

install_environment(envname = "vmsae", use_gpu = FALSE)

Arguments

Value

No return value, called for side effects

Examples

## Not run: 
library(vmsae)
# this function is time consuming for the first run
install_environment()          # Install into default "vmsae" environment


# this step is time consuming for the first run
install_environment("custom")  # Install into a custom-named environment

## End(Not run)

Load Python Environment and Source Model Modules

Description

This function activates a specified Python virtual environment and sources Python modules used by the vmsae package, including models and python scripts.

Usage

load_environment(envname = "vmsae", is_conda = FALSE)

Arguments

Details

The function loads four Python scripts located in the package's ⁠py/⁠ directory:

• vgmcar.py

• vae.py

• train_vae.py

• car_dataset.py

The environment must be created beforehand (e.g., using install_environment()), and must include all Python dependencies required by these modules.

Value

No return value, called for side effects

Examples

## Not run: 
library(vmsae)

# this function is time consuming for the first run
install_environment()
load_environment()          # Load default "vmsae" environment

# this function is time consuming for the first run
install_environment("custom")
load_environment("custom") # Load custom virtual environment

load_environment("custom", is_conda = TRUE) # Load custom conda environment

## End(Not run)

Load Pretrained VAE Decoder

Description

Load a pretrained Variational Autoencoder (VAE) decoder from disk. This function reads the saved PyTorch model weights and corresponding GEOID list, and constructs a Decoder S4 object with the loaded parameters.

Usage

load_vae(model_name, save_dir = NULL)

Arguments

Details

This function assumes the model was trained and saved using train_vae(), and that the decoder weights are stored in a file compatible with torch::load() (via reticulate). It extracts the decoder input/output weights and biases, along with region GEOIDs, and returns them as an S4 object of class Decoder.

Value

An object of class Decoder, containing the decoder weights and region identifiers.

Examples

## Not run: 
library(vmsae)
# this function is time consuming for the first run
install_environment()
load_environment()
decoder <- load_vae(model_name = "mo_county")

## End(Not run)

Plot VGMSFH Result

Description

This method plots spatial summaries of results from a VGMSFH object, including model estimates and comparisons with direct estimates.

Usage

## S4 method for signature 'VGMSFH'
plot(x, shp = NULL, var_idx = 1, type = "compare", verbose = TRUE)

Arguments

Details

The function provides spatial visualization of model results. It supports both univariate and multivariate response settings. When type = "compare", it generates side-by-side choropleth maps for the direct and model-based estimates. When type = "estimate", it plots the posterior mean and standard deviation of the VGMSFH model output.

If no shapefile is provided, a default geometry is loaded from the pretrained repository.

Value

A ggplot object. The plot is rendered to the active device.

Examples

library(vmsae)
library(sf)
example_model <- readRDS(system.file("example", "example_model.Rds", package = "vmsae"))
example_shp <- read_sf(system.file("example", "mo_county.shp", package = "vmsae"))
plot(example_model, shp = example_shp, type = "compare")
plot(example_model, shp = example_shp, type = "estimate", var_idx = 2)

Summarize VGMSFH Result

Description

This method provides a summary of posterior samples from a VGMSFH object, including posterior means and credible intervals for a specified parameter field.

Usage

## S4 method for signature 'VGMSFH'
summary(object, var_idx = 1, field = "beta_samples")

Arguments

Details

This function extracts the posterior samples for the specified variable index, and combines it with confint() to compute credible intervals. The result is a compact summary table of central tendency and uncertainty.

Value

A data frame with columns:

• mean: Posterior mean,

• lower: Lower bound of the credible interval,

• upper: Upper bound of the credible interval.

Examples

library(vmsae)
example_model <- readRDS(system.file("example", "example_model.Rds", package = "vmsae"))
summary(example_model)  # Summary of beta_samples for variable 1
summary(example_model, var_idx = 2, field = "yhat_samples")

Train VAE for CAR Prior

Description

Trains a Variational Autoencoder (VAE) to learn the spatial structure implied by the Conditional Autoregressive (CAR) prior. The trained VAE parameters are saved and can later be used as a generator within Hamiltonian Monte Carlo (HMC) sampling.

Usage

train_vae(
  W,
  GEOID,
  model_name,
  save_dir,
  n_samples = 10000,
  batch_size = 256,
  epoch = 10000,
  lr_init = 0.001,
  lr_min = 1e-07,
  verbose = TRUE,
  use_gpu = TRUE
)

Arguments

Details

The function requires a configured Python environment via the reticulate interface, with VAE training implemented in Python. It uses py$train_vae() defined in the sourced Python modules (see load_environment).

Value

A named list containing:

Examples

## Not run: 
library(vmsae)
library(sf)
# 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"))
W <- readRDS(system.file("example", "W.Rds", package = "vmsae"))

loss <- train_vae(W = W,
  GEOID = acs_data$GEOID,
  model_name = "test",
  save_dir = tempdir(),
  n_samples = 1000, # set to larger values in practice, e.g. 10000.
  batch_size = 256,
  epoch = 1000)     # set to larger values in practice, e.g. 10000.

## End(Not run)

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

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, including mu, 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)