APSDMA Heat Early Warning System v2 — Architecture & Operations

Mandal-resolved · 5-tier · NDMA + WMO-WHO aligned · Built 19-22 May 2026 in ≤ 3 days

1 · Executive summary

Heat EWS v2 is the new operational heat-warning pipeline replacing the v1 patchwork. It produces a daily 5-day forecast for all 688 AP mandals with five scientific indices, IMD HW/SHW classification, MOS-bias-corrected GFS forecasts, ensemble agreement across 6 forecast sources, vulnerability-weighted impact scores, and a 5-tier alert (GREEN/YELLOW/ORANGE/RED/MAROON) — published as both an Excel workbook and a live interactive portal at /heatwave-v2/.

What it answers: for every mandal in AP, every day of the next 5 days, what is the tier (severity), the underlying physical drivers, and the priority for ASHA/health/labour response — with built-in validation against ground truth.

2 · Five-layer architecture

End-to-end pipeline: each layer is one Python module under heat_ews/, with a single YAML config holding all thresholds, tier rules, and output paths.

3 · Modules — what each file does

File	Responsibility	Key external surface
`config.yaml`	Single source of truth — thresholds, paths, tier rules, action plans	—
`heat_ews/climatology.py`	Wraps existing `heatwave.*` tables: thresholds, normals, HVI	`get_thresholds_for_date(date)`, `get_multi_param_normals_for_date(date)`
`heat_ews/indices.py`	9 scientific indices (HI Rothfusz, AT Steadman, UTCI, WBGT, HWMID Russo, EHF Nairn, Tmin anomaly, IMD HW class)	`compute_all_indices(...)`
`heat_ews/tiering.py`	YAML-driven 5-tier rule engine	`classify(record)`, `enrich_record(record, thresholds)`
`heat_ews/mos.py`	Per-district per-lead linear MOS; writes `weather.mos_coefficients_district`	`train()`, `apply_correction(district, lead, raw)`
`heat_ews/ensemble.py`	6-model forecast ensemble, weighted mean + spread + HW/SHW probability	`get_ensemble_for_date`, `get_ensemble_agreement`
`heat_ews/impact.py`	Impact score combining tier × HVI × duration	`impact_score(tier, hvi, dur)`, `compute_dataframe(df)`
`heat_ews/dispatch.py`	Press PNG + email + Telegram (gated by `--send` flag)	`make_press_png`, `send_email`, `send_telegram`
`heat_ews_daily.py`	Single-command orchestrator — runs all of the above	CLI: `python heat_ews_daily.py [RUN_ID] [--send] [--retrain-mos]`
`export_portal_geojson.py`	Joins CSV with mandal polygons → publishes GeoJSON to `/heatwave-v2/data/`	CLI: `python export_portal_geojson.py RUN_ID`
`verify_daily.py`	Nightly forecast-vs-observation skill report	Writes `/heatwave-v2/skill.html`

4 · Scientific indices — formulas & references

Index	Definition	Reference	Where used
Heat Index	NWS Rothfusz polynomial (full + adjusted)	Rothfusz 1990	Modifier in tiering when ≥ 41 °C
Apparent Temperature	Ta + 0.33·e − 0.70·V − 4.0	Steadman 1984	Press bulletin context
UTCI (approx)	Ta + 0.33·(e − 6.105) − 0.70·V − 4	Brode et al. 2012 (shaded)	Reference column (true UTCI in Phase 2)
WBGT (no sun)	0.7·Twb + 0.3·Ta; Twb via Stull 2011	ACGIH	Occupational heat-stress reference
HWMID	(Tmax − T25) / (T75 − T25) for daily Tmax over T_threshold	Russo et al. 2014	Magnitude column
EHF (Excess Heat Factor)	EHI_sig × max(1, EHI_accl)	Nairn & Fawcett 2013	Severity column
Tmin anomaly	Tmin − Tmin_normal; warm night ≥ +4.5, very warm ≥ +6.5	IMD convention	Tier modifier (warm-night escalation)
IMD HW / SHW class	Plains: Tmax ≥ 40 °C & dep ≥ 4.5 (HW) / 6.4 (SHW); zone-adjusted for coastal/hills	IMD HAP	Primary tier driver

5 · 5-tier rules — exact thresholds

Rules are evaluated in order MAROON → RED → ORANGE → YELLOW → GREEN (highest matching wins). Each tier has any-of rule blocks; all conditions inside a block must match.

Tier	Color	Triggering rules (any-of)
MAROON Extreme emergency	●	`imd_hw_class == "extreme"` (Tmax ≥ 47 °C) `imd_hw_class == "shw"` AND `duration_days ≥ 3` `imd_hw_class == "shw"` AND `tmin_class == "very_warm_night"`
RED Severe heat wave	●	`imd_hw_class == "shw"` (single-day, Tmax ≥ normal + 6.4 °C) `imd_hw_class == "hw"` AND `duration_days ≥ 3` `imd_hw_class == "hw"` AND `tmin_class == "very_warm_night"`
ORANGE Heat wave	●	`imd_hw_class == "hw"` (Tmax ≥ normal + 4.5 °C) `tmax_p95_exceed` AND `tmin_class == "warm_night"`
YELLOW Hot day caution	●	`tmax_p90_exceed` (above mandal 90th-percentile, but not IMD HW) `heat_index ≥ 41 °C`
GREEN Normal	●	fallback when none of the above match

All rules and thresholds live in config.yaml. Edit that file (not code) to retune.

6 · Impact-based scoring

impact = tier_severity × (0.5 + 0.5 × HVI/100) × (1 + 0.15 × max(0, duration−1))

tier_severity: GREEN=0, YELLOW=20, ORANGE=45, RED=70, MAROON=95. Bounded to [0, 100]. The half-weighted HVI ensures a high-vulnerability mandal with moderate temperature can still rank above a low-vulnerability mandal with extreme temperature — matching WMO-WHO 2024 impact-based forecasting guidance.

7 · Data sources consumed

Source	Table / path	Volume
IMD GFS Mandal Forecast (today's run)	`C:\…\IMD_Daily_Output\YYYYMMDD\*.xlsx`	3,440 mandal-days × 5 days
IMD 1991–2020 mandal normals	`heatwave.imd_mandal_normals`	251,808 rows
Multi-param normals (RH, WBGT, HI, AT)	`heatwave.multi_param_normals`	251,808 rows × 32 cols
Daily Tmax thresholds (p90, p95, HW, SHW)	`heatwave.mandal_daily_thresholds`	83,936 rows
Mandal HVI (688 mandals, 31 cols)	`heatwave.mandal_hvi`	688 rows
Multi-model forecasts (6 sources)	`sde.forecast_daily`	~95,880 active rows
DES + IMD AWS observed daily	`sde.observed_daily`	~3,100 paired district-days
MOS coefficients	`weather.mos_coefficients_district`	196 (district × lead) pairs

8 · Operations

8.1 Scheduled tasks

Task	Schedule (IST)	What it does
`APSDMA_IMD_GFS_Pipeline` (existing)	10:00–15:00 / every 30 min	Pulls GRIB, generates IMD GFS bulletin Excel
`APSDMA_HeatEWS_Daily`	10:35 daily	Runs `heat_ews_daily.py` + portal export
`APSDMA_HeatEWS_Verify`	23:30 daily	Updates `/heatwave-v2/skill.html`
`APSDMA_HeatEWS_MOS_Train`	03:00 Sundays	Refreshes MOS coefficients on rolling 60-day window

8.2 Manual operations

# Default — files only, no external dispatch:
python E:\Heat_EWS_v2\heat_ews_daily.py

# Force-regenerate for a past run:
python E:\Heat_EWS_v2\heat_ews_daily.py 2026051900

# Re-train MOS first:
python E:\Heat_EWS_v2\heat_ews_daily.py --retrain-mos

# External email + Telegram (ONLY after operator approval):
python E:\Heat_EWS_v2\heat_ews_daily.py --send

# Skill report:
python E:\Heat_EWS_v2\verify_daily.py

8.3 Outputs per run

E:\Heat_EWS_v2\output\Heat_EWS_v2_RUNID.xlsx — full mandal-day workbook (33 columns)
…\Heat_EWS_v2_RUNID.csv — same as Excel for analytics
…\Heat_EWS_v2_RUNID_press.png — bilingual press map (D+1 tier choropleth)
…\Heat_EWS_v2_RUNID_topmandals.png — top-30 impact bar chart
C:\inetpub\wwwroot\heatwave-v2\data\mandals_heatews_v2.geojson — portal data (14 MB)
…\heatwave-v2\data\meta.json — portal metadata
…\heatwave-v2\skill.html — nightly skill report (overwritten)

8.4 Portal

Live at https://apsdmagis.ap.gov.in/heatwave-v2/ — Leaflet interactive map, tier filter, day selector, click-any-mandal popup with all indices, top-20 highest-impact ranking sidebar, downloadable CSV.

9 · Day-2 reference performance

Metric	Value
Wall-clock end-to-end	32 s
Mandal-day rows classified	3,440
MOS pairs trained	196 (district × lead)
MOS RMSE improvement (avg)	−1.1 °C
Ensemble sources joined	6 of 6 active
Tier distribution (run 2026051900)	MAROON 5.8% · RED 14.5% · ORANGE 22.7% · YELLOW 55.6% · GREEN 1.2%

10 · Roadmap (post-Day-3)

Phase	Item	Effort
Phase A	WRF 3 km NetCDF integration (IMD upstream — 8.9 GB/day)	2 wks
Phase B	Full Brode 2012 UTCI with solar radiation forecast	1 wk
Phase C	SMS/IVRS dissemination via VAANI or APSFL gateway	4 wks (procurement-gated)
Phase D	Mobile app (Flutter, read-only public tier viewer)	4 wks
Phase E	Health-dept mortality coupling — heat-stroke admissions pilot	6 wks (partnership-gated)
Phase F	Citizen-sensor / IoT ingestion (handheld AWS, school weather stations)	4 wks

11 · References

WMO-WHO (2015, rev 2024). Heatwaves and Health: Guidance on Warning System Development. WHO/WMO.
Russo S. et al. (2014). Magnitude of extreme heat waves in present climate and their projection in a warming world. J. Geophys. Res. Atmos. 119.
Nairn J.R. & Fawcett R.J.B. (2013). Defining heatwaves: heatwave defined as a heat-impact event servicing all community and business sectors. CAWCR TR 060, BoM Australia.
Rothfusz L.P. (1990). The Heat Index "Equation." NWS SR Tech Attachment 90-23.
Steadman R.G. (1984). A universal scale of apparent temperature. J. Climate Appl. Meteor. 23.
Brode P. et al. (2012). Deriving the operational procedure for the Universal Thermal Climate Index (UTCI). Int. J. Biometeorol. 56.
NDMA India (2024). National Action Plan for Heat-Related Illnesses.
IMD (2024). Heat Action Plan — operational handbook.
Mukhopadhyay P. et al. (2019). Performance of operational global ensemble forecast system over Indian region during pre-monsoon. Atmosphere 10.

Generated 2026-05-22 · APSDMA RS & GIS Lab · Heat EWS v2 design + ops handbook.