Update backtest_indonesia.py

backtest_indonesia.py

@@ -3,17 +3,6 @@ backtest_indonesia.py
 =====================
 Historical replay / evaluation harness for the Indonesia weather-risk stack.
 
-WHAT THIS IS FOR
-----------------
-The Optuna sweep (train_kaggle.py) evaluates the RL AGENT's hyperparameters.
-This harness answers a different, more operational question: "fed real
-historical weather for Indonesian zones, does the deterministic scoring
-stack (climatology anomalies -> ZoneObs signals -> crop_risk_scorer alert
-levels) actually fire on the days when the climate says something bad was
-happening -- and with how much lead time?" It is the missing link between
-"the modules pass unit tests" and "the system demonstrably works as a
-weather modelling / prediction / planning tool for Indonesia".
-
 PIPELINE PER REPLAY STEP (per zone, per date)
 ---------------------------------------------
   1. obs: live mode -> era5_data_pipeline.fetch_zone_obs (Open-Meteo archive
@@ -24,37 +13,10 @@ PIPELINE PER REPLAY STEP (per zone, per date)
      event blocks (offline, CI-friendly).
   2. anomalies: climatology.apply_climatology_anomalies with a PINNED
      climatology whose period ends BEFORE the replay window starts
-     (end_year = replay_start.year - 1). This is the no-look-ahead
-     guarantee; fetching anomalies through cfg.use_climatology_anomalies
-     would instead use the most-recent years and leak the replayed period.
+     (end_year = replay_start.year - 1).
   3. forecast: timesfm_wrapper 'baseline' backend (persistence /
      climatology-reverting, derived from the obs only -- no look-ahead).
-     A real NWP hindcast archive would be the strict upgrade; the baseline
-     keeps the replay honest and reproducible.
   4. score: crop_risk_scorer.compute_risk_score -> alert level per day.
-
-GROUND TRUTH
-------------
-Default (proxy): climatological percentiles from the SAME pinned climatology:
-  drought day: obs.precip_30d_mm < mean_30d - 0.84 * std_30d
-  flood day:   obs.precip_7d_mm  > mean_7d  + 1.28 * std_7d
-L1 (optional): --impact-labels PATH loads impact_labels JSON (e.g.
-  impact_labels_java_v1.json). When a zone-day has an L1 drought/flood
-  event, that overrides the proxy flags for that day only. Days without
-  L1 coverage keep the proxy. This is the documented production path
-  toward BNPB/provincial catalogues without inventing live APIs.
-
-PRODUCT EMIT (optional)
------------------------
---emit-product-alerts: after each compute_risk_score, call
-product_alert_service.emit_product_alert (idempotent, WARNING+ or
-hazard gate). Trusted backend path only; uses LocalTransport by default.
-
-SUGGESTED LIVE DEMO WINDOWS (historically documented events):
-  * 2023 El Nino + positive-IOD dry season, Java:
-      --zones karawang_rice,indramayu_rice --start 2023-07-01 --end 2023-11-30
-  * 2020-21 La Nina wet season (Jan 2021 Java floods):
-      --zones karawang_rice --start 2020-12-01 --end 2021-02-28
 """
 
 from __future__ import annotations
@@ -132,7 +94,6 @@ class DayRecord:
 
 @dataclass
 class BacktestMetrics:
-    """Day-level confusion + event-level detection/lead time."""
     n_days: int = 0
     tp: int = 0
     fp: int = 0
@@ -174,17 +135,6 @@ class BacktestMetrics:
 
 
 def compute_metrics(records: Sequence[DayRecord]) -> BacktestMetrics:
-    """Day-level confusion + event-run detection with lead time.
-
-    Day-level:  TP = alert on an event day, FP = alert on a non-event day,
-                FN = missed event day, TN = quiet day correctly quiet.
-    Run-level:  contiguous event days (merged across gaps <=
-                _RUN_MERGE_GAP_DAYS) form one event run. A run is DETECTED
-                if any alert fires inside the run or in the
-                _LEAD_WINDOW_DAYS before its first day. Lead time = days
-                from that first qualifying alert to the run start (0 for
-                alerts landing on day 1 of the run).
-    """
     m = BacktestMetrics(n_days=len(records))
     for r in records:
         if r.event and r.alert:
@@ -243,13 +193,6 @@ def compute_metrics(records: Sequence[DayRecord]) -> BacktestMetrics:
 
 
 def compute_product_l1_metrics(records: Sequence[Dict[str, Any]]) -> Dict[str, Any]:
-    """
-    Primary product metrics: EMITTED vs L1 event days (not ADVISORY vs proxy).
-
-    Uses record dicts (as written to result JSON). A day is:
-      product_positive = product_emit == 'EMITTED'
-      l1_event = gt_source == 'l1' and (event_drought or event_flood)
-    """
     n = len(records)
     tp = fp = fn = tn = 0
     n_l1 = 0
@@ -299,7 +242,6 @@ def compute_product_l1_metrics(records: Sequence[Dict[str, Any]]) -> Dict[str, A
 # ---------------------------------------------------------------------------
 
 def _classify_events(obs: ZoneObs, clim: ZoneClimatology) -> Tuple[bool, bool]:
-    """Proxy ground truth from the pinned climatology (see module docstring)."""
     event_drought = False
     event_flood = False
     if obs.precip_30d_mm > 0.0:
@@ -324,18 +266,6 @@ def replay_zone(
     emission_ledger: Any = None,
     transport: Any = None,
 ) -> List[DayRecord]:
-    """Replay one zone over [start, end] at `step_days` resolution.
-
-    mode='live':      obs via era5_data_pipeline (Open-Meteo archive for
-                      historical dates), forecast via baseline backend.
-    mode='synthetic': deterministic synthetic obs; `planted_events` maps
-                      'drought'/'flood' -> (start, end) blocks during which
-                      the synthetic generator's event flag is forced on.
-    impact_store:     optional ImpactLabelStore; L1 flags override proxy
-                      when present for that zone-day.
-    emit_product:     if True, call product_alert_service after each score
-                      (requires emission_ledger + transport).
-    """
     if start.tzinfo is None:
         start = start.replace(tzinfo=timezone.utc)
     if end.tzinfo is None:
@@ -378,9 +308,6 @@ def replay_zone(
                 seed=_zo._stable_seed(f"{zone_id}|{vt.date().isoformat()}"),
                 **flag,
             )
-            # The factory draws its own random valid_time from the seed;
-            # the replay clock is authoritative -- override via the
-            # codebase's to_dict/from_dict idiom (never mutate).
             _d = obs.to_dict()
             _d.pop("_schema_version", None)
             _d["valid_time"] = vt.isoformat()
@@ -397,7 +324,6 @@ def replay_zone(
         ev_drought, ev_flood = _classify_events(obs, clim)
         gt_source = "proxy"
 
-        # L1 override: when store has a label for this zone-day, use it.
         if impact_store is not None:
             try:
                 l1_d, l1_f = impact_store.labels_for_day(zone_id, vt.date())
@@ -427,7 +353,6 @@ def replay_zone(
                 except RuntimeError:
                     loop = None
                 if loop and loop.is_running():
-                    # Nested running loop (e.g. notebook): schedule carefully
                     import concurrent.futures
                     with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
                         product_emit = pool.submit(lambda: asyncio.run(_one())).result().outcome_code
@@ -467,7 +392,6 @@ def run_backtest(
     impact_labels_path: Optional[str] = None,
     emit_product_alerts: bool = False,
 ) -> Dict[str, Any]:
-    """Replay several zones; return per-zone + overall metrics and records."""
     if mode == "live":
         register_indonesia_zones()
 
@@ -737,4 +661,4 @@ if __name__ == "__main__":
     if len(sys.argv) > 1:
         sys.exit(_main())
     else:
-        sys.exit(_self_test())
+        sys.exit(_self_test())