Method comparison validation suite (#65, Phase 1.5)

[smjenness]

Closes #65. Now that the joint g-comp refactor is fully landed (PRs #67 / #68 / #69 / #71 / #74), this PR adds the systematic marginal-vs-joint comparison the validation phase calls for.

What's new

inst/validation/method_comparison.R — three entry points, designed to be sourced via system.file():

source(system.file("validation/method_comparison.R", package = "ARTnet"))
res <- compare_methods()              # full suite, ~30s
summarize_comparison(res)             # console summary
render_comparison_report(res)         # writes inst/validation/method_comparison.md

The harness walks every numeric target stat in netstats per layer (edges, nodefactor_, nodematch_, absdiff_*, concurrent, dissolution_duration) and produces a long-format data.frame with one row per (scenario, layer, stat, level) cell — existing and joint values side-by-side, plus abs_diff and pct_diff.

Four scenarios:

Scenario	Description
atlanta_default	Baseline EpiModelHIV-Template config (Atlanta, race = TRUE)
national_no_geog	No geographic stratification (sanity check)
atlanta_nhbs_shifted	Atlanta config with race.prop = c(0.35, 0.25, 0.40) (NHBS-MSM-like)
atlanta_no_race	race = FALSE path (sanity check)

inst/validation/method_comparison.md is the canonical rendered report of this run, committed to the repo so anyone can read the comparison without running the harness. It will feed methods-paper drafting work directly.

Headline findings (full breakdown in method_comparison.md)

• 363 target-stat cells across 4 scenarios
• 229 cells (~63%) shift > 5% under joint vs existing
• Per scenario:
  • atlanta_default: 63 / 96 cells materially shifted
  • national_no_geog: 51 / 96
  • atlanta_nhbs_shifted: 66 / 96 (slightly more than default — NHBS race mix stresses the correction further)
  • atlanta_no_race: 49 / 75 (race off, but dyad-level corrections still drive the divergence)

Largest shifts cluster around:

• dissolution_duration matched-and-old strata (matched.5 main: −47% across all scenarios). This is the multivariate-fit-vs-stratum-only-empirical-with-smoothing tradeoff documented in PR Duration methods: empirical + joint_lm (#63 phase 3) #71.
• inst$nodematch_age.grp[5] (small targets dominated by AIC-selected interactions in Joint dyad-level modeling: nodematch + absdiff (#63 phases 1 & 2) #69's joint dyad fits).
• casl$nodefactor_deg.main[3] (+35–43%): high-deg.main outliers are sparse in ARTnet, so Poisson joint fit produces noticeably different per-stratum sums than the marginal × deg.main.dist multiplication.

What it confirms

• The joint refactor is doing material work — not a no-op. Substantial fraction of every layer's target stats are corrected.
• The correction direction is consistent across scenarios (e.g., main dissolution durations always pulled down for older matched strata, whether we're looking at default Atlanta, NHBS-shifted, or national).
• atlanta_nhbs_shifted sees more material shifts than atlanta_default, consistent with the marginal-vs-joint critique: the bigger the gap between target-population and ARTnet sample composition, the more the correction matters.

Tests

tests/testthat/test-method-comparison.R (4 blocks): structure check, arithmetic check, dissolution_duration scoping, baseline divergence sanity. Uses a 2000-node mini scenario for speed; full suite stays at 5000.

Test plan

• Backward-compat snapshot harness 3/3
• Comparison runs without error across all 4 scenarios
• Output structure matches spec (long format, all expected stats)
• Unit tests pass (4/4); full suite 546/546 passes
• R CMD check 0/0/0
• inst/validation/method_comparison.md rendered and committed

Closes #65. Logical follow-up: #64 (post-stratification API) — with these comparison results in hand, we know the magnitudes of population-shift effects and can size the API surface accordingly.