bhfvar: Bayesian Hybrid Framework for Variance Decomposition

The bhfvar package implements the Bayesian Hybrid Framework for variance decomposition in complex surveys with post-hoc domains. It provides tools for separating substantive geographic variation from design artifacts and sampling noise.

Key Features

• Bayesian Pseudo-Likelihood estimation for design consistency

• Hybrid generalized linear mixed models with domain and PSU effects

• Dual Estimand Framework: Policy (A/A*) and Descriptive (B) estimands

• De-attenuation for finite-sample variance inflation correction

• Comprehensive diagnostic and visualization tools

Main Functions

• compile_bhf_model: Compile Stan model (once per session)

• prepare_bhf_data: Prepare data for Stan

• bhf_fit: Fit the BHF model

• variance_decomposition: Extract variance components

• domain_estimates: Extract domain-specific estimates

Workflow

The recommended workflow is:

1. Compile the Stan model once per R session using compile_bhf_model()

2. Prepare your data using prepare_bhf_data()

3. Fit the model using bhf_fit()

4. Extract results using variance_decomposition() and domain_estimates()

Design Philosophy

This package uses a "defensive" programming approach where the Stan model is compiled explicitly by the user once per session, rather than being pre-compiled during package installation. This approach:

• Avoids rstantools caching issues

• Provides clearer error messages when compilation fails

• Ensures compatibility across different R/Stan versions

• Gives users more control over the compilation process

References

Lee, J., & Hooper, A. (2025). Disentangling Signal from Noise: A Bayesian Hybrid Framework for Variance Decomposition in Complex Surveys with Post-Hoc Domains. Mathematics.

See also

Useful links:

• https://github.com/joonho-lee/bhfvar

• Report bugs at https://github.com/joonho-lee/bhfvar/issues

Author

JoonHo Lee jlee296@ua.edu