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 proposal adaptation. An alternative sampler, selected via update_method = "adaptive-metropolis"; its proposal machinery also drives edge moves during NUTS runs.
  • NUTS — No-U-Turn Sampler: adaptive-length Hamiltonian Monte Carlo with binary tree expansion and U-turn termination. The default sampler for all model types. A conjugate Gibbs sweep for the GGM (update_method = "gibbs") is documented under Sampler Classes.
  • Constrained Cholesky Parameterization — how excluded edges are held exactly at zero, and the precision matrix positive definite, through per-column null-space coordinates rather than constrained integration.

Sampler Infrastructure

Shared machinery that supports all samplers.

  • Sampler Classes — The SamplerBase interface, gradient-based sampler hierarchy, and factory dispatch
  • Warmup Schedule — Multi-stage adaptation with sampler-dependent staging: step-size search, mass matrix estimation, dual averaging, selection-active warmup
  • Convergence Diagnostics — C++ implementation of ESS (AR spectral) and split-R-hat

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 the constrained continuous block

Supporting pages:

  • Pseudolikelihood — Pseudolikelihood objectives for OMRF, mixed MRF, and group-comparison models, including statistical properties and the marginal pseudolikelihood used for mixed models.
  • 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.
  • Simulation and Prediction — Running the models forwards: the standalone and fitted-model generators per model class, the conditional-distribution kernels behind predict(), seeding, and which operations are exact.

Priors

Prior distributions on model parameters and graph structure.

  • Parameter Priors — BaseParameterPrior polymorphic hierarchy for real-valued parameters (Cauchy, Normal, beta-prime, Gamma scale). Polymorphic dispatch replaces hard-coded prior calls in the model code.
  • 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
  • Hierarchical Graph Prior and the Z-Ratio Engine — Per-graph normalized precision prior: the per-edge normalizer ratio, its deterministic estimator, and the trust gauge

Results and Checks

The layer between the finished sampler run and the numbers a reader reports.

  • Fit Objects — The S7 classes behind bgm() and bgmCompare(): what the object stores, the lazy summary cache, the accessor contract, and where the same quantity appears on two scales.
  • Extractor Internals — The layer between the raw draws and the reference API: block reindexing and scale conversion, the two inclusion estimators, the joint-prior correction path, and the derived centrality and clustering summaries.
  • Checks Internals — The three-way verdict rule and its Monte Carlo fragility flag, the calibration resampling schemes for discrete and continuous variables, and the anchored reweighting curve.
  • Sensitivity and Refits — The prior-sensitivity anchor grid, the warm-started refit engine, the two-level convergence gate, and the noise band the mover rule reads.

Group Comparison

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

Cross-Platform Math

  • OpenLibM Integration — Ships portable exp() and log() implementations because the Windows C runtime versions are 4–5x slower than macOS/Linux; includes benchmark details.