bgmCompare()

Compares group differences in networks for discrete (binary and ordinal) variables using Bayesian estimation and optional difference selection.

Description

bgmCompare() extends bgm() to test group differences in threshold and partial-association parameters for discrete MRFs. Groups can be supplied as two datasets (x and y) or through a grouping vector in group_indicator. This page is the technical reference for arguments and return values. For workflow and interpretation, see Group Comparison, Edge Selection, MCMC Output, and MCMC Diagnostics. Methodological background is provided in Marsman et al. (2025).

Usage

bgmCompare(
  x,
  y,
  group_indicator,
  difference_selection = TRUE,
  main_difference_selection = FALSE,
  variable_type = "ordinal",
  baseline_category,
  difference_scale = 1,
  difference_prior = c("Bernoulli", "Beta-Bernoulli"),
  difference_probability = 0.5,
  beta_bernoulli_alpha = 1,
  beta_bernoulli_beta = 1,
  pairwise_scale = 1,
  main_alpha = 0.5,
  main_beta = 0.5,
  iter = 1000,
  warmup = 1000,
  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,
  verbose = getOption("bgms.verbose", TRUE)
)

Arguments

Data and groups

Argument Description
x A data frame or matrix of binary and ordinal responses for Group 1. Variables should be coded as nonnegative integers starting at 0. For ordinal variables, unused categories are collapsed; for Blume–Capel variables, all categories are retained.
y Optional data frame or matrix for Group 2 (two-group designs). Must have the same variables (columns) as x.
group_indicator Optional integer vector of group memberships for rows of x (multi-group designs). Ignored if y is supplied.
variable_type Character vector specifying the type of each variable: "ordinal" (default) or "blume-capel".
baseline_category Integer or vector giving the baseline category for Blume–Capel variables.
na_action How to handle missing data: "listwise" (drop rows) or "impute" (impute within Gibbs sampler, propagating uncertainty). Default: "listwise". See Missing Data for details.

Difference selection

Argument Description
difference_selection Logical. If TRUE, spike-and-slab priors are applied to difference parameters. Default: TRUE.
main_difference_selection Logical. If TRUE, apply spike-and-slab selection to main effect (threshold) differences. Since main effects are often nuisance parameters and their selection can interfere with pairwise selection under the Beta-Bernoulli prior, the default is FALSE. Only used when difference_selection = TRUE.
difference_scale Scale of the Cauchy prior for difference parameters. Default: 1.
difference_prior Prior for difference inclusion: "Bernoulli" or "Beta-Bernoulli". Default: "Bernoulli".
difference_probability Prior inclusion probability for differences (Bernoulli prior). Default: 0.5.
beta_bernoulli_alpha, beta_bernoulli_beta Shape parameters of the Beta prior for inclusion probabilities in the Beta–Bernoulli model. Defaults: 1.

Prior specification

Argument Description
pairwise_scale Scale of the Cauchy prior for baseline partial associations. Default: 1.
main_alpha, main_beta Shape parameters of the beta-prime prior for baseline threshold parameters. Defaults: 0.5.
standardize Logical. If TRUE, the Cauchy prior scale for each partial association (both baseline and difference) is adjusted based on the range of response scores. Default: FALSE.

Sampler settings

Argument Description
iter Number of post-warmup iterations per chain. Default: 1000.
warmup Number of warmup iterations before sampling. Default: 1000.
update_method Sampling algorithm: "nuts" or "adaptive-metropolis". "hamiltonian-mc" is accepted but deprecated; use "nuts" instead. Default: "nuts".
target_accept Target acceptance rate. Defaults: 0.44 (Metropolis), 0.80 (NUTS).
hmc_num_leapfrogs Deprecated. Leapfrog steps for HMC. Only relevant when update_method = "hamiltonian-mc", which is deprecated. Default: 100.
nuts_max_depth Maximum tree depth for NUTS. Default: 10.
learn_mass_matrix Logical. If TRUE, adapts a diagonal mass matrix during warmup (NUTS only). Default: TRUE.
chains Number of parallel chains. Default: 4.
cores Number of CPU cores. Default: parallel::detectCores().
display_progress Progress reporting: "per-chain", "total", or "none". Default: "per-chain".
seed Optional integer seed for reproducibility.
verbose Logical. Print informational messages during data processing. Default: getOption("bgms.verbose", TRUE).

Value

An S7 object of class bgmCompare with posterior summaries, posterior mean matrices, and raw MCMC samples. Standard methods such as print(), summary(), and coef() work through S3 dispatch for compatibility.

Main components:

  • posterior_summary_main_baseline, posterior_summary_pairwise_baseline — Data frames with posterior summaries (mean, sd, MCSE, ESS, Rhat) for baseline threshold and partial association parameters.
  • posterior_summary_main_differences, posterior_summary_pairwise_differences — Data frames with posterior summaries for group differences in thresholds and partial associations. Includes posterior inclusion probabilities when difference_selection = TRUE.
  • posterior_summary_indicator — Data frame with posterior summaries for difference inclusion indicators (if difference_selection = TRUE).
  • posterior_mean_main_baseline — Matrix of posterior mean baseline thresholds (p x max_categories).
  • posterior_mean_associations_baseline — Symmetric matrix of posterior mean baseline partial associations.
  • posterior_mean_main_differences — Matrix of posterior mean threshold differences.
  • posterior_mean_associations_differences — Symmetric matrix of posterior mean partial association differences.
  • posterior_mean_indicator — Symmetric matrix of posterior inclusion probabilities for differences (if difference_selection = TRUE).
  • raw_samples — List of raw MCMC draws per chain with sublists:
    • main_baseline, pairwise_baseline — Baseline parameter samples.
    • main_differences, pairwise_differences — Difference parameter samples.
    • indicator — Difference indicator samples (if enabled).
    • nchains, niter — Number of chains and iterations per chain.
  • arguments — List of function call arguments and metadata.

NUTS diagnostics are available in fit$nuts_diag when update_method = "nuts".

Details

For full explanations, see the guide. The modeling setup for cross-group contrasts is explained in Group Comparison, with related background in Graphical Models. Prior choices for difference selection are discussed in Edge Selection, and output interpretation and convergence checks are covered in MCMC Output and MCMC Diagnostics.

Warning

update_method = "hamiltonian-mc" is deprecated and will be removed in a future release. Prefer update_method = "nuts".

Examples

# Compare French and non-French groups on a subset of the Boredom data
x = Boredom[Boredom$language == "fr", 2:6]
y = Boredom[Boredom$language != "fr", 2:6]

fit = bgmCompare(x, y, chains = 2)

# Posterior inclusion probabilities
summary(fit)$indicator

# Bayesian model averaged main effects for the groups
coef(fit)$main_effects_groups

# Bayesian model averaged pairwise effects for the groups
coef(fit)$pairwise_effects_groups

See also

bgm(), Methods, Extractor Functions, and Group Comparison.

References

Marsman, M., Waldorp, L. J., Sekulovski, N., & Haslbeck, J. M. B. (2025). Bayes factor tests for group differences in ordinal and binary graphical models. Psychometrika, 90(5), 1809–1842. https://doi.org/10.1017/psy.2025.10060