feat(bgm): dimension-adaptive auto-default for the determinant tilt

[MaartenMarsman]

Summary

Implements Stage 1 of dev/plans/backlog/hierarchical-ggm-degord-rr.md: a dimension-adaptive auto-default for the delta argument.

bgm() and sample_ggm_prior() now accept delta = NULL (the new default), which resolves to

$$\delta(p) = 0.5 \cdot \log(p)$$

where $p$ is the dimension of the continuous precision matrix. This is the simple form of the dimension-adaptive scaling $\delta(p) = c \cdot \log p$ with $c \in (0.3, 0.6)$ established in the companion paper on determinant-tilted spike-and-slab priors (Marsman et al., in preparation). The rule keeps the prior bulk in the positive-definite cone interior uniformly in $p$, whereas constant $\delta$ drifts off-target and the G-Wishart-style linear rule $(q-2)/2$ overshoots.

At common dimensions the auto-default produces sensible values:

p	5	10	20	50	100
auto	0.80	1.15	1.50	1.96	2.30

Changes

• R/bgm.R: signature delta = 0 → delta = NULL; roxygen documents the auto-default, the companion-paper motivation, and the explicit override path.
• R/bgm_spec.R: signature delta = 0 → delta = NULL; resolver added after model_type is finalized. Routing:
  • GGM: $\delta = 0.5 \log(\textnormal{num_variables})$
  • Mixed MRF: $\delta = 0.5 \log(\textnormal{num_continuous})$
  • OMRF / compare: $\delta = 0$ (no continuous block to tilt; the existing validation already forbids $\delta > 0$ here)
• R/sample_ggm_prior.R: same treatment; GGM-only so the resolver is simply $0.5 \log(p)$.
• Roxygen: regenerated man/bgm.Rd and man/sample_ggm_prior.Rd via devtools::document().
• Tests: four tests that relied on the implicit delta = 0 for their original calibration (3 GGM SBC tests + M.2J mixed-MRF NUTS diagnostics) now pass delta = 0 explicitly. Their prior generators sample from the untilted prior; explicit delta = 0 preserves the test's calibration.

Behavior change

Users who previously called bgm() or sample_ggm_prior() without specifying delta get the tilted prior by default. Reproducibility note: chains with the same seed will differ from previous versions; pass delta = 0 to recover identical behavior.

Test plan

• Smoke test: sample_ggm_prior(p = 4, delta = NULL) resolves to $\delta \approx 0.693$ and produces finite draws.
• Smoke test: sample_ggm_prior(p = 4, delta = 0) continues to work (explicit untilted).
• Smoke test: sample_ggm_prior(p = 4, delta = -1) errors with a clear message.
• Fast test suite: 6786/6786 assertions pass.
• Slow tests (filter sbc-ggm|parameter-recovery-ggm|ggm-nuts|mixed-nuts|scaling-diagnostics): all pass after the four targeted patches.
• CI green.

Companion / next stage

Stage 2 follows: sample_ggm_prior(spec = "joint") for joint-specification SBC. The auto-default exposed here applies in either spec.

[codecov]

Codecov Report

❌ Patch coverage is 90.90909% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 87.42%. Comparing base (cb68f0e) to head (eda8f4b).

Files with missing lines	Patch %	Lines
R/sample_ggm_prior.R	66.66%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #107      +/-   ##
==========================================
+ Coverage   87.34%   87.42%   +0.07%     
==========================================
  Files          77       77              
  Lines       13441    13450       +9     
==========================================
+ Hits        11740    11758      +18     
+ Misses       1701     1692       -9     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.