Update indonesia_zones.py

indonesia_zones.py

@@ -3,46 +3,6 @@ indonesia_zones.py
 ==================
 Indonesia grounding layer: real agricultural zone registry, rice crop
 calendars, monsoon-onset context, and planting-window planning outputs.
-
-WHY THIS MODULE EXISTS
-----------------------
-The rest of the pipeline (era5_data_pipeline, crop_risk_scorer,
-weather_forecast_env, hierarchical_search) is fully generic -- it knows
-what a ZoneObs is but nothing about WHERE the zones are or WHAT is growing
-there. Concretely, before this module:
-
-  * No Indonesian zone was registered anywhere; register_zone() was only
-    ever called with ad-hoc polygons (tests, hierarchical_search nodes).
-  * Real fetchers never populated crop_stage / days_to_harvest, so
-    crop_risk_scorer._optimal_harvest_window never fired on real data and
-    _harvest_pressure always used the 0.3 default branch.
-  * "Planning" outputs did not exist: the system produced alert levels but
-    no actionable windows (when to plant, whether irrigation is needed).
-
-This module is deliberately self-contained: it depends only on
-zone_observation (+ crop_risk_scorer for the advisory's risk summary) so it
-can be imported by era5_data_pipeline callers, the backtester, or a service
-layer without pulling in the RL stack.
-
-DATA PROVENANCE (honest boundaries)
------------------------------------
-  * Zone geometries: rectangular approximations around well-known
-    agricultural-region centroids (+/-0.35 deg). They are NOT administrative
-    boundaries. For production alerting routed to real officials, replace
-    to_polygon() geometries with BPS/BIG (Badan Informasi Geospasial)
-    regency-level shapefiles.
-  * Crop calendars: heuristic two-season irrigated-rice calendar for Java /
-    Sumatra / Sulawesi lowlands and a single rainfed season for the
-    south-eastern islands (NTB/NTT), consistent with the broadly documented
-    wet (Oct-Apr) / dry (May-Sep) season structure. Real planting dates
-    vary by regency, variety (e.g. Ciherang vs Inpari), and irrigation
-    district (bendungan/waduk service area). Treat stages as
-    climatological-typical, not field-observed.
-  * Monsoon onset: climatological heuristic with ENSO/IOD sign adjustments
-    (El Nino / positive IOD delay onset over the southern archipelago;
-    La Nina / negative IOD advance it). BMKG publishes official onset
-    forecasts per ZOM (zona musim) each year -- wiring THAT product in is
-    the production upgrade; see monsoon_onset_estimate() docstring.
 """
 
 from __future__ import annotations
@@ -81,11 +41,6 @@ logger = logging.getLogger(__name__)
 
 @dataclass(frozen=True)
 class IndonesiaZone:
-    """One agricultural zone in the Indonesian registry.
-
-    half_extent_deg: the rectangle half-width in degrees (applied to both
-    lat and lon). 0.35 deg ~= 39 km -- roughly regency scale in Java.
-    """
     zone_id:        str
     label:          str
     province:       str
@@ -99,8 +54,6 @@ class IndonesiaZone:
     notes:          str = ""
 
     def to_polygon(self) -> GeoPolygon:
-        """Rectangular approximation. NOT an administrative boundary --
-        see module docstring for the BPS/BIG production upgrade path."""
         h = self.half_extent_deg
         return GeoPolygon(
             zone_id=self.zone_id,
@@ -187,8 +140,7 @@ INDONESIA_ZONES: Tuple[IndonesiaZone, ...] = (
 
 _ZONE_BY_ID: Dict[str, IndonesiaZone] = {z.zone_id: z for z in INDONESIA_ZONES}
 
-# Indonesia bounding box (matches hierarchical_search.py's self-test value).
-INDONESIA_BBOX = (-11.0, 6.0, 95.0, 141.0)  # (lat_min, lat_max, lon_min, lon_max)
+INDONESIA_BBOX = (-11.0, 6.0, 95.0, 141.0)
 
 
 def get_zone(zone_id: str) -> IndonesiaZone:
@@ -201,11 +153,6 @@ def get_zone(zone_id: str) -> IndonesiaZone:
 
 
 def register_indonesia_zones() -> List[str]:
-    """Register every INDONESIA_ZONES polygon with era5_data_pipeline's zone
-    registry (idempotent). Returns the registered zone_ids.
-
-    Local import so this module stays importable without the pipeline.
-    """
     from era5_data_pipeline import register_zone
     ids = []
     for z in INDONESIA_ZONES:
@@ -221,14 +168,6 @@ def register_indonesia_zones() -> List[str]:
 
 @dataclass(frozen=True)
 class RiceSeason:
-    """One cropping season, in day-of-year windows (1..366).
-
-    plant_*: the typical transplanting/direct-seeding window.
-    harvest_*: the typical harvest window. Growing duration between them is
-    derived, not stored. Windows may wrap around year end (wet-season rice
-    planted in November is harvested the following February) -- handled by
-    the _in_doy_window helper.
-    """
     name:         str
     plant_start:  int
     plant_end:    int
@@ -236,42 +175,31 @@ class RiceSeason:
     harvest_end:  int
 
 
-# Heuristic calendars (see module docstring for provenance and limits).
 CROP_CALENDARS: Dict[str, Tuple[RiceSeason, ...]] = {
-    # Java / Bali / Sulawesi lowland irrigated: wet + dry season rice.
     "java_double": (
         RiceSeason("wet_rice",  plant_start=305, plant_end=365,
                    harvest_start=46,  harvest_end=105),   # Nov -> Feb/Mar
         RiceSeason("dry_rice",  plant_start=105, plant_end=151,
                    harvest_start=213, harvest_end=258),   # Apr/May -> Aug/Sep
     ),
-    # Southern Sumatra: wet season slightly earlier, same double structure.
     "sumatra_double": (
         RiceSeason("wet_rice",  plant_start=290, plant_end=350,
                    harvest_start=31,  harvest_end=90),
         RiceSeason("dry_rice",  plant_start=100, plant_end=146,
                    harvest_start=205, harvest_end=250),
     ),
-    # Equatorial Sumatra / Kalimantan: wet season peaks Oct-Dec; less
-    # pronounced dry season -- second crop is partial (represented as a
-    # narrower, less reliable window).
     "sumatra_equatorial": (
         RiceSeason("main_rice", plant_start=274, plant_end=334,
                    harvest_start=15,  harvest_end=75),
         RiceSeason("second_rice", plant_start=90, plant_end=135,
                    harvest_start=195, harvest_end=240),
     ),
-    # NTT single rainfed crop (maize/upland rice): plant with the onset
-    # rains Dec-Jan, harvest Apr-May.
     "ntt_single": (
         RiceSeason("rainfed_main", plant_start=335, plant_end=31,
                    harvest_start=100, harvest_end=140),
     ),
 }
 
-# Phase fractions of the growing period (plant_end -> harvest_start):
-# vegetative first ~45%, reproductive next ~25%, grain filling next ~20%,
-# maturation the final ~10% before harvest opens.
 _PHASE_FRACTIONS: Tuple[Tuple[CropStage, float], ...] = (
     (CropStage.VEGETATIVE,    0.45),
     (CropStage.REPRODUCTIVE,  0.25),
@@ -281,15 +209,12 @@ _PHASE_FRACTIONS: Tuple[Tuple[CropStage, float], ...] = (
 
 
 def _in_doy_window(doy: int, start: int, end: int) -> bool:
-    """True if doy is inside [start, end], with wrap-around support
-    (e.g. start=335, end=31 covers Dec -> Jan)."""
     if start <= end:
         return start <= doy <= end
     return doy >= start or doy <= end
 
 
 def _doy_distance_forward(from_doy: int, to_doy: int) -> int:
-    """Number of days from from_doy forward to to_doy (wrap-aware, 0..365)."""
     return (to_doy - from_doy) % 366 if (to_doy - from_doy) % 366 != 0 else 0
 
 
@@ -301,40 +226,22 @@ def crop_stage_for_date(
     zone_id: str,
     dt: datetime,
 ) -> Tuple[CropStage, Optional[int], Optional[str]]:
-    """Climatological-typical crop stage for a zone on a date.
-
-    Returns (crop_stage, days_to_harvest, season_name).
-      * days_to_harvest is None when the zone is FALLOW or the crop is
-        already inside the harvest window (0 would mean "harvest today";
-        we return 0 then, not None -- None means "no crop in the ground").
-      * season_name is None when FALLOW.
-
-    This is a CALENDAR model, not a field observation. It exists so real
-    pipeline fetches can populate crop_stage / days_to_harvest (which the
-    scorer's harvest-window and harvest-pressure logic needs) instead of
-    leaving them UNKNOWN/None forever on real data.
-    """
     z = get_zone(zone_id)
     doy = dt.timetuple().tm_yday
 
     for season in CROP_CALENDARS[z.calendar]:
         plant_len = _window_len(season.plant_start, season.plant_end)
 
-        # Inside the planting window -> PLANTING; harvest is one growing
-        # period ahead of the END of the window (approximation: crop goes in
-        # mid-window).
         if _in_doy_window(doy, season.plant_start, season.plant_end):
             mid_plant = (season.plant_start + plant_len // 2) % 366 or 366
             grow_len = _doy_distance_forward(mid_plant, season.harvest_start)
             dth = _doy_distance_forward(doy, season.harvest_start)
             return CropStage.PLANTING, max(0, min(dth, grow_len + plant_len)), season.name
 
-        # Two weeks before the planting window -> LAND_PREP.
         prep_start = (season.plant_start - 14) % 366 or 366
         if _in_doy_window(doy, prep_start, season.plant_start):
             return CropStage.LAND_PREP, None, season.name
 
-        # Growing period: plant_end -> harvest_start, phase by fraction.
         grow_len = _doy_distance_forward(season.plant_end, season.harvest_start)
         if grow_len > 0 and _in_doy_window(doy, season.plant_end, season.harvest_start):
             elapsed = _doy_distance_forward(season.plant_end, doy)
@@ -348,7 +255,6 @@ def crop_stage_for_date(
                     break
             return stage, _doy_distance_forward(doy, season.harvest_start), season.name
 
-        # Harvest window itself.
         if _in_doy_window(doy, season.harvest_start, season.harvest_end):
             return CropStage.HARVEST, 0, season.name
 
@@ -359,14 +265,7 @@ def crop_stage_for_date(
 # Monsoon onset
 # ---------------------------------------------------------------------------
 
-# Climatological wet-season onset day-of-year by region group, with the
-# typical interannual std. HEURISTIC values consistent with the broadly
-# documented SE->NW onset progression over the maritime continent (earliest
-# over the south-eastern islands in November, reaching N Sumatra as its
-# Oct-Dec rainfall peak). BMKG's official per-ZOM onset forecast is the
-# production replacement -- see monsoon_onset_estimate() docstring.
 _ONSET_CLIMATOLOGY: Dict[str, Tuple[int, int]] = {
-    # region_group: (base_onset_doy, std_days)
     "ntt":           (320, 18),   # mid-November
     "bali_nt":       (325, 16),
     "java":          (330, 15),   # late Nov / early Dec
@@ -379,7 +278,6 @@ _ONSET_CLIMATOLOGY: Dict[str, Tuple[int, int]] = {
 
 @dataclass(frozen=True)
 class MonsoonOnset:
-    """Wet-season onset estimate for one zone and season year."""
     zone_id: str
     season_year: int                 # the year the wet season STARTS in
     base_onset_doy: int
@@ -399,28 +297,6 @@ def monsoon_onset_estimate(
     year: int,
     basin: Optional[BasinContext] = None,
 ) -> MonsoonOnset:
-    """Estimate wet-season onset for a zone.
-
-    Base value is the regional climatological onset (see
-    _ONSET_CLIMATOLOGY). When a BasinContext is supplied, its ENSO/IOD
-    phases shift the estimate with the DOCUMENTED sign of the
-    teleconnection and an explicitly heuristic magnitude:
-
-      * El Nino (ONI > +0.5): onset delayed over the southern archipelago.
-        +8 days per +1.0 degC ONI anomaly (clipped to [0, +20]).
-      * La Nina (ONI < -0.5): onset advanced. Same magnitude, negative.
-      * Positive IOD (DMI > +0.4): suppressed rainfall over the SE islands
-        -> additional delay of +6 days per +1.0 degC DMI (clipped [0, +15]),
-        halved for Sumatra (weaker IOD coupling that far west).
-      * Negative IOD: mirrored advance.
-
-    These magnitudes are order-of-magnitude heuristics, NOT fitted
-    regressions. The production upgrade is BMKG's official per-ZOM (zona
-    musim) onset forecast, published ahead of each wet season; this
-    function's contract (base + teleconnection adjustment) is designed so
-    a BMKG product can replace `adjusted_onset_doy` without changing
-    callers.
-    """
     z = get_zone(zone_id)
     base_doy, std = _ONSET_CLIMATOLOGY[z.region_group]
 
@@ -461,12 +337,6 @@ def monsoon_onset_estimate(
 
 @dataclass
 class PlantingAdvisory:
-    """Actionable planting-window recommendation for one zone.
-
-    This is the module's planning output: not an alert (crop_risk_scorer
-    already does those) but a forward-looking operational recommendation
-    answering "when should planting happen here, and is water a constraint?".
-    """
     zone_id: str
     generated_at: datetime
 
@@ -514,25 +384,6 @@ def planting_advisory(
     config: Optional[ForecastConfig] = None,
     basin: Optional[BasinContext] = None,
 ) -> PlantingAdvisory:
-    """Build a PlantingAdvisory for a zone from its current obs + forecast.
-
-    Window-selection rule (documented heuristic, tuned for rice land
-    preparation at the start of the wet season):
-
-      * Scan the forecast horizon with a 7-day sliding window.
-      * A window QUALIFIES when:
-          - cumulative precip inside the window is in [MIN, MAX] mm
-            (rainfed: [25, 150] -- enough to rewet the profile, not so much
-            that puddling/transplanting is disrupted;
-             irrigated: [10, 200] -- canal supply relaxes the rain floor),
-          - no single day exceeds 80 mm (waterlogging/transplant damage),
-          - mean prob_drought_day over the window <= 0.6.
-      * The FIRST qualifying window is returned (earliest acceptable start).
-
-    These are agronomic heuristics, not calibrated values; they are
-    constants at the top of the function precisely so they can be tuned
-    against field data later.
-    """
     RAINFED_MIN, RAINFED_MAX = 25.0, 150.0
     IRRIGATED_MIN, IRRIGATED_MAX = 10.0, 200.0
     DAY_CAP_MM = 80.0
@@ -545,7 +396,6 @@ def planting_advisory(
 
     stage, dth, season = crop_stage_for_date(zone_id, vt)
 
-    # --- Scan forecast for a qualifying window ---
     p_min, p_max = (IRRIGATED_MIN, IRRIGATED_MAX) if z.irrigation == "irrigated" \
         else (RAINFED_MIN, RAINFED_MAX)
     precip = list(forecast.precip_mm)
@@ -758,4 +608,4 @@ if __name__ == "__main__":
             print(f"  - {f}")
         sys.exit(1)
     else:
-        print("All 8 test groups passed.")
+        print("All 8 test groups passed.")