target_pop API: list / data.frame / character forms (#64, Phase 1.4)

[smjenness]

Closes #64. Adds a single target_pop argument to build_netstats() that unifies post-stratification of the synthetic target population.

API

target_pop accepts four forms:

Form	What it does
NULL (default)	Legacy patchwork-of-references behavior — byte-identical to pre-#64
Named list	Per-marginal overrides for {age.pyramid, race.prop, deg.casl, deg.main, deg.tot, role.class, risk.grp}. Missing names fall through to defaults
data.frame	One row per node. Required: age, deg.casl, deg.main, role.class, risk.grp (+ race when race = TRUE). Optional with derivation: sqrt.age, age.grp, active.sex, deg.tot, diag.status. network.size is overridden to nrow(target_pop)
Character	Reserved for built-in references (e.g., "atlanta", "us_msm_male") bundled from NCHS age pyramid + ARTnetData::race.dist by geography. Raises a clear not-yet-implemented error for now

Why each form

• List form unifies what was previously several args (age.pyramid, race.prop) and extends the override surface to per-attribute distributions previously sourced silently from netparams. One place to set every marginal you might want to override.
• data.frame form is the meaningful new capability for the ARTnetPredict 2024-projection workflow: post-stratify ARTnet targets to AMIS demographics or any user-specified joint distribution by handing in a fully-specified synthetic cohort. Bypasses sampling entirely, no marginal-vs-joint independence assumption.
• Character form is a planned hook for built-in reference populations. Stubbed out with an informative error so the API surface is locked in even though the data isn't shipped yet.

Implementation

• New private helper .parse_target_pop() does form detection, column / element validation, and normalization (e.g., handles race.props alias for race.prop).
• The "Nodal Attribute Initialization" block is restructured into an if/else: data.frame form pulls attrs directly into the same attr_* locals the sampling path produces; sampling path applies list-form distribution overrides via .dist_* locals.
• The diag.status block honors a user-supplied diag.status column when data.frame form provides one; otherwise falls through to the existing epistats-based draw using the user's attribute vectors.
• Common out$attr assignments factored out so both code paths share one place to populate.

Validation

• Backward-compat snapshot harness: 3/3 match on default and explicit method = "existing" (this is the real test that the restructuring didn't break anything).
• Full testthat suite: 571 / 571 pass.
• R CMD check: 0 errors / 0 warnings / 0 notes.

Tests

tests/testthat/test-target-pop.R — 12 blocks, 25 assertions. Covers:

• NULL byte-identical to no-arg (regression test)
• list form: race.prop override produces matching race composition; deg.casl override produces matching distribution; race.props alias normalized to race.prop; unknown list elements raise informative error
• data.frame form: attributes pass through; deg.tot cap derivation; missing-required-column error; diag.status falls back to epistats when absent; composes with method = "joint" (internal consistency sum(nf_*) == 2 * edges still holds)
• character form: not-yet-implemented error message
• Bad input: non-list/df/char raises "must be NULL, a list, a data.frame, or a character string"

Test plan

• NULL byte-identical to legacy (snapshot match 3/3)
• List form overrides each supported marginal correctly
• data.frame form bypasses sampling, derives missing columns, composes with method = "joint"
• Character form raises clear error
• All 4 forms validated end-to-end manually + 25 unit assertions
• R CMD check 0/0/0
• Built-in geography-named reference bundles (e.g., "atlanta", "us_msm_male"): tracked as future work. Implementation is a lookup table from name to list(age.pyramid = ..., race.prop = ...) using NCHS age pyramid (already in build_netstats) + ARTnetData::race.dist (already shipped) — no new external data needed.

Closes #64. With #64 + #65 + the joint g-comp refactor (#61–#74) all landed, the ARTnet → ERGM target stat pipeline is now fully joint-corrected and post-stratifiable.