fwh_health — disease-burden maps (Facetwork domain)

Choropleth maps of chronic- and infectious-disease burden (cancer / diabetes / Alzheimer's / stroke plus COVID / flu / RSV / HIV / measles), built from open public-health data and published to facetwork-maps. Each map carries a metric dropdown and an amber "where data is missing" note explaining the grey (no-data) areas.

Feature specifications

Per-feature specs live in docs/ — one document per map (or shared capability), each covering how it works, what it renders and what's missing/grey, its external deps, facets/workflows, and cache/output. Start with the flagship NHSN respiratory family.

Spec	What it covers
respiratory-nhsn	Flagship — five US-state COVID/flu/RSV time-slider maps off one NHSN HRD engine
us-mortality	US-state age-adjusted death rates + COVID/flu (CDC NCHS)
us-prevalence	US-county adult prevalence — cancer/diabetes/stroke (CDC PLACES)
world-ncd	World NCD burden + COVID/HIV/measles (WHO GHO + OWID)
world-hiv	World HIV over time, by sex & key population (WHO SDGHIV + UNAIDS)
hiv-transmission	HIV by transmission route — Europe (ECDC) & US (CDC AtlasPlus)
us-autism	US-state autism identification in schools (IDEA §618)
rendering	The static + time-slider MapLibre choropleth renderers
storage-and-geometry	Output backend paths + reused census/Natural Earth geometry
domain-package	Entry-point discovery, facet→builder dispatch, FFL workflows

Full index: docs/README.md.

Maps

Map	Source	Metrics
US mortality by state	CDC NCHS + CDC COVID + CDC FluView	age-adjusted death rates (cancer, stroke, diabetes, Alzheimer's) + COVID deaths/100k + peak flu (ILINet) activity
US prevalence by county	CDC PLACES	adult prevalence — cancer, diabetes, stroke (2,956 counties)
World NCD + infectious burden	WHO GHO + World Bank/OWID	diabetes prevalence, premature-NCD + NCD mortality, COVID deaths/100k, HIV prevalence, measles incidence
World HIV over time	WHO SDGHIV + UNAIDS KP Atlas	HIV prevalence / new infections per country over time, by sex & key population (year slider)
Europe HIV by transmission route	ECDC Surveillance Atlas	new HIV diagnoses by transmission route (sex, IDU, hetero…) per country
US HIV by transmission route	CDC AtlasPlus	new HIV diagnoses by transmission route per state
US autism identification by state	US DoE IDEA §618 Child Count	autism educational-identification rate per state (year span) — schools, not clinical prevalence
US respiratory hospitalizations over time	CDC NHSN HRD	COVID-19 / flu / RSV new admissions per 100k by state, monthly, with a month slider (~5 yrs)
US hospital strain — bed occupancy	CDC NHSN HRD	% of inpatient & ICU beds occupied + share held by each virus, monthly (slider)
US respiratory ICU severity	CDC NHSN HRD	share of hospitalized COVID / flu / RSV patients in the ICU, monthly (slider)
US respiratory admissions — children vs adults	CDC NHSN HRD	admission rates per 100k by virus & age group (RSV/flu in kids), monthly (slider)
US "tripledemic" combined burden	CDC NHSN HRD	combined COVID + flu + RSV admissions per 100k, winter over winter, monthly (slider)

Geometry is reused from the Facetwork ecosystem: US Census TIGER state/county GeoJSON (cached in MinIO by the census-us domain) and Natural Earth country polygons.

Data-availability constraints (honest scope)

Public-health data is fragmented; the maps reflect what's openly redistributable:

• US is well-covered. County-level prevalence (cases) for cancer/diabetes/ stroke from CDC PLACES; state-level deaths for all four chronic causes incl. Alzheimer's from NCHS, plus state COVID deaths/100k (CDC) and peak flu (ILINet) activity (CDC FluView). County-level deaths are suppressed for small counties; Alzheimer's has no prevalence estimate anywhere, so it appears deaths-only. In the county prevalence map, Kentucky & Pennsylvania are blank for all three conditions — CDC PLACES (2025 release) models them from 2023 BRFSS, and KY & PA have no usable 2023 BRFSS sample. This is stated in the map's note.
• Worldwide is thin. Current, openly-redistributable, country-level data for these specific diseases barely exists — IHME/OWID cause series are license- blocked, WHO's cause-specific death series are empty or frozen at 2004, and IARC's cancer API isn't cleanly fetchable. The world map therefore shows the non-communicable-disease burden (diabetes prevalence + WHO premature-NCD and NCD mortality) plus the infectious metrics that are openly current — COVID deaths/100k (WHO), HIV prevalence and measles incidence (WHO GHO) — rather than per-cause cancer/stroke cases. Measles/smallpox/ebola/STDs were requested but most lack a clean current country-level open series, so the map carries only the ones with redistributable data and the note says so.

Build — FFL workflows on the runtime

This is a standard Facetwork domain package (facetwork.domains entry point, DomainPackage), so the maps are first-class FFL workflows discovered + seeded by the runner. Each fetches → joins geometry → renders a MapLibre choropleth (shared health/choropleth.py) → writes HTML to the configured backend (MinIO on the fleet, cache/health/maps/<name>/):

fw ffl run --workflow health.workflows.USMortalityMap   --task-list health
fw ffl run --workflow health.workflows.USPrevalenceMap  --task-list health
fw ffl run --workflow health.workflows.WorldNCDMap      --task-list health

FFL at a glance

A step is name = Facet(args); steps that reference each other are ordered, steps that don't run in parallel — so one workflow can render a whole map family at once:

namespace my.health {

    use health.maps

    /** The NHSN respiratory family — five maps, rendered concurrently. */
    workflow RespiratoryFamily() => (built: Int, first: String) andThen {

        resp = health.maps.BuildUSRespiratoryMap()
        strain = health.maps.BuildUSHospitalStrainMap()
        icu = health.maps.BuildUSICUSeverityMap()
        ped = health.maps.BuildUSPedVsAdultMap()
        tri = health.maps.BuildUSTripledemicMap()

        yield RespiratoryFamily(built = 5, first = resp.html_path)
    }
}

fw ffl run --primary my.ffl --library src/health/ffl/health.ffl \
  --workflow my.health.RespiratoryFamily --task-list health

📖 docs/ffl-examples.md — the full example gallery: implied parallelism, catch so one dead CDC endpoint doesn't sink the family, call-time mixins (timeout/retry), when join checks, and publishing several maps in one commit. Every snippet there is compile-checked.

There are 12 map workflows in all — the three above plus WorldHIVMap, EuropeHIVTransmissionMap, USHIVTransmissionMap, USAutismMap, and the NHSN respiratory family (USRespiratoryMap, USHospitalStrainMap, USICUSeverityMap, USPedVsAdultMap, USTripledemicMap) — each backed by one health.maps.Build*Map facet (12 registered facets). The rendered HTML is published to the health/ section of facetwork-maps (each carries its source attribution + a link back).

Install like any domain: pip install -e . (or fw install domain health); the runner auto-discovers it via the entry point.