Zone-specific trigger thresholds behind THRESHOLD_MODE env var

Under THRESHOLD_MODE=zone_specific, each zone gets its own (alert_c,
payout_c) calibrated to the P90/P97 of that zone's 20-year ERA5-Land ×
UHI-corrected WBGT distribution. This matches the actuarial pattern
used by ARC, CCRIF, and SEWA heat pilot, and fixes the "Jangwani $0
premium" problem that surfaced under UHI_MODEL=lst with the global
35.1°C threshold — zones get equitable ~10% alert / ~3% payout trigger
frequency regardless of absolute temperature distribution.

Under UHI_MODEL=lst + THRESHOLD_MODE=zone_specific:
Jangwani: alert 31.79°C / payout 32.54°C (vs global 35.1/36.0 it
never reached, producing $0 premium)
Tandale: alert 36.10°C / payout 36.93°C (hotter than global, LST
confirmed this zone really is a heat hotspot)
Vingunguti: alert 36.73°C / payout 37.55°C (hottest zone)

Default remains THRESHOLD_MODE=global so production behavior is
unchanged until the HF Space secret is set.

- src/pricing/zone_thresholds.py: new module. Computes per-zone
P90/P97 from ERA5-Land × active UHI model, caches to
data/zone_thresholds.json on first call (gitignored; regenerates if
UHI_MODEL changes or cache is deleted).
- src/pricing/burn_analysis.py::burn_for_zone(): passes zone-specific
threshold into compute_burn() so actuarial pricing reflects zone
return periods.
- src/pipeline.py: trigger call site and observed-WBGT fallback both
now use get_zone_thresholds(zone). Drops the last reference to the
global WBGT_THRESHOLD_C constant in the per-zone loop.

Caveat worth flagging in the preprint: zone-specific thresholds make
coverage relative to local climatology, not absolute WBGT health risk
(ISO 7243). Product narrative needs to align with that choice —
workers in Jangwani are protected against "unusual heat for Jangwani,"
which is not the same as "WBGT ≥ 28°C absolute health threshold."

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.gitignore

@@ -14,3 +14,4 @@ dist/
 data/nasa_power_cache/
 data/era5_cache/
 data/era5land_cache/
+data/zone_thresholds.json

CLAUDE.md

@@ -110,6 +110,17 @@ Data under `data/landsat_lst/`:
 - `zone_features.json` — per-zone climatology features + hot-season anomaly
 - `city_climatology.json` — city-mean LST across covered zones
 
+## Trigger threshold mode
+
+`THRESHOLD_MODE` env var picks between global (Dar-wide) and zone-specific trigger thresholds.
+
+- `THRESHOLD_MODE=global` (default, current production) — every zone uses the same 35.1°C alert / 36.0°C payout thresholds. Trigger frequency varies wildly across zones because UHI delta shifts the effective threshold per zone (under LST UHI, Jangwani's effective threshold is unreachable → $0 premium).
+- `THRESHOLD_MODE=zone_specific` — each zone gets its own (alert_c, payout_c) calibrated to P90/P97 of that zone's own 20-year ERA5-Land × UHI-corrected WBGT distribution. Trigger frequency normalizes to ~10% alert / ~3% payout per year across all zones. Standard parametric-insurance actuarial pattern (ARC, CCRIF, SEWA).
+
+Thresholds are computed at first pipeline invocation and cached to `data/zone_thresholds.json`. Delete the cache to force recompute after any UHI model change or panel rebuild. The cache depends on the active `UHI_MODEL` — changing the UHI model invalidates the threshold cache.
+
+To flip production fully data-anchored: set both `UHI_MODEL=lst` and `THRESHOLD_MODE=zone_specific` as HF Space secrets.
+
 ## Things to know
 
 - **HF Space runs on A100 GPU** — needed for GraphCast inference (~5-8s per forecast). Space wakes, runs pipeline, pauses. Cost: ~$0.50/week.

src/pipeline.py

@@ -638,24 +638,30 @@ class HeatRiskPipeline:
 
                 if gc_wbgt is not None:
                     zone_wbgt = [w + mean_uhi for w in gc_wbgt]
+                    # Zone-specific trigger thresholds (P90/P97 of each zone's
+                    # own corrected WBGT climatology under THRESHOLD_MODE=
+                    # zone_specific; otherwise fall back to the global
+                    # 35.1°C / 36.0°C values).
+                    from src.pricing.zone_thresholds import get_zone_thresholds
+                    zone_alert_c, zone_payout_c = get_zone_thresholds(zone)
                     action = forecast_trigger_decision(
                         zone_wbgt,
                         alert_duration_days=ALERT_CONSECUTIVE_DAYS,
                         payout_duration_days=PAYOUT_CONSECUTIVE_DAYS,
-                        window_threshold_c=WBGT_THRESHOLD_C,
-                        payout_severity_c=30.7,
+                        window_threshold_c=zone_alert_c,
+                        payout_severity_c=zone_payout_c,
                     )
                     max_wbgt = max(zone_wbgt) if zone_wbgt else 0
                     # Max consecutive-run length above threshold in the forecast
                     consec = 0
                     run_length = 0
                     for w in zone_wbgt:
-                        if w > WBGT_THRESHOLD_C:
+                        if w > zone_alert_c:
                             run_length += 1
                             consec = max(consec, run_length)
                         else:
                             run_length = 0
-                    total_above = sum(1 for w in zone_wbgt if w > WBGT_THRESHOLD_C)
+                    total_above = sum(1 for w in zone_wbgt if w > zone_alert_c)
 
                     if action == "alert_cash":
                         all_triggers.append(_make_trigger(
@@ -669,14 +675,16 @@ class HeatRiskPipeline:
                     # Fallback: use recent observed WBGT
                     recent_wbgt = wbgts[-7:] if len(wbgts) >= 7 else wbgts
                     if recent_wbgt:
+                        from src.pricing.zone_thresholds import get_zone_thresholds
+                        zone_alert_c, _ = get_zone_thresholds(zone)
                         max_wbgt = max(recent_wbgt)
                         consec = 0
                         for w in reversed(recent_wbgt):
-                            if w > WBGT_THRESHOLD_C:
+                            if w > zone_alert_c:
                                 consec += 1
                             else:
                                 break
-                        total_above = sum(1 for w in recent_wbgt if w > WBGT_THRESHOLD_C)
+                        total_above = sum(1 for w in recent_wbgt if w > zone_alert_c)
 
                         if consec >= PAYOUT_CONSECUTIVE_DAYS:
                             all_triggers.append(_make_trigger(

src/pricing/burn_analysis.py

@@ -200,7 +200,12 @@ class BurnAnalysisPricer:
         uhi_lo, uhi_hi = get_zone_uhi_range(zone)
         mean_uhi = (uhi_lo + uhi_hi) / 2.0
 
-        result = compute_burn(records, mean_uhi)
+        # Zone-specific trigger threshold (THRESHOLD_MODE env var selects
+        # global=35.1°C vs zone_specific=per-zone P90 from local climatology).
+        from src.pricing.zone_thresholds import get_zone_thresholds
+        alert_c, _payout_peak_c = get_zone_thresholds(zone)
+
+        result = compute_burn(records, mean_uhi, threshold_c=alert_c)
         result.zone_id = zone.zone_id
         result.basis_risk_score = _basis_risk_for_zone(zone, mean_uhi)
 

src/pricing/zone_thresholds.py

@@ -0,0 +1,148 @@
+"""Zone-specific trigger threshold calibration.
+
+Computes (alert_wbgt_c, payout_peak_wbgt_c) per zone from each zone's own
+20-year ERA5-Land WBGT distribution, with UHI delta applied. Replaces the
+global 35.1°C / 36.0°C thresholds used in Phase 1 with zone-relative
+thresholds calibrated to the same percentiles (P90 alert, P97 payout) —
+the actuarial pattern used by ARC, CCRIF, SEWA heat pilot.
+
+Activated by THRESHOLD_MODE env var:
+  THRESHOLD_MODE=global         (default)  use WBGT_THRESHOLD_C / PAYOUT_PEAK
+  THRESHOLD_MODE=zone_specific  per-zone P90/P97 calibrated from local history
+
+Cached to data/zone_thresholds.json for reuse; safe to delete to force
+recompute after any UHI model change.
+"""
+from __future__ import annotations
+
+import json
+import math
+import os
+from pathlib import Path
+from typing import Tuple
+
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+ERA5_PATH = _REPO_ROOT / "data" / "era5land_dar_es_salaam.json"
+CACHE_PATH = _REPO_ROOT / "data" / "zone_thresholds.json"
+
+ALERT_PERCENTILE = 0.90   # P90 for alert-tier trigger (matches grid-cell
+                          # 35.1°C historical origin on raw ERA5-Land)
+PAYOUT_PERCENTILE = 0.97  # P97 for payout-tier peak severity
+
+
+def _calculate_wbgt(temp_c: float, humidity_pct: float) -> float:
+    """Liljegren simplified outdoor — matches CRE src.indexing.heat_index."""
+    es = 6.112 * math.exp((17.67 * temp_c) / (temp_c + 243.5))
+    e = es * (humidity_pct / 100.0)
+    return 0.567 * temp_c + 0.393 * e + 3.94
+
+
+def _percentile(values: list[float], p: float) -> float:
+    if not values:
+        return 0.0
+    s = sorted(values)
+    idx = p * (len(s) - 1)
+    lo, hi = int(math.floor(idx)), int(math.ceil(idx))
+    if lo == hi:
+        return s[lo]
+    return s[lo] + (s[hi] - s[lo]) * (idx - lo)
+
+
+def _threshold_mode() -> str:
+    return os.environ.get("THRESHOLD_MODE", "global").lower()
+
+
+def compute_zone_thresholds(use_cache: bool = True) -> dict[str, dict[str, float]]:
+    """Return {zone_id: {alert_c, payout_c, n_days, mean_wbgt_c}} for Dar zones.
+
+    Iterates each Dar zone, applies its UHI delta (from the active UHI model)
+    to the 20-year ERA5-Land DAR-JAN grid-cell series, computes per-day WBGT,
+    and extracts percentiles.
+
+    Cached to ``CACHE_PATH`` to avoid re-computing on every pipeline run.
+    """
+    if use_cache and CACHE_PATH.exists():
+        return json.loads(CACHE_PATH.read_text())
+
+    from config import ZONES
+    from src.downscaling import get_uhi_corrector
+    from datetime import datetime
+
+    era5 = json.loads(ERA5_PATH.read_text())
+    grid_rows = era5["DAR-JAN"]  # all 15 Dar zones resolve to this grid cell
+    corrector = get_uhi_corrector()
+
+    out: dict[str, dict[str, float]] = {}
+    for z in ZONES:
+        if z.city != "Dar es Salaam":
+            continue
+        wbgts = []
+        for r in grid_rows:
+            t = r.get("temp_max_c")
+            h = r.get("humidity_pct")
+            if t is None or h is None:
+                continue
+            month = int(r["date"][5:7])
+            # Apply UHI correction at this zone for this month (mid-day)
+            corrected_t, _, _ = corrector.correct_temperature(z, float(t), hour=14, month=month)
+            wbgts.append(_calculate_wbgt(corrected_t, float(h)))
+        if not wbgts:
+            continue
+        out[z.zone_id] = {
+            "alert_c": round(_percentile(wbgts, ALERT_PERCENTILE), 2),
+            "payout_c": round(_percentile(wbgts, PAYOUT_PERCENTILE), 2),
+            "n_days": len(wbgts),
+            "mean_wbgt_c": round(sum(wbgts) / len(wbgts), 2),
+            "uhi_model": os.environ.get("UHI_MODEL", "synthetic").lower(),
+        }
+    CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    CACHE_PATH.write_text(json.dumps(out, indent=2))
+    return out
+
+
+# Global-mode fallback constants (imported by callers for back-compat)
+GLOBAL_ALERT_C = 35.1
+GLOBAL_PAYOUT_PEAK_C = 36.0
+
+
+def get_zone_thresholds(zone) -> Tuple[float, float]:
+    """Return (alert_c, payout_peak_c) for a zone.
+
+    THRESHOLD_MODE=zone_specific: zone's own P90/P97 from historical series.
+    THRESHOLD_MODE=global (default): (35.1, 36.0) regardless of zone.
+
+    Zones without pre-computed thresholds (non-Dar zones, or first-ever run
+    before cache exists) fall back to global.
+    """
+    if _threshold_mode() != "zone_specific":
+        return GLOBAL_ALERT_C, GLOBAL_PAYOUT_PEAK_C
+    try:
+        thresholds = compute_zone_thresholds(use_cache=True)
+    except Exception:
+        return GLOBAL_ALERT_C, GLOBAL_PAYOUT_PEAK_C
+    zt = thresholds.get(zone.zone_id)
+    if zt is None:
+        return GLOBAL_ALERT_C, GLOBAL_PAYOUT_PEAK_C
+    return float(zt["alert_c"]), float(zt["payout_c"])
+
+
+def current_mode() -> str:
+    return _threshold_mode()
+
+
+if __name__ == "__main__":
+    import sys
+    sys.path.insert(0, str(_REPO_ROOT))
+    # Force recompute
+    if CACHE_PATH.exists():
+        CACHE_PATH.unlink()
+    import os as _os
+    _os.environ.setdefault("UHI_MODEL", "lst")
+    print(f"Computing zone thresholds under UHI_MODEL={_os.environ['UHI_MODEL']}...")
+    t = compute_zone_thresholds(use_cache=False)
+    print(f"\n{'zone':9s} {'alert':>7s} {'payout':>7s} {'mean':>7s} {'n':>6s}")
+    for zid, v in sorted(t.items()):
+        print(f"{zid:9s} {v['alert_c']:>7.2f} {v['payout_c']:>7.2f} "
+              f"{v['mean_wbgt_c']:>7.2f} {v['n_days']:>6d}")
+    print(f"\nGlobal reference (THRESHOLD_MODE=global): alert={GLOBAL_ALERT_C} payout={GLOBAL_PAYOUT_PEAK_C}")
+    print(f"\nCached at: {CACHE_PATH}")