ggm_search: Perform Bayesian Graph Search and Optional Model Averaging

In BGGM: Bayesian Gaussian Graphical Models

Perform Bayesian Graph Search and Optional Model Averaging

Description

The 'ggm_search' function performs a Metropolis-Hastings graph search to identify high-probability graph structures. At each iteration, one edge is randomly proposed to flip (add or remove, chosen by an independent coin flip), and the proposal is accepted or rejected using a proper MH acceptance ratio (including a birth-death Hastings correction for the proposal-size asymmetry between the add and remove moves), so the walk can move to a worse-BIC graph and is not just a hill-climb. It also computes an optional Bayesian Model Averaged (BMA) solution: the distinct graphs visited after burn-in are reweighted by their BIC-approximated posterior model probabilities.

Usage

ggm_search(
  x,
  n = NULL,
  method = "mc3",
  prior_prob = 0.3,
  iter = 5000,
  burn_in = NULL,
  stop_early = 1000,
  bma_mean = TRUE,
  seed = NULL,
  progress = TRUE,
  probabilistic = TRUE,
  ...
)

Arguments

x	Data, either raw data or covariance matrix
n	For x = covariance matrix, provide number of observations
method	mc3 defaults to MH sampling
prior_prob	Prior prbability of sparseness.
iter	Number of iterations
burn_in	Number of initial iterations discarded before computing the BMA solution. Defaults to iter / 2. Only meaningful when probabilistic = TRUE (a greedy hill-climb has no transient to burn in — its BIC trajectory is monotone non-increasing).
stop_early	Default to 1000. Only used when probabilistic = FALSE: stop the greedy search early if proposals keep being rejected (stopping by default after 1000 consecutive rejections). Ignored under probabilistic search, which always runs the full iter iterations since rejections are an expected, normal part of MH sampling.
bma_mean	Compute Bayesian Model Averaged solution
seed	Set seed. Current default is to set R's random seed.
progress	Show progress bar, defaults to TRUE
probabilistic	Defaults to TRUE: a genuine Metropolis-Hastings sampler over graph structures (see Details). Set to FALSE for the deterministic greedy hill-climb instead.
...	Not currently in use

Details

Set probabilistic = FALSE to instead run a deterministic greedy hill-climb (accept a proposed edge flip only if it improves BIC). This is much faster per iteration but explores far less of graph space in practice — in testing it can get stuck after accepting only a handful of moves, well before iter is reached, and stop_early exists to end the search once that happens.

This function is ideal for exploring the graph space and obtaining an initial estimate of the graph structure or adjacency matrix.

To refine the results or compute posterior distributions of graph parameters (e.g., partial correlations), use the bma_posterior function, which builds on the output of 'ggm_search' to account for parameter uncertainty.

Value

A list containing the MAP graph structure, BMA solution (if specified), and BIC-approximated posterior probabilities of the graphs visited during the search.

Author(s)

Donny Williams and Philippe Rast

See Also

bma_posterior

BGGM documentation built on Sept. 24, 2026, 9:06 a.m.