The bgmCompare function estimates group differences in category
threshold parameters (main effects) and pairwise interactions (pairwise
effects) of a Markov Random Field (MRF) for binary and ordinal variables.
Groups can be defined either by supplying two separate datasets (x and
y) or by a group membership vector. Optionally, Bayesian variable
selection can be applied to identify differences across groups.
bgmCompare(
x,
y,
group_indicator,
difference_selection = TRUE,
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 = 2.5,
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 = FALSE,
chains = 4,
cores = parallel::detectCores(),
display_progress = c("per-chain", "total", "none"),
seed = NULL,
main_difference_model,
reference_category,
main_difference_scale,
pairwise_difference_scale,
pairwise_difference_prior,
main_difference_prior,
pairwise_difference_probability,
main_difference_probability,
pairwise_beta_bernoulli_alpha,
pairwise_beta_bernoulli_beta,
main_beta_bernoulli_alpha,
main_beta_bernoulli_beta,
interaction_scale,
threshold_alpha,
threshold_beta,
burnin,
save
)A list of class "bgmCompare" containing posterior summaries,
posterior mean matrices, and raw MCMC samples:
posterior_summary_main_baseline,
posterior_summary_pairwise_baseline: summaries of baseline
thresholds and pairwise interactions.
posterior_summary_main_differences,
posterior_summary_pairwise_differences: summaries of group
differences in thresholds and pairwise interactions.
posterior_summary_indicator: summaries of inclusion
indicators (if difference_selection = TRUE).
posterior_mean_main_baseline,
posterior_mean_pairwise_baseline: posterior mean matrices
(legacy style).
raw_samples: list of raw draws per chain for main,
pairwise, and indicator parameters.
arguments: list of function call arguments and metadata.
The summary() method prints formatted summaries, and
coef() extracts posterior means.
NUTS diagnostics (tree depth, divergences, energy, E-BFMI) are included
in fit$nuts_diag if update_method = "nuts".
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.
Optional data frame or matrix for Group 2 (two-group designs).
Must have the same variables (columns) as x.
Optional integer vector of group memberships for
rows of x (multi-group designs). Ignored if y is supplied.
Logical. If TRUE, spike-and-slab priors
are applied to difference parameters. Default: TRUE.
Character vector specifying type of each variable:
"ordinal" (default) or "blume-capel".
Integer or vector giving the baseline category for Blume–Capel variables.
Double. Scale of the Cauchy prior for difference
parameters. Default: 1.
Character. Prior for difference inclusion:
"Bernoulli" or "Beta-Bernoulli". Default: "Bernoulli".
Numeric. Prior inclusion probability for
differences (Bernoulli prior). Default: 0.5.
Doubles. Shape parameters
of the Beta prior for inclusion probabilities in the Beta–Bernoulli
model. Defaults: 1.
Double. Scale of the Cauchy prior for baseline
pairwise interactions. Default: 2.5.
Doubles. Shape parameters of the beta-prime
prior for baseline threshold parameters. Defaults: 0.5.
Integer. Number of post–warmup iterations per chain.
Default: 1e3.
Integer. Number of warmup iterations before sampling.
Default: 1e3.
Character. How to handle missing data:
"listwise" (drop rows) or "impute" (impute within Gibbs).
Default: "listwise".
Character. Sampling algorithm:
"adaptive-metropolis", "hamiltonian-mc", or "nuts".
Default: "nuts".
Numeric between 0 and 1. Target acceptance rate. Defaults: 0.44 (Metropolis), 0.65 (HMC), 0.80 (NUTS).
Integer. Leapfrog steps for HMC. Default: 100.
Integer. Maximum tree depth for NUTS. Default: 10.
Logical. If TRUE, adapt the mass matrix
during warmup (HMC/NUTS only). Default: FALSE.
Integer. Number of parallel chains. Default: 4.
Integer. Number of CPU cores. Default:
parallel::detectCores().
Character. Controls progress reporting:
"per-chain", "total", or "none".
Default: "per-chain".
Optional integer. Random seed for reproducibility.
`r lifecycle::badge("deprecated")` Deprecated arguments as of **bgms 0.1.6.0**. Use `difference_scale`, `difference_prior`, `difference_probability`, `beta_bernoulli_alpha`, `beta_bernoulli_beta`, `baseline_category`, `pairwise_scale`, and `warmup` instead.
For variables \(i\) and \(j\), the group-specific interaction is represented as: $$\theta_{ij}^{(g)} = \phi_{ij} + \delta_{ij}^{(g)},$$ where \(\phi_{ij}\) is the baseline effect and \(\delta_{ij}^{(g)}\) are group differences constrained to sum to zero.
Regular ordinal variables: category thresholds are decomposed into a baseline plus group differences for each category.
Blume–Capel variables: category thresholds are quadratic in the category index, with both the linear and quadratic terms split into a baseline plus group differences.
When difference_selection = TRUE, spike-and-slab priors are
applied to difference parameters:
Bernoulli: fixed prior inclusion probability.
Beta–Bernoulli: inclusion probability given a Beta prior.
Parameters are updated within a Gibbs framework, using the same
sampling algorithms and staged warmup scheme described in
bgm:
Adaptive Metropolis–Hastings: componentwise random–walk proposals with Robbins–Monro adaptation of proposal SDs.
Hamiltonian Monte Carlo (HMC): joint updates with fixed leapfrog trajectories; step size and optionally the mass matrix are adapted during warmup.
No–U–Turn Sampler (NUTS): an adaptive HMC variant with dynamic trajectory lengths; warmup uses the same staged adaptation schedule as HMC.
For details on the staged adaptation schedule (fast–slow–fast phases),
see bgm. In addition, when
difference_selection = TRUE, updates of inclusion indicators are
delayed until late warmup. In HMC/NUTS, this appends two extra phases
(Stage-3b and Stage-3c), so that the total number of warmup iterations
exceeds the user-specified warmup.
After warmup, adaptation is disabled: step size and mass matrix are fixed at their learned values, and proposal SDs remain constant.
This function extends the ordinal MRF framework MarsmanVandenBerghHaslbeck_2024;textualbgms to multiple groups. The basic idea of modeling, analyzing, and testing group differences in MRFs was introduced in MarsmanWaldorpSekulovskiHaslbeck_2024;textualbgms, where two–group comparisons were conducted using adaptive Metropolis sampling. The present implementation generalizes that approach to more than two groups and supports additional samplers (HMC and NUTS) with staged warmup adaptation.
Key components of the model:
vignette("comparison", package = "bgms") for a worked example.
if (FALSE) {
# Run bgmCompare on subset of the Boredom dataset
x = Boredom[Boredom$language == "fr", 2:6]
y = Boredom[Boredom$language != "fr", 2:6]
fit <- bgmCompare(x, y)
# 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
}
Run the code above in your browser using DataLab