Technical Manual

Technical documentation for the bgms C++ backend, MCMC algorithms, and R scaffolding layer.

Architecture

How the R front-end and C++ back-end fit together.

  • C++ Architecture — Source layout, layer separation, design principles
  • R Scaffolding — Validation, spec construction, sampler dispatch, output assembly
  • Model Classes — BaseModel hierarchy and the virtual interface that all models implement
  • Parallel Chains — TBB threading, model cloning, per-chain RNG seeding

MCMC Algorithms

The sampling algorithms available in bgms.

  • Adaptive Metropolis — Scalar random-walk Metropolis–Hastings with Robbins–Monro step-size adaptation. Used for discrete parameters (thresholds, interactions) in OMRF and mixed models.
  • NUTS — No-U-Turn Sampler: adaptive-length Hamiltonian Monte Carlo with binary tree expansion and U-turn termination. The default sampler for continuous parameters in mixed models.
  • HMC — Fixed-trajectory Hamiltonian Monte Carlo. Deprecated; NUTS is preferred.
  • Constrained Leapfrog — RATTLE integrator for Hamiltonian dynamics under precision-matrix constraints. Required for mixed models where the precision matrix must remain positive definite.

Sampler Infrastructure

Shared machinery that supports all samplers.

  • Sampler Classes — The SamplerBase interface, gradient-based sampler hierarchy, and factory dispatch
  • Warmup Schedule — Five-stage adaptation: step-size search, mass matrix estimation, dual averaging
  • Convergence Diagnostics — C++ implementation of ESS (AR spectral) and R-hat (Gelman–Rubin)

Model Internals

How each model type computes likelihoods, gradients, and parameter updates.

  • GGM — Free-element Cholesky parameterization of the precision matrix, gradient computation, and edge selection
  • OMRF — Ordinal threshold parameterization, Blume–Capel model, residual matrix bookkeeping, and pseudolikelihood gradients
  • Mixed MRF — Block structure for discrete-continuous interactions, joint parameter updates, and RATTLE constraints

Supporting pages:

  • Pseudolikelihood — Pseudolikelihood objectives for OMRF, mixed MRF, and group-comparison models, including statistical properties and the conditional vs. marginal variants.
  • Fast Computation — Recursive accumulation of MRF category probabilities that avoids per-category exp() calls. The FAST path provides a major speedup; the SAFE path handles overflow-prone cases.

Edge Priors

Prior distributions over graph structure for edge selection.

  • Edge Priors — Overview of the edge prior framework: Bernoulli (fixed), Beta-Bernoulli (learned), and Stochastic Block Model
  • SBM Prior — Mixture-of-finite-mixtures SBM formulation, collapsed Gibbs updates, cluster allocation sampling

Group Comparison

  • bgmCompare Internals — Multi-group parameterization (baseline plus differences), group-specific gradients, difference-edge selection

Cross-Platform Math