BGGM Package Overview

Relevant source files

• .Rbuildignore
• .github/workflows/pkgdown.yaml
• .gitignore
• DESCRIPTION
• NEWS.md
• R/bggm_missing.R
• README.Rmd
• README.md
• _pkgdown.yml
• cran-comments.md
• docs/404.html
• docs/LICENSE-text.html
• docs/articles/index.html
• docs/authors.html
• docs/index.html
• docs/news/index.html
• docs/paper.html
• docs/pkgdown.yml
• docs/reference/index.html
• index.Rmd
• index.md
• inst/REFERENCES.bib
• man/bggm_missing.Rd

Purpose and Scope

This document provides a high-level introduction to the BGGM (Bayesian Gaussian Graphical Models) R package. It covers the package's purpose, core conceptual framework, main inference approaches, supported data types, and computational architecture. For detailed information on specific topics, see:

• Installation and setup: Installation and Quick Start
• Core statistical concepts: Core Concepts and Terminology
• Estimation-based methods: Estimation-Based Analysis
• Hypothesis testing: Exploratory Hypothesis Testing and Confirmatory Hypothesis Testing
• Multi-group comparisons: Comparing Gaussian Graphical Models

Sources: README.md1-50 DESCRIPTION1-62 paper.md1-109

---

Package Identity

BGGM is an R package that provides Bayesian inference methods for Gaussian graphical models (GGMs). A Gaussian graphical model represents conditional dependencies among variables as a network of partial correlations, where each edge reflects the relationship between two variables after controlling for all other variables in the model.

Property	Value
Package Name	BGGM
Current Version	2.1.6
License	GPL-2
Repository	https://github.com/rast-lab/BGGM
CRAN Page	https://cran.r-project.org/package=BGGM
Primary Language	R with C++ backend

Key Contributors:

• Donald R. Williams (University of California, Davis)
• Joris Mulder (Tilburg University)
• Philippe Rast (maintainer)

Sources: DESCRIPTION1-12 README.md5-12 paper.md10-22

---

Core Problem and Solution

What Problem Does BGGM Solve?

Researchers across sciences (psychology, economics, climate science, genetics) need to understand conditional dependencies between variables. Traditional approaches either:

1. Provide point estimates without quantifying uncertainty (frequentist methods)
2. Lack principled methods for hypothesis testing in network structures
3. Cannot handle discrete data types (binary, ordinal)
4. Struggle with group comparisons

BGGM's Solution

BGGM extends classical Gaussian graphical modeling by providing:

1. Full Bayesian uncertainty quantification via posterior distributions
2. Two distinct inference paradigms: estimation (posterior-based) and hypothesis testing (Bayes factor-based)
3. Universal data type support: continuous, binary, ordinal, and mixed data through latent variable models
4. Principled group comparison methods including posterior predictive checks and confirmatory constraints
5. Matrix-F prior distribution for improved estimation and testing

Sources: README.md14-34 paper.md26-44

---

Two Inference Paradigms

BGGM organizes all methods around two fundamental approaches to Bayesian inference:

1. Estimation-Based Inference

Focus: Posterior and posterior predictive distributions

Philosophy: Quantify uncertainty about parameters and make predictions

Key Functions:

• estimate() - Fit model and obtain posterior samples
• ggm_compare_estimate() - Compare networks via posterior distributions of differences
• ggm_compare_ppc() - Compare networks via posterior predictive checks

Output: Posterior distributions, credible intervals, posterior means

2. Hypothesis Testing

Focus: Bayes factors for model comparison

Philosophy: Evaluate evidence for/against specific hypotheses

Key Functions:

• explore() - Edge-by-edge Bayes factors without pre-specified hypotheses
• confirm() - Test theory-driven (in)equality constraints
• ggm_compare_explore() - Group comparison via Bayes factors
• ggm_compare_confirm() - Test group-specific hypotheses

Output: Bayes factors, posterior hypothesis probabilities, evidence classifications

Sources: README.md14-20 README.Rmd31-35

---

Main User-Facing Functions

Function Categories:

Category	Functions	Purpose
Estimation	estimate()	Posterior-based network inference
Exploration	explore()	Data-driven edge discovery via BF
Confirmation	confirm()	Theory-driven hypothesis testing
Group Comparison	ggm_compare_*() (4 variants)	Multi-group network comparison
Selection	select()	Identify significant edges
Extraction	coef(), pcor_mat(), posterior_samples()	Extract model components
Advanced Analysis	predictability(), roll_your_own(), predict()	Extended inference
Visualization	plot()	Network and diagnostic plots
Missing Data	bggm_missing()	Integration with mice package

Sources: README.md54-102 README.Rmd68-99

---

Supported Data Types

BGGM handles four data types through a unified latent variable framework:

Type	Description	Model	Key Parameter	C++ Sampler
continuous	Gaussian data	Direct Wishart	type = "continuous"	_BGGM_Theta_continuous
binary	0/1 coded data	Probit (latent truncated normal)	type = "binary"	_BGGM_mv_binary
ordinal	Ordered categories	Threshold model	type = "ordinal"	_BGGM_mv_ordinal_albert _BGGM_mv_ordinal_cowles
mixed	Combination	Semi-parametric copula	type = "mixed"	_BGGM_copula

Data Type Selection

Users specify the data type via the type argument in main functions:

Latent Variable Interpretation

For non-continuous types, BGGM models latent Gaussian variables underlying the observed discrete data. Partial correlations represent relationships between these latent variables, not the observed categories directly. This approach:

• Enables standard GGM methods on all data types
• Provides tetrachoric (binary) and polychoric (ordinal) correlations
• Unifies inference across data types

Sources: README.md103-123 README.Rmd106-122 paper.md79-95

---

Computational Architecture

Architecture Principles

1. Clear separation of concerns: R handles user interaction and data preparation; C++ handles performance-critical MCMC sampling
2. Modular samplers: Each data type has dedicated C++ sampling functions
3. Automatic bindings: Rcpp generates type-safe R-C++ interfaces
4. External dependencies: Leverages specialized packages (BFpack for Bayes factors, Armadillo for linear algebra)

Key Dependencies

From DESCRIPTION23-57:

Core Imports:

• BFpack (≥ 1.2.3) - Bayes factor computation for confirm()
• Rcpp (≥ 1.0.4.6) - R-C++ interface
• MASS, mvnfast - Statistical distributions
• GGally, ggplot2, network, sna - Visualization

LinkingTo (C++):

• RcppArmadillo - Matrix operations
• RcppDist - Statistical distributions (Wishart)
• RcppProgress - User feedback during sampling

Suggested (Optional):

• mice - Missing data imputation
• networktools, assortnet - Network statistics
• testthat - Testing framework

Sources: DESCRIPTION23-57 README.md94-101 paper.md97-99

---

Object-Oriented Structure

BGGM uses S3 classes for fitted model objects:

Common Object Components

All fitted objects share:

• type - Data type ("continuous", "binary", "ordinal", "mixed")
• iter - Number of MCMC iterations
• p - Number of variables
• call - Original function call
• pcor_mat - Posterior mean partial correlation matrix

Object-Specific Components

estimate objects:

• post_samp$pcors - Posterior samples (array: iter × p × p)
• analytic - Boolean flag for analytic solution (continuous only)
• formula - Optional control variable formula

explore objects:

• BF_01 - Bayes factor matrix (p × p) for null hypothesis
• prior_samp - Prior samples for Savage-Dickey ratio

confirm objects:

• out_hyp_prob - Posterior hypothesis probabilities
• BF_matrix - Pairwise Bayes factors between hypotheses
• hypothesis - String specifying constraints

Sources: README.md182-239 README.Rmd148-187

---

Matrix-F Prior Distribution

BGGM uses the matrix-F prior distribution for the precision matrix (inverse covariance). This prior:

1. Improves on the Wishart prior by better handling high-dimensional settings
2. Provides principled hypothesis testing via the Savage-Dickey density ratio
3. Allows user control via prior_sd parameter (related to expected partial correlation magnitude)

Prior Specification

Users control the prior through prior_sd (or deprecated delta):

The relationship: delta = sqrt(prior_sd^(-2) - 1)

Valid range: 0 < prior_sd ≤ sqrt(1/2) ensures delta ≥ 1

Sources: README.md59-60 NEWS.md52-53 inst/REFERENCES.bib145-156

---

Analytic Solution for Continuous Data

When type = "continuous" and n > p, BGGM offers an analytic solution based on the Wishart distribution:

Advantages:

• Immediate computation (no MCMC sampling)
• Exact posterior (not approximate)
• Competitive with state-of-the-art methods

Limitations:

• Only for type = "continuous"
• Requires n > p (more observations than variables)
• Cannot use with formulas (control variables)

Use Cases:

• Rapid exploratory analysis
• Posterior predictive checks requiring many model fits
• Situations where only network structure matters

Sources: README.md261-278 README.Rmd211-225

---

Missing Data Support

BGGM handles missing data through two mechanisms:

1. Integration with mice Package

The bggm_missing() function interfaces with the mice package for multiple imputation:

Workflow:

1. Impute missing data using mice::mice() → multiple datasets
2. Fit BGGM model to each imputed dataset independently
3. Pool posterior samples across all datasets
4. Return single estimate or explore object with pooled results

Sources: R/bggm_missing.R1-210 man/bggm_missing.Rd1-91

2. Built-in Imputation During Sampling

For continuous and mixed data, BGGM can impute missing values during MCMC sampling:

This treats missing values as additional parameters to be sampled.

Sources: README.md101 README.Rmd104

---

Version History

Version	Key Changes
2.1.6	Ordinal sampler improvements: Stan-style latent centering, threshold initialization from empirical frequencies, improved stability for skewed data
2.1.5	Removed NPM library for CRAN compatibility
2.1.4	Improved search() function: adaptive sampling, better initialization
2.1.3	Adjusted prior_sd computation, replaced deprecated Armadillo functions
2.1.2	Critical fix: select() returned Fisher-z instead of correlations
2.0.0	Major rewrite with C++ backend, full support for binary/ordinal/mixed data, added roll_your_own(), convergence(), pcor_to_cor(), and more
1.0.0	Initial CRAN release

Current Development Version: 2.1.6.9000

Sources: NEWS.md1-111 DESCRIPTION4-5

---

Related Software

BGGM is unique in the R ecosystem for combining:

• Bayesian GGM estimation and hypothesis testing
• Support for all four data types (continuous, binary, ordinal, mixed)
• Confirmatory hypothesis testing with (in)equality constraints
• Comprehensive group comparison methods

Comparison to other packages:

Package	Language	Capabilities	Limitations vs. BGGM
sbgcop	Base R	Mixed data (copula)	No hypothesis testing, slower
BDgraph	C++	Gaussian copula	No binary/ordinal support, no confirmatory testing
qgraph	R	Network visualization	Not Bayesian, no inference
bootnet	R	Network stability	Frequentist only

BGGM's unique contributions:

1. Only package with confirmatory hypothesis testing for GGMs
2. Only package with all group comparison methods (estimation, exploration, confirmation, PPC)
3. Matrix-F prior for improved Bayesian inference
4. Unified interface across all data types

Sources: README.md1025-1034 paper.md101-103

---

Target Audience and Design Philosophy

Primary Users

BGGM was built specifically for social-behavioral scientists, though methods apply broadly across:

• Psychology (comorbidity networks, personality networks)
• Economics (correlation networks)
• Climate science (climate networks)
• Genetics (gene regulatory networks)

Design Constraints

Not designed for: High-dimensional data (p > n)

BGGM requires n ≥ p (more observations than variables), which is typical in social-behavioral research but rare in genetics/bioinformatics.

Philosophy

1. Transparency: Users see posterior distributions, not just point estimates
2. Theory-driven: Support for confirmatory hypothesis testing, not just exploration
3. Uncertainty quantification: Full Bayesian treatment provides credible intervals for all parameters
4. Flexibility: Users can extend analysis with roll_your_own() for custom network statistics

Sources: README.md1009-1017 paper.md40-43

---

Citations and Academic References

To cite BGGM in publications:

Williams, D. R., & Mulder, J. (2020). BGGM: Bayesian Gaussian Graphical Models in R. Journal of Open Source Software, 5(51), 2111. https://doi.org/10.21105/joss.02111

Key methodological papers:

1. Estimation: Williams (2018). Bayesian Estimation for Gaussian Graphical Models. https://doi.org/10.31234/osf.io/x8dpr
2. Hypothesis Testing: Williams & Mulder (2019). Bayesian Hypothesis Testing for Gaussian Graphical Models. https://doi.org/10.31234/osf.io/ypxd8
3. Group Comparison: Williams et al. (2020). Comparing Gaussian graphical models with the posterior predictive distribution. Psychological Methods. https://doi.org/10.1037/met0000254
4. Matrix-F Prior: Mulder & Pericchi (2018). The Matrix-F Prior for Estimating and Testing Covariance Matrices. Bayesian Analysis. https://doi.org/10.1214/17-BA1092

Sources: README.md1036-1290 inst/REFERENCES.bib35-156 paper.md23-109