bgm()

Fits a single-network Bayesian graphical model with bgm() and returns an S7 object of class bgms.

Description

bgm() fits a single network for binary, ordinal, continuous, or mixed data, with optional Bayesian edge selection. This page is the technical reference for function arguments and returned objects. For interpretation and workflow, start with Getting Started, then see Graphical Models and The Bayesian Approach. Methodological background is provided in Marsman et al. (2025).

Usage

bgm(
  x,
  variable_type = "ordinal",
  baseline_category,
  iter = 1000,
  warmup = 1000,
  pairwise_scale = 1,
  main_alpha = 0.5,
  main_beta = 0.5,
  edge_selection = TRUE,
  edge_prior = c("Bernoulli", "Beta-Bernoulli", "Stochastic-Block"),
  inclusion_probability = 0.5,
  beta_bernoulli_alpha = 1,
  beta_bernoulli_beta = 1,
  beta_bernoulli_alpha_between = 1,
  beta_bernoulli_beta_between = 1,
  dirichlet_alpha = 1,
  lambda = 1,
  na_action = c("listwise", "impute"),
  update_method = c("nuts", "adaptive-metropolis", "hamiltonian-mc"),
  target_accept,
  hmc_num_leapfrogs = 100,
  nuts_max_depth = 10,
  learn_mass_matrix = TRUE,
  chains = 4,
  cores = parallel::detectCores(),
  display_progress = c("per-chain", "total", "none"),
  seed = NULL,
  standardize = FALSE,
  pseudolikelihood = c("conditional", "marginal"),
  verbose = getOption("bgms.verbose", TRUE)
)

Arguments

Data

Argument Description
x A data frame or matrix with n rows and p columns containing binary and ordinal responses. Variables are automatically recoded to non-negative integers (0, 1, ..., m). For regular ordinal variables, unobserved categories are collapsed; for Blume–Capel variables, all categories are retained.
variable_type Character or character vector. Specifies the type of each variable in x. Allowed values: "ordinal", "blume-capel", or "continuous". A single string applies to all variables. A per-variable vector that mixes discrete ("ordinal" / "blume-capel") and "continuous" types fits a mixed MRF. Binary variables are automatically treated as "ordinal". Default: "ordinal".
baseline_category Integer or vector. Baseline category used in Blume–Capel variables. Can be a single integer (applied to all) or a vector of length p. Required if at least one variable is of type "blume-capel".
na_action Character. Specifies missing data handling. Either "listwise" (drop rows with missing values) or "impute" (impute within Gibbs sampler, propagating uncertainty). Default: "listwise". See Missing Data for details.

Prior specification

Argument Description
pairwise_scale Double. Scale of the Cauchy prior for pairwise interaction parameters. Default: 1.
main_alpha, main_beta Double. Shape parameters of the beta-prime prior for threshold parameters. Must be positive. If equal, the prior is symmetric. Defaults: main_alpha = 0.5 and main_beta = 0.5.
edge_selection Logical. Whether to perform Bayesian edge selection. If FALSE, the model estimates all edges. Default: TRUE.
edge_prior Character. Specifies the prior for edge inclusion. Options: "Bernoulli", "Beta-Bernoulli", or "Stochastic-Block". Default: "Bernoulli".
inclusion_probability Numeric scalar. Prior inclusion probability of each edge (used with the Bernoulli prior). Default: 0.5.
beta_bernoulli_alpha, beta_bernoulli_beta Double. Shape parameters for the beta distribution in the Beta–Bernoulli and Stochastic-Block priors. Must be positive. For the Stochastic-Block prior these are the shape parameters for the within-cluster edge inclusion probabilities. Defaults: beta_bernoulli_alpha = 1 and beta_bernoulli_beta = 1.
beta_bernoulli_alpha_between, beta_bernoulli_beta_between Double. Shape parameters for the between-cluster edge inclusion probabilities in the Stochastic-Block prior. Must be positive. Defaults: beta_bernoulli_alpha_between = 1 and beta_bernoulli_beta_between = 1.
dirichlet_alpha Double. Concentration parameter of the Dirichlet prior on block assignments (used with the Stochastic Block model). Default: 1.
lambda Double. Rate of the zero-truncated Poisson prior on the number of clusters in the Stochastic Block Model. Default: 1.
standardize Logical. If TRUE, the Cauchy prior scale for each pairwise interaction is adjusted based on the range of response scores. Variables with more response categories have larger score products \((x_i \cdot x_j)\), which typically correspond to smaller interaction effects \((\omega_{ij})\). Without standardization, a fixed prior scale is relatively wide for these smaller effects, resulting in less shrinkage for high-category pairs and more shrinkage for low-category pairs. Standardization scales the prior proportionally to the maximum score product, ensuring equivalent relative shrinkage across all pairs. After internal recoding, regular ordinal variables have scores \(0, 1, \ldots, m\). The adjusted scale for the interaction between variables \(i\) and \(j\) is pairwise_scale * m_i * m_j, so that pairwise_scale itself applies to the unit interval case (binary variables where \(m_i = m_j = 1\)). For Blume-Capel variables with reference category \(b\), scores are centered as \(-b, \ldots, m-b\), and the adjustment uses the maximum absolute product of the score endpoints. For mixed pairs, ordinal variables use raw score endpoints \((0, m)\) and Blume-Capel variables use centered score endpoints \((-b, m-b)\). Default: FALSE.

Sampler settings

Argument Description
iter Integer. Number of post-warmup iterations (per chain). Default: 1e3.
warmup Integer. Number of warmup iterations before collecting samples. A minimum of 1000 iterations is enforced, with a warning if a smaller value is requested. Default: 1e3.
update_method Character. Specifies how the MCMC sampler updates the model parameters: "adaptive-metropolis" (componentwise adaptive Metropolis–Hastings with Robbins–Monro proposal adaptation), "hamiltonian-mc" (Deprecated. Use "nuts" instead. Will be removed in a future release.), or "nuts" (the No-U-Turn Sampler with dynamically chosen trajectory lengths). Default: "nuts".
target_accept Numeric between 0 and 1. Target acceptance rate for the sampler. Defaults are set automatically if not supplied: 0.44 for adaptive Metropolis and 0.80 for NUTS.
hmc_num_leapfrogs Deprecated. Integer. Number of leapfrog steps for Hamiltonian Monte Carlo. Only relevant when update_method = "hamiltonian-mc", which is deprecated. Default: 100.
nuts_max_depth Integer. Maximum tree depth in NUTS. Must be positive. Default: 10.
learn_mass_matrix Logical. If TRUE, adapt a diagonal mass matrix during warmup (NUTS only). If FALSE, use the identity matrix. Default: TRUE.
chains Integer. Number of parallel chains to run. Default: 4.
cores Integer. Number of CPU cores for parallel execution. Default: parallel::detectCores().
display_progress Character. Controls progress reporting during sampling. Options: "per-chain" (separate bar per chain), "total" (single combined bar), or "none" (no progress). Default: "per-chain".
seed Optional integer. Random seed for reproducibility. Must be a single non-negative integer.
pseudolikelihood Character. Pseudolikelihood approximation for mixed MRF models (ignored for pure ordinal or pure continuous data). "conditional" conditions on the observed continuous variables when computing the discrete full conditionals; faster because the discrete pseudolikelihood does not depend on the continuous precision matrix. "marginal" integrates out the continuous variables, giving discrete full conditionals that account for induced interactions through the continuous block; more expensive per iteration. Default: "conditional".
verbose Logical. If TRUE, prints informational messages during data processing (e.g., missing data handling, variable recoding). Defaults to getOption("bgms.verbose", TRUE). Set options(bgms.verbose = FALSE) to suppress messages globally.

Value

An S7 object of class bgms with posterior summaries, posterior mean matrices, and raw MCMC draws. Supports print(), summary(), coef(), predict(), and simulate().

Main components:

  • posterior_summary_main — Data frame with posterior summaries (mean, sd, MCSE, ESS, Rhat) for main-effect parameters. For OMRF models these are category thresholds; for mixed MRF models these are discrete thresholds and continuous means. NULL for GGM models.
  • posterior_summary_quadratic — Data frame with posterior summaries for the precision matrix diagonal (GGM and mixed MRF). NULL for OMRF models.
  • posterior_summary_pairwise — Data frame with posterior summaries for partial association parameters.
  • posterior_summary_indicator — Data frame with posterior summaries for edge inclusion indicators (if edge_selection = TRUE).
  • posterior_mean_main — Posterior mean of main-effect parameters. NULL for GGM models. For OMRF: a matrix (p x max_categories) of category thresholds. For mixed MRF: a list with $discrete (threshold matrix) and $continuous (q x 1 matrix of means).
  • posterior_mean_associations — Symmetric matrix of posterior mean partial associations (zero diagonal). For continuous variables these are unstandardized partial correlations; for discrete variables these are half the log adjacent-category odds ratio. Use extract_precision(), extract_partial_correlations(), or extract_log_odds() to convert to interpretable scales.
  • posterior_mean_residual_variance — Named numeric vector of posterior mean residual variances \(1/\Theta_{ii}\). Present for GGM and mixed MRF models; NULL for OMRF.
  • posterior_mean_indicator — Symmetric matrix of posterior mean inclusion probabilities (if edge selection was enabled).
  • raw_samples — A list of raw MCMC draws per chain with the following sublists:
    • main — List of main effect samples.
    • pairwise — List of pairwise effect samples.
    • indicator — List of indicator samples (if edge selection enabled).
    • allocations — List of cluster allocations (if SBM prior used).
    • nchains — Number of chains.
    • niter — Number of post-warmup iterations per chain.
    • parameter_names — Named lists of parameter labels.
  • arguments — A list of function call arguments and metadata.

Additional summaries when edge_prior = "Stochastic-Block" (see Sekulovski et al., 2025):

  • posterior_summary_pairwise_allocations — Data frame with posterior summaries (mean, sd, MCSE, ESS, Rhat) for the pairwise cluster co-occurrence of the nodes. This serves to indicate whether the estimated posterior allocations, co-clustering matrix and posterior cluster probabilities have converged.
  • posterior_coclustering_matrix — Symmetric matrix of pairwise proportions of occurrence of every variable. This matrix can be plotted to visually inspect the estimated number of clusters and visually inspect nodes that tend to switch clusters.
  • posterior_mean_allocations — A vector with the posterior mean of the cluster allocations of the nodes.
  • posterior_mode_allocations — A vector with the posterior mode of the cluster allocations of the nodes.
  • posterior_num_blocks — A data frame with the estimated posterior inclusion probabilities for all the possible number of clusters.

NUTS diagnostics (tree depth, divergences, energy, E-BFMI) are available in fit$nuts_diag when update_method = "nuts".

Details

For full explanations, see the guide. Model-specific assumptions and parameterization are described in Ordinal MRF, Gaussian Graphical Model, and Mixed MRF. Prior specification and structure learning are discussed in Prior Basics, Edge Selection, and Edge Clustering. To interpret outputs and verify chain quality, see MCMC Output and MCMC Diagnostics.

Examples

fit = bgm(x = Wenchuan, chains = 2)

See also

Getting Started, Methods, Extractor Functions, and bgmCompare().

References

Marsman, M., van den Bergh, D., & Haslbeck, J. M. B. (2025). Bayesian analysis of the ordinal Markov random field. Psychometrika, 90(1), 146–182. https://doi.org/10.1017/psy.2024.4
Sekulovski, N., Arena, G., Haslbeck, J. M. B., Huth, K. B. S., Friel, N., & Marsman, M. (2025). A stochastic block prior for clustering in graphical models. Manuscript Submitted for Publication. https://osf.io/preprints/psyarxiv/29p3m_v3