Skip to content

Add research report on the joint g-computation refactor#78

Merged
smjenness merged 1 commit intomainfrom
docs/refactor-report
Apr 25, 2026
Merged

Add research report on the joint g-computation refactor#78
smjenness merged 1 commit intomainfrom
docs/refactor-report

Conversation

@smjenness
Copy link
Copy Markdown
Contributor

A standalone ~2,800-word writeup documenting the joint g-computation refactor that the package shipped via PRs #66 through #77. Lives at inst/validation/method_refactor_report.md, parallel to the machine-generated comparison report method_comparison.md.

Structured as a research report:

  • Introduction — ARTnet's role in EpiModelHIV-p; the marginal-vs-joint problem; the ARTnetPredict motivation for fixing the within-ARTnet baseline before applying ML-based forward projection
  • Methods — the three new arguments (method, duration.method, target_pop); per-layer joint GLMs (Poisson, binomial, Gaussian, log-linear) with AIC-based interaction selection; g-computation aggregation in build_netstats; the deliberate choice that durations target mean age of extant ties at cross-section rather than mean full partnership duration (Steve Goodreau's framing in Length-biased sampling and 5-partnership truncation bias in formation target stats #72); validation infrastructure
  • Results — headline finding: 229/363 cells (63%) shift > 5% across four scenarios; worst shifts on matched-and-old dissolution durations (−47%), older-age inst nodematch (−51%), high-deg.main casual nodefactor (+40%); concrete decomposition of the −15% Atlanta main-edges shift to the ARTnet vs Atlanta race composition gap; coefficient strengthening on deg.casl (−0.24 → −0.55), hiv2 (+0.09 → +0.25); end-to-end ERGM convergence verified
  • Discussion — implications for EpiModelHIV-p (Atlanta-specific models over-target main edges by ~15% under legacy); three explicit limitations (geometric TERGM dissolution can't honor Weibull k ≠ 1, length-bias and 5-truncation not yet addressed in Length-biased sampling and 5-partnership truncation bias in formation target stats #72, joint_lm uses ongoing-only); ARTnetPredict's three unblocked next steps; outline for a methods paper
  • References + Reproducibility snippet

Numbers cited spot-checked against the committed inst/validation/method_comparison.md for consistency. No code changes; documentation-only PR.

Test plan

  • Word count in target range (2,811 / target 2,000–3,000)
  • Numbers cited match inst/validation/method_comparison.md
  • Sections cover the four requested areas (intro, methods, results, discussion)
  • No code touched — pure docs PR

After this lands, the inst/validation/ directory holds:

  • validate_backward_compat.R + snapshots — backward-compat regression infrastructure
  • method_comparison.R + method_comparison.md — automated cross-method comparison tables
  • method_refactor_report.md — this writeup
  • epimodelhiv_template_ref/ — pinned downstream consumer scripts
  • netstats_contract.md — field-level public contract
  • README.md — workflow guide

Together that covers regression testing, cross-method numerics, and now the methodological narrative.

A 2,800-word standalone writeup at inst/validation/method_refactor_report.md
documenting the methodological refactor delivered by PRs #66-#77.
Structured as introduction / methods / results / discussion + references
+ reproducibility section.

Sections cover:

- Intro: ARTnet's role in EpiModelHIV-p; the marginal-vs-joint
  problem the legacy univariate approach exposed; the ARTnetPredict
  motivation for fixing the within-ARTnet baseline before forward
  projection.
- Methods: the three new arguments (`method`, `duration.method`,
  `target_pop`); per-layer joint Poisson + binomial + Gaussian +
  log-linear fits; g-computation aggregation in build_netstats; the
  cross-sectional age-of-extant-ties target for dissolution; the
  validation infrastructure (snapshot harness, method comparison,
  GHA CI).
- Results: 229/363 cells (63%) shift > 5% across four scenarios;
  worst shifts on dissolution durations in matched-and-old strata
  (-47%), one-time nodematch in older age groups (-51%), and
  high-deg.main casual nodefactor (+40%); decomposition of the -15%
  Atlanta main-edges shift attributed to ARTnet's 80.7% White vs
  Atlanta's 51.5% Black composition; coefficient strengthening on
  deg.casl (-0.24 -> -0.55), hiv2 (+0.09 -> +0.25), age slope, and
  the AIC-selected age:deg.casl interaction; end-to-end ERGM
  convergence with netdx |Z| <= 2.05 across 1000 sims.
- Discussion: implications for EpiModelHIV-p simulations
  (Atlanta-specific models over-target main edges by 15%);
  three explicit limitations (geometric tergm dissolution can't honor
  Weibull k != 1, length-bias and 5-truncation in formation stats not
  yet addressed in #72, joint_lm uses ongoing partnerships only);
  ARTnetPredict's three unblocked next steps (corrected 2017-18
  baseline, 2022-24 AMIS projection via target_pop data.frame, NHBS
  post-stratification as a one-line argument); methods paper outline.

Numbers cited are spot-checked against the committed
inst/validation/method_comparison.md to ensure the report and the
machine-generated comparison agree.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@smjenness smjenness merged commit 58dfaff into main Apr 25, 2026
1 check passed
@smjenness smjenness deleted the docs/refactor-report branch April 25, 2026 21:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant