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, Model 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_family = c("Normal", "Cauchy"),
  difference_prior = bernoulli_prior(0.5),
  interaction_prior = normal_prior(scale = 1),
  threshold_prior = beta_prime_prior(alpha = 0.5, beta = 0.5),
  iter = 2000,
  warmup = 2000,
  na_action = c("listwise", "impute"),
  update_method = c("nuts", "adaptive-metropolis"),
  target_accept,
  nuts_max_depth = 10,
  learn_mass_matrix = TRUE,
  chains = 4,
  cores = parallel::detectCores(),
  display_progress = c("per-chain", "total", "none"),
  seed = NULL,
  verbose = getOption("bgms.verbose", TRUE),
  progress_callback = NULL
)

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 the contrast parameters that encode group differences (for two groups, a single scaled difference; for \(G > 2\) groups, \(G - 1\) orthogonal contrasts). 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 prior for the contrast parameters. Default: 1.
difference_family	Character. Distributional family of the slab prior on the contrast parameters, one of "Normal" (default) or "Cauchy". Independent of interaction_prior, which governs the baseline interactions.
difference_prior	A bgms_indicator_prior object specifying the prior on difference inclusion. Allowed: bernoulli_prior() (default), beta_bernoulli_prior(), or sbm_prior() — see the note below the table for the SBM case. Legacy character strings ("Bernoulli", "Beta-Bernoulli", "Stochastic-Block") and the scalar difference_probability / beta_bernoulli_alpha / beta_bernoulli_beta arguments are accepted but deprecated. Default: bernoulli_prior(0.5).

Under difference_prior = sbm_prior(...), the stochastic block model governs the off-diagonal (pairwise) difference inclusions; the diagonal (main-effect difference inclusions, when main_difference_selection = TRUE) follows a separate Beta-Bernoulli prior using the within-cluster alpha and beta.

Prior specification

Priors on baseline parameters are specified via prior-object constructors (see Prior Constructors). The legacy scalar arguments listed under the table are deprecated as of bgms 0.2.0 — they still work but emit a lifecycle warning.

Argument	Description
interaction_prior	A bgms_parameter_prior object for baseline pairwise interactions. Allowed: normal_prior() (default), cauchy_prior(). This matches the default in bgm(), so a comparison and separate single-group fits place the same prior on a baseline interaction. Default: normal_prior(scale = 1).
threshold_prior	A bgms_parameter_prior object for baseline threshold parameters. Allowed: beta_prime_prior() (default), normal_prior(). Default: beta_prime_prior(alpha = 0.5, beta = 0.5).

NoteDeprecated arguments

Deprecated	Replacement
standardize	No replacement; see the note below the table
pairwise_scale = s	interaction_prior = cauchy_prior(scale = s)
main_alpha = a, main_beta = b	threshold_prior = beta_prime_prior(alpha = a, beta = b)
difference_probability = p	difference_prior = bernoulli_prior(p)
beta_bernoulli_alpha = a, beta_bernoulli_beta = b	difference_prior = beta_bernoulli_prior(a, b)
pairwise_difference_scale, main_difference_scale	difference_scale
pairwise_difference_prior, main_difference_prior	difference_prior
pairwise_difference_probability, main_difference_probability	difference_prior = bernoulli_prior(p)
pairwise_beta_bernoulli_alpha/beta, main_beta_bernoulli_alpha/beta	difference_prior = beta_bernoulli_prior(a, b)
main_difference_model, reference_category	No replacement (removed model options)
interaction_scale = s	interaction_prior = cauchy_prior(scale = s) (deprecated since 0.1.6.0)
threshold_alpha = a, threshold_beta = b	threshold_prior = beta_prime_prior(alpha = a, beta = b) (deprecated since 0.1.6.0)
burnin = n	warmup = n (deprecated since 0.1.6.0)
save	No replacement; raw samples are always stored (deprecated since 0.1.6.0)

standardize scaled each pair’s baseline and difference prior by the product of the two variables’ maximum scores; pairwise interactions are now on the association scale and share one prior scale, so the adjustment is gone. standardize = FALSE, the old default, is what the sampler does, so it warns and fits; standardize = TRUE errors and points you at setting the scales directly through interaction_prior and difference_scale.

Sampler settings

Argument	Description
iter	Number of post-warmup iterations per chain. Default: 2000.
warmup	Number of warmup iterations before sampling. Default: 2000.
update_method	Sampling algorithm: "nuts" or "adaptive-metropolis". Default: "nuts".
target_accept	Target acceptance rate. Defaults: 0.44 (Metropolis), 0.80 (NUTS).
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).
progress_callback	Optional R function with signature function(completed, total), called at regular intervals during sampling with the number of completed and total iterations across all chains. Useful for external front-ends (e.g., JASP). Default: NULL (no callback).

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 the contrast parameters of 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_pairwise_baseline — Symmetric matrix of posterior mean baseline partial associations.
• posterior_mean_main_differences — Matrix of posterior mean threshold differences.
• posterior_mean_pairwise_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).
  • rb_inclusion, rb_counts — Rao-Blackwellized inclusion draws for the difference indicators and the per-indicator odds accumulators behind them (if enabled); see extract_posterior_inclusion_probabilities() and extract_inclusion_bf().
  • allocations — Cluster allocation samples (SBM difference prior only).
  • nchains, niter — Number of chains and iterations per chain.
• arguments — List of function call arguments and metadata.

When difference_prior = sbm_prior(...), the following SBM summaries are also populated (see extract_sbm() for a helper):

• posterior_num_blocks — Posterior probabilities for each possible number of clusters, computed under the shifted-Poisson prior on the number of clusters (see Edge Clustering).
• posterior_mean_allocations — Posterior mean cluster allocations.
• posterior_mode_allocations — Posterior mode cluster allocations.
• posterior_mean_coclustering_matrix — Co-clustering proportion matrix.
• posterior_summary_pairwise_allocations — Pairwise allocation convergence summary.

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 Model Output and MCMC Diagnostics.

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, seed = 123)

# 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