Joint dyad-level modeling: nodematch + absdiff (#63 phases 1 & 2)

[smjenness]

Summary

Under method = "joint", nodematch_* and absdiff_* target statistics now come from per-ego g-computation on dyad-level joint GLMs, not from scaling univariate marginals by the new edge count. Partially addresses #63 (phases 1 and 2). Phase 3 (duration / dissolution with method flag) lands in a follow-up PR.

Default method = "existing" is byte-identical to pre-refactor — verified.

Approach (Option A per #63)

Fit on partnership-level data (lmain / lcasl / linst) with only ego attributes on the RHS (matching PR #68's synthetic-newdata structure). Aggregate per-ego predictions weighted by the joint-Poisson-predicted degree.

New additive outputs on netparams per layer when method = "joint":

Field	Model
joint_nm_age_model	glm(same.age.grp ~ age + race + hiv [+ geog], family = binomial)
joint_nm_race_model (race = TRUE only)	glm(same.race ~ age + race + hiv [+ geog], family = binomial)
joint_absdiff_age_model	glm(ad ~ age + race + hiv [+ geog], family = gaussian)
joint_absdiff_sqrtage_model	glm(ad.sr ~ age + race + hiv [+ geog], family = gaussian)

All use the existing fit_joint_glm() helper with AIC-based interaction selection over {age.grp:race.cat.num}.

In build_netstats under method = "joint":

nodematch_<attr>[level] <- sum(pred_deg * pred_dyad)[ego in level] / 2
absdiff_age             <- sum(pred_deg * pred_ad_age) / 2

where pred_deg comes from the layer's joint Poisson and pred_dyad is the per-ego expected partnership property. Each edge double-counted (from both endpoints), divide by 2.

Empirical (Atlanta, race = TRUE, N = 10k)

All 12 dyad models converge without warnings, nobs 2557/5790/7462. Marginal recovery on training data is exact for every model (expected for GLMs with intercept).

AIC-selected interactions — age.grp:race.cat.num picked for 8/12 models. Race-conditional mixing structure is real and heterogeneous with age.

Layer × Model	AIC	Interactions kept
main × nm_age	3259	—
main × nm_race	2725	age:race
main × absdiff_age	16822	—
main × absdiff_sqrtage	4071	—
casl × nm_age	6973	age:race
casl × nm_race	7052	age:race
casl × absdiff_age	41027	age:race
casl × absdiff_sqrtage	12302	age:race
inst × nm_age	9315	—
inst × nm_race	9076	age:race
inst × absdiff_age	51882	—
inst × absdiff_sqrtage	15004	—

Target-stat shifts vs existing method:

Field	Existing	Joint	Δ
main$edges	1990.3	1697.9	−14.7%
main$absdiff_age	10056	10592	+5.3%
main$absdiff_sqrt.age	848.0	863.2	+1.8%
main$nodematch_race_diffF	1518.9	1192.9	−21.5%

nodematch_race[r] per-race is largely consistent in absolute terms — the big drop in nodematch_race_diffF comes from the edges shift, not the race-match rate itself.

Validation

• Backward-compat snapshot harness: default and explicit method = "existing" match 3/3 on all parameter sets (Atlanta+race, national no-geog, Atlanta no-race).
• Identity: sum(nodematch_race) == nodematch_race_diffF holds to machine precision across all layers.
• Bound: sum(nodematch_<attr>) <= edges verified for age.grp and race on all layers.
• Joint ≠ existing: absdiff_age and nodematch_race_diffF both diverge >1% on main, confirming the refactor actually changes something.

Tests

tests/testthat/test-joint-dyad.R — 8 test blocks, 77 assertions:

• Dyad models present when method = "joint", absent when "existing".
• All dyad models converge with correct family.
• Marginal recovery within 1%.
• sum(nodematch_race) == nodematch_race_diffF.
• sum(nodematch_<attr>) <= edges.
• Joint differs from existing by > 1% on at least one key target.
• race = FALSE path handles nm_race gracefully (no fit, no target stat).

Existing tests still pass: test-joint-model.R (77), test-joint-netstats.R (29). Total: 180/180.

What's still deferred

• Duration / dissolution — Phase 3 of [Phase 1.3] Joint modeling for nodematch + absdiff + dissolution (dyad-level target stats) #63, next PR. Per PI request, this gets a duration.method flag with options {"empirical", "weibull_strat", "joint_lm"}, default "empirical" (byte-identical). See discussion on [Phase 1.3] Joint modeling for nodematch + absdiff + dissolution (dyad-level target stats) #63.
• End-to-end EpiModelHIV-Template estimation — moves to the PR that lands [Phase 1.3] Joint modeling for nodematch + absdiff + dissolution (dyad-level target stats) #63 (after duration refactor), where netstats is finally end-to-end joint-driven.

Test plan

• Backward-compat snapshot match 3/3
• All dyad models converge
• Marginal recovery < 1% on training data
• nodematch identity + nonneg bound
• Joint ≠ existing (> 1% divergence on at least one target)
• race = FALSE path works
• Unit tests 180/180

Depends on #61, #62 (merged). Part of #63. Unblocks the duration PR + the EpiModelHIV-Template end-to-end.