race.dist city rows are municipality-scoped, not metro: Atlanta Hispanic share is out by a factor of 3.6

[smjenness]

Surfaced while rebuilding the Atlanta calibration targets for EpiModelHIV-p v4.0. Filing here under popsize2026 because it is the same family of problem as #79/#80, though it is about population composition rather than size, so the two are orthogonal and both have to be right.

The finding

ARTnetData::race.dist$city, row "Atlanta", is White.Other 43.9, Black 51.5, Hispanic 4.6. Those are not metro figures. Men aged 15-64 across the four EHE-priority counties (Cobb, DeKalb, Fulton, Gwinnett) are Black 36.5, Hispanic 15.9, White/Other 47.6 on Census PEP vintage 2024.

A 4.6% Hispanic share is not attainable for metropolitan Atlanta. It is about right for the city of Atlanta municipality.

The state rows are fine, which is what makes me think the issue is scope rather than staleness:

	Black	Hispanic	White/Other
race.dist$state row GA	31.1	10.4	58.5
Georgia, men 15-64, Census 2024	31.5	12.8	55.8
race.dist$city row Atlanta	51.5	4.6	43.9
4-county Atlanta EHE metro, men 15-64, 2024	36.5	15.9	47.6

The state row tracks Census closely, with the Hispanic gap consistent with an older vintage (that share has been rising about 0.33 points a year). The city row is not explicable as a vintage effect.

Why it matters here

build_netstats() reads race.dist[[geog.lvl]] when race.prop is NULL, so a project calling build_epistats(geog.lvl = "city", geog.cat = "Atlanta") gets MSA-scoped behavioral data over municipality-scoped racial composition. At N = 100,000 that is 51,500 Black and 4,600 Hispanic agents instead of roughly 36,600 and 16,600.

This compounds with the popsize2026 work rather than being separate from it. Getting N right and the composition wrong still leaves every race-specific rate wrong, because the race-specific denominator is N times the share. In our case the Hispanic share alone was moving the Hispanic diagnosis rate by more than a factor of three, which is larger than the Grey-vs-Islek spread.

It also bears directly on #80. Surveillance MSM rates are published for a jurisdiction, so the denominator has to be scoped to that jurisdiction. If race.dist is municipality-scoped and the surveillance numerator is county-scoped, the mismatch is in the composition as well as the size.

Questions

1. What geography do the city rows actually cover, and where did they come from? If they are places rather than CBSAs, that should be documented, because geog.lvl = "city" reads naturally as "the metro area we sampled in" and the behavioral side of ARTnet is MSA-based.
2. Should the city rows be re-scoped to CBSAs to match the behavioral data, or should a parallel metro-scoped table be added, leaving the existing rows in place for reproducibility?
3. All 15 city rows are worth checking, not just Atlanta. The ones whose central city differs sharply from its suburbs (Detroit at 78.8% Black, Miami at 72.2% Hispanic, Washington DC at 46.3% Black) are where a place-versus-CBSA scope error would be largest.

Workaround in use

race.prop already overrides this cleanly and is a documented formal of build_netstats(), ordered Black / Hispanic / White-Other. EpiModelHIV-Template on v4.0.x now passes it explicitly with the four-county figures and a comment explaining why, so no ARTnetData change is needed to unblock us.

Reproduce the Census numbers with inst/AHEAD/scripts/02-census-race-distribution.py on EpiModelHIV-p v4.0.x (standard library only, no API key; the Census API now requires one, so it reads the Population Estimates bulk file).

Related: EpiModel/EpiModelHIV-p#230, and EpiModel/ARTnetPredict, whose Atlanta reference run hardcodes these same values.

[smjenness]

Cross-linking: this now blocks EpiModel/EpiModelHIV-p#375, the tracking issue for the v4.0 milestone's upstream dependencies. That issue records what "resolved" means from our side, namely that our race.prop override in EpiModelHIV-Template needs to end up in step with whatever is decided here, and that the popsize2026 decision on N (#84) sets the denominator for the new HIV diagnosis-rate targets. The Atlanta slice of the #80 denominator audit is largely written up in inst/AHEAD/DERIVATION.md on EpiModelHIV-p v4.0.x if it is useful there.