rakumar25/Disaster-Health-Needs-Estimator

Model Card: Disaster Health Needs Estimator (DHNE)

Model summary

DHNE estimates community-level health-supply needs after a disaster (diapers, menstrual products, insulin, inhalers, dialysis sessions, water, calories, and a power-dependent-care priority flag), with low/base/high uncertainty bands. It is a hybrid: a machine-learning population impact model feeds a transparent, evidence-based needs translation engine.

• Developed by: Ravindra Kumar
• Model type: Gradient-boosted trees (impact) + rule/rate engine (needs)
• Language(s): N/A (tabular)
• License: Apache-2.0
• Serialization: skops (artifacts/impact_model.skops) — deliberately not joblib/pickle. Loading a pickle file executes arbitrary code, which Hugging Face flags as unsafe for public model repos; skops is pickle-free.
• Intended use: Emergency planning decision support for agencies and NGOs, with emphasis on rural and socially vulnerable communities.

Intended use & users

• Intended: pre-positioning and resupply planning; scenario analysis; identifying power-dependent residents needing priority evacuation.
• Users: emergency managers, public-health departments, humanitarian NGOs.
• Out of scope: individual diagnosis, treatment, triage, or any clinical decision about a specific person. Not a medical device.

Inputs / outputs

• Input: hazard type (FEMA's real incidentType, e.g. Hurricane/Flood/ Severe Storm/Tornado/Fire), duration, season; county demographics (population, poverty, age structure, median home age), Social Vulnerability Index, rurality.
• Output: predicted affected population and a needs manifest with low/base/high quantities per item, plus a power-dependent priority count.

Training data

• Labels: OpenFEMA Individual Assistance registrant counts per (disaster, county) — aggregated from record-level microdata (IndividualAssistanceHousingRegistrantsLargeDisasters), county FIPS derived from each registrant's censusBlockId. A proxy for impact (registration undercounts affected people; an explicit uptake factor in src/pipeline.run corrects for this — currently a documented assumption, not a fitted constant). This dataset only covers disasters large enough to clear FEMA's size/privacy threshold, so the training set is inherently biased toward larger, more damaging events.
• Features: US Census/ACS 5-yr (population, poverty, age structure, median home year — requires a free Census API key), USDA RUCC (rurality), CDC/ATSDR SVI (social vulnerability). All public, all joined on 5-digit county FIPS. See src/data_sources.py and scripts/build_training_table.py.
• No patient-level or identifiable data is used.
• Built via scripts/build_training_table.py --min-year 2005 --max-year 2026 --max-disasters 8. Finding from building this: the IA registrant microdata ("LargeDisasters") dataset is far smaller than its name suggests — across ALL declared disasters from 2005–2026, only 8 disasters total have any rows in it at all (probed every one; verified this isn't a bug — see src/data_sources.probe_ia_registrant_totals's docstring). All 8 are major hurricanes plus the February 2021 Texas severe ice storm/freeze. The current shipped model is trained on 7 of those 8 (one, Hurricane Irma's Puerto Rico declaration, has no matching ACS/RUCC/SVI county features in this pass — PR isn't in this build's Census state-FIPS list) → 311 (disaster, county) rows spanning 2017, 2018, 2020, 2021, 273 distinct counties, hazard types Hurricane (182 rows) and Severe Ice Storm (129 rows).
• This is a small, hazard-narrow, hurricane/ice-storm-heavy training set — not remotely a representative sample of "all disasters." Rerun scripts/build_training_table.py with a wider --min-year/--max-year if FEMA adds more disasters to the underlying dataset over time (results are cached in data/raw/, so reruns are cheap); Puerto Rico/territory coverage would need src/data_sources.US_STATE_FIPS extended and ACS variables re-verified for territory geographies.

Evaluation

• Out-of-time split: trained on disasters declared before a cutoff year, evaluated on disasters declared at/after it (src/model.fit's year_col/ cutoff_year; the shipped run used the default 80th-percentile-year cutoff, which came out to 2021 — train on 2017/2018/2020 (157 rows), test on 2021 (154 rows, entirely Hurricane Ida + the TX ice storm)). Current numbers (artifacts/metrics.json):
  • Out-of-time: MAE(log1p)=1.73, R²=-0.25 — worse than predicting the mean. For comparison, a random 80/20 split on the same 311 rows gets MAE(log1p)=0.65, R²=0.74. That gap is the honest headline result: the model fits these 7 disasters' patterns well in-sample, but the out-of-time test asks it to generalize to a genuinely different disaster (Ida vs. mostly-Harvey/Irma/Florence in training, plus an ice storm — a fundamentally different hazard mechanism than every hurricane in training) from a training set of only 6 other disasters. That is not enough distinct events for a tree ensemble to learn generalizable disaster-to-impact relationships yet. Treat this model's predictions as illustrative of the pipeline working end-to-end on real data, not as calibrated forecasts — the needs engine's transparent rate-based reasoning (not the ML impact prediction) is where this project's reliability currently comes from. Expanding to more disasters (as FEMA's dataset grows, or by adding earlier eras once verified) is the clear next step before trusting the impact model's outputs.
• Needs engine validated by sensitivity analysis and expert review of rates — not yet done; tracked as future work in README.md.

Limitations & biases

• Inherits census/prevalence data lag and FEMA-registration undercount and its socioeconomic biases; outputs are ranges, not guarantees.
• Consumption/prevalence rates are documented assumptions in config/needs_rates.yaml — audit and localize them.
• The uptake_factor (registrants → truly-affected people) is an explicit, visible assumption (default 2.0), not fitted against real affected- population data. Calibrate against independent estimates (Red Cross shelter counts, state after-action reports) before treating outputs as more than directional.
• CDC PLACES' current release has no CKD/kidney-disease measure, so dialysis/ CKD prevalence stays a literature-rate default in CountyRatios rather than a per-county figure.
• HHS emPOWER (electricity-dependent beneficiaries) is not yet wired up; empower_beneficiaries is a per-capita default, not a real county figure.
• USDA's 9-point RUCC scale is collapsed to a 3-bucket rurality (metro/ micropolitan/rural) to match this project's needs multipliers — a documented simplification, not an official USDA mapping.
• Only 7 disasters, 311 rows, in the current training set (see Training data above) — the impact model's out-of-time R² is negative, meaning it currently does not reliably generalize to a disaster unlike the ones it was trained on. This is the single biggest thing to fix before trusting the ML impact prediction; it is not a representative sample of disasters in general (hurricane- and one ice-storm-heavy).
• Not validated for use outside the United States, and Puerto Rico/territory counties are not yet covered (see Training data above).

Ethical considerations

Population-level planning aid only. Misuse as individual clinical guidance is explicitly out of scope. Designed to reduce inequity by surfacing needs in underserved areas, but should be paired with local knowledge and on-the-ground assessment.

How to use

import skops.io as sio
from src.pipeline import run, CountyRatios

path = "artifacts/impact_model.skops"
est = sio.load(path, trusted=sio.get_untrusted_types(file=path))
event = {
    "county_population": 42000, "poverty_rate": 0.22, "pct_65plus": 0.21,
    "pct_under5": 0.06, "median_home_year": 1978, "svi_score": 0.78,
    "rucc_code": "rural", "hazard_type": "Flood",
    "season": "summer", "duration_days": 9,
}
print(run(est, event, CountyRatios(rurality="rural", svi_quartile="q4_high"), horizon_days=7))

Citation

@software{kumar_dhne_2026,
  author  = {Kumar, Ravindra},
  title   = {Disaster Health Needs Estimator (DHNE)},
  year    = {2026},
  url     = {https://huggingface.co/<your-username>/dhne-impact-model}
}