fix: report contradictions, NaN propagation, NDBI threshold, blue tint

Five fixes for the v2 analytical report based on the test PDF review:

1. SAR NaN propagation
- Add safe_float helper that converts NaN/inf to 0.0
- Apply at every np.nanmean/nanstd source (sar, ndvi, water, buildup)
- Prevents 'nan dB' / 'z=+nan' strings in headlines and chart data

2. Headline/status alignment
- Add BaseProduct._generate_headline as single source of truth
- Headlines for RED/AMBER never say 'within normal range'; they
describe whichever signal (z-score, hotspot %, anomaly months)
drove the non-GREEN status
- All four products use the unified generator
- Fix _build_seasonal_chart_data to use a year-aware date helper
(was reusing time_range.end.year for every month)
- Buildup chart had unit mismatch (current ha vs raw NDBI ha);
now uses paired baseline buildup fractions for envelope

3. Settlement NDBI threshold for arid terrain
- openEO graph now emits paired NDBI/NDVI bands per timestep
- _compute_stats applies combined mask (NDBI > 0 AND NDVI < 0.2)
to exclude bare soil/rock from built-up classification
- _write_change_raster handles paired layout (with backward-compat
fallback to NDBI-only for legacy data)

4. Satellite overview blue tint
- build_true_color_graph now emits bands in [B04, B03, B02] order
so renderers reading [1,2,3] get true RGB instead of BGR

5. Non-tech language pass on report
- 'EO Product' → 'Indicator' throughout
- Display names: ndvi → 'Vegetation health', water → 'Water bodies',
sar → 'Ground surface change', buildup → 'Built-up areas'
- Plain-language interpretations rewritten
- New 'What to verify on the ground' box per non-GREEN indicator
- Status traffic-light line gains action verbs (action recommended,
worth monitoring, within normal range)
- Anomaly count uses actual N months instead of hardcoded /12

Verified by smoke test: safe_float catches NaN/inf, headline generator
never produces 'within normal range' for non-GREEN status, chart dates
correctly cross year boundaries.

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

app/eo_products/base.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
 import abc
+import math
 import os
 from dataclasses import dataclass, field
+from datetime import date
 from typing import Optional
 
 import numpy as np
@@ -10,6 +12,17 @@ import numpy as np
 from app.models import AOI, TimeRange, ProductResult, ProductMeta
 
 
+def safe_float(v, default: float = 0.0) -> float:
+    """Convert a value to float, replacing NaN/inf with default."""
+    try:
+        f = float(v)
+    except (TypeError, ValueError):
+        return default
+    if math.isnan(f) or math.isinf(f):
+        return default
+    return f
+
+
 @dataclass
 class SpatialData:
     """Spatial data produced by an indicator for map rendering."""
@@ -92,6 +105,72 @@ class BaseProduct(abc.ABC):
             return StatusLevel.AMBER
         return StatusLevel.GREEN
 
+    @staticmethod
+    def _generate_headline(
+        *,
+        status: "StatusLevel",
+        z_current: float,
+        hotspot_pct: float,
+        anomaly_months: int,
+        total_months: int,
+        value_phrase: str,
+        indicator_label: str,
+        direction_up: str = "increase",
+        direction_down: str = "decline",
+    ) -> str:
+        """Generate a plain-language headline that matches the status level.
+
+        Rule: if status is not GREEN, the headline MUST describe the anomaly
+        that triggered the non-GREEN status. Never say "within normal range"
+        for an AMBER or RED status.
+        """
+        from app.models import StatusLevel
+
+        z = safe_float(z_current)
+        hot = safe_float(hotspot_pct)
+
+        if status == StatusLevel.GREEN:
+            return f"{indicator_label} within normal range ({value_phrase})."
+
+        # Pick the driver of the non-GREEN status
+        if abs(z) > 1.0:
+            direction = direction_up if z > 0 else direction_down
+            severity = "major" if status == StatusLevel.RED else "moderate"
+            reason = (
+                f"{severity} {direction} vs seasonal baseline "
+                f"(z={z:+.1f})"
+            )
+        elif hot > 25:
+            reason = f"widespread change in {hot:.0f}% of the area"
+        elif hot > 10:
+            reason = f"localised change in {hot:.0f}% of the area"
+        elif anomaly_months > 0:
+            reason = (
+                f"{anomaly_months} of {total_months} months show anomalies"
+            )
+        else:
+            reason = "anomalous conditions detected"
+
+        return f"{indicator_label}: {reason} ({value_phrase})."
+
+    @staticmethod
+    def _build_monthly_dates(start: "date", n_months: int) -> list[str]:
+        """Return YYYY-MM strings for n consecutive months starting at start.
+
+        Correctly increments the year when crossing December, unlike the old
+        behaviour of reusing time_range.end.year for every month.
+        """
+        dates: list[str] = []
+        year = start.year
+        month = start.month
+        for _ in range(n_months):
+            dates.append(f"{year}-{month:02d}")
+            month += 1
+            if month > 12:
+                month = 1
+                year += 1
+        return dates
+
     @staticmethod
     def _compute_trend_zscore(monthly_zscores: list[float]) -> "TrendDirection":
         """Compute trend from direction of monthly z-scores."""

app/eo_products/buildup.py

@@ -23,7 +23,7 @@ from app.config import (
     ZSCORE_THRESHOLD,
     MIN_CLUSTER_PIXELS,
 )
-from app.eo_products.base import BaseProduct, SpatialData
+from app.eo_products.base import BaseProduct, SpatialData, safe_float
 from app.models import (
     AOI,
     TimeRange,
@@ -46,6 +46,7 @@ logger = logging.getLogger(__name__)
 
 BASELINE_YEARS = 5
 NDBI_THRESHOLD = 0.0  # NDBI > 0 = potential built-up
+NDVI_BUILDUP_MAX = 0.2  # NDVI < 0.2 required to exclude vegetation (combined with NDBI threshold)
 
 
 class BuiltupProduct(BaseProduct):
@@ -142,8 +143,8 @@ class BuiltupProduct(BaseProduct):
 
         # --- Seasonal baseline analysis ---
         current_stats = self._compute_stats(current_path)
-        current_mean = current_stats["overall_mean"]
-        current_frac = current_stats["overall_buildup_fraction"]
+        current_mean = safe_float(current_stats["overall_mean"])
+        current_frac = safe_float(current_stats["overall_buildup_fraction"])
         n_current_bands = current_stats["valid_months"]
         aoi_ha = aoi.area_km2 * 100  # km² → hectares
         current_ha = current_frac * aoi_ha
@@ -162,7 +163,7 @@ class BuiltupProduct(BaseProduct):
             # Z-score for overall current mean NDBI vs seasonal baseline
             if most_recent_month in seasonal_stats and seasonal_stats[most_recent_month]["n_years"] > 0:
                 s = seasonal_stats[most_recent_month]
-                z_current = compute_zscore(current_mean, s["mean"], s["std"], MIN_STD_BUILDUP)
+                z_current = safe_float(compute_zscore(current_mean, s["mean"], s["std"], MIN_STD_BUILDUP))
             else:
                 z_current = 0.0
 
@@ -172,8 +173,8 @@ class BuiltupProduct(BaseProduct):
             for i, val in enumerate(current_stats["monthly_means"]):
                 cal_month = ((start_month + i - 1) % 12) + 1
                 if cal_month in seasonal_stats and seasonal_stats[cal_month]["n_years"] > 0:
-                    z = compute_zscore(val, seasonal_stats[cal_month]["mean"],
-                                       seasonal_stats[cal_month]["std"], MIN_STD_BUILDUP)
+                    z = safe_float(compute_zscore(val, seasonal_stats[cal_month]["mean"],
+                                       seasonal_stats[cal_month]["std"], MIN_STD_BUILDUP))
                     monthly_zscores.append(z)
                     if abs(z) > ZSCORE_THRESHOLD:
                         anomaly_months += 1
@@ -216,27 +217,25 @@ class BuiltupProduct(BaseProduct):
             status = self._classify_zscore(z_current, hotspot_pct)
             trend = self._compute_trend_zscore(monthly_zscores)
 
+            baseline_buildup_fractions = self._build_seasonal_buildup_fractions(
+                baseline_stats["monthly_buildup_fractions"], BASELINE_YEARS,
+            )
             chart_data = self._build_seasonal_chart_data(
-                current_stats["monthly_buildup_fractions"], seasonal_stats,
+                current_stats["monthly_buildup_fractions"], baseline_buildup_fractions,
                 time_range, monthly_zscores, aoi_ha,
             )
 
-            # Headline — z-score driven, with hectare context
-            if abs(z_current) <= 1.0:
-                headline = (
-                    f"Settlement extent stable at ~{current_ha:.0f} ha "
-                    f"(z={z_current:+.1f})"
-                )
-            elif z_current > 0:
-                headline = (
-                    f"Settlement expansion detected: {current_ha:.0f} ha "
-                    f"(z={z_current:+.1f} above seasonal baseline)"
-                )
-            else:
-                headline = (
-                    f"Settlement contraction detected: {current_ha:.0f} ha "
-                    f"(z={z_current:+.1f} below seasonal baseline)"
-                )
+            headline = self._generate_headline(
+                status=status,
+                z_current=z_current,
+                hotspot_pct=hotspot_pct,
+                anomaly_months=anomaly_months,
+                total_months=n_current_bands,
+                value_phrase=f"{current_ha:.0f} ha built-up",
+                indicator_label="Built-up areas",
+                direction_up="expansion",
+                direction_down="contraction",
+            )
 
             # Write change raster for map rendering
             change_map_path = os.path.join(results_dir, "buildup_change.tif")
@@ -488,27 +487,25 @@ class BuiltupProduct(BaseProduct):
 
         status = self._classify_zscore(z_current, hotspot_pct)
         trend = self._compute_trend_zscore(monthly_zscores)
+        baseline_buildup_fractions = self._build_seasonal_buildup_fractions(
+            baseline_stats["monthly_buildup_fractions"], BASELINE_YEARS,
+        )
         chart_data = self._build_seasonal_chart_data(
-            current_stats["monthly_buildup_fractions"], seasonal_stats,
+            current_stats["monthly_buildup_fractions"], baseline_buildup_fractions,
             time_range, monthly_zscores, aoi_ha,
         )
 
-        # Headline — z-score driven, with hectare context
-        if abs(z_current) <= 1.0:
-            headline = (
-                f"Settlement extent stable at ~{current_ha:.0f} ha "
-                f"(z={z_current:+.1f})"
-            )
-        elif z_current > 0:
-            headline = (
-                f"Settlement expansion detected: {current_ha:.0f} ha "
-                f"(z={z_current:+.1f} above seasonal baseline)"
-            )
-        else:
-            headline = (
-                f"Settlement contraction detected: {current_ha:.0f} ha "
-                f"(z={z_current:+.1f} below seasonal baseline)"
-            )
+        headline = self._generate_headline(
+            status=status,
+            z_current=z_current,
+            hotspot_pct=hotspot_pct,
+            anomaly_months=anomaly_months,
+            total_months=n_current_bands,
+            value_phrase=f"{current_ha:.0f} ha built-up",
+            indicator_label="Built-up areas",
+            direction_up="expansion",
+            direction_down="contraction",
+        )
 
         # Write change raster for map rendering
         change_map_path = os.path.join(results_dir, "buildup_change.tif")
@@ -567,38 +564,66 @@ class BuiltupProduct(BaseProduct):
     def _compute_stats(tif_path: str) -> dict[str, Any]:
         """Extract monthly built-up fraction and raw NDBI stats from GeoTIFF.
 
-        Built-up = NDBI > 0.
+        Built-up = NDBI > NDBI_THRESHOLD AND NDVI < NDVI_BUILDUP_MAX.
+        Bands are interleaved (NDBI, NDVI) per month: band 1 = month0 NDBI,
+        band 2 = month0 NDVI, band 3 = month1 NDBI, band 4 = month1 NDVI, ...
+
+        For backward compatibility with single-band (NDBI-only) TIFs, falls
+        back to NDBI-only thresholding when band count is odd or n_bands == 1.
         """
         with rasterio.open(tif_path) as src:
             n_bands = src.count
+            paired_layout = n_bands >= 2 and n_bands % 2 == 0
+            n_months = n_bands // 2 if paired_layout else n_bands
             monthly_fractions: list[float] = []
             monthly_means: list[float] = []
             peak_frac = -1.0
             peak_band = 1
-            for band in range(1, n_bands + 1):
-                data = src.read(band).astype(np.float32)
+
+            for m in range(n_months):
+                if paired_layout:
+                    ndbi_band = m * 2 + 1
+                    ndvi_band = m * 2 + 2
+                    ndbi_data = src.read(ndbi_band).astype(np.float32)
+                    ndvi_data = src.read(ndvi_band).astype(np.float32)
+                else:
+                    ndbi_band = m + 1
+                    ndvi_band = None
+                    ndbi_data = src.read(ndbi_band).astype(np.float32)
+                    ndvi_data = None
+
                 nodata = src.nodata
                 if nodata is not None:
-                    valid = data[data != nodata]
+                    mask = ndbi_data != nodata
                 else:
-                    valid = data.ravel()
-                if len(valid) > 0:
-                    buildup_pixels = np.sum(valid > NDBI_THRESHOLD)
-                    frac = float(buildup_pixels / len(valid))
-                    mean_val = float(np.nanmean(valid))
+                    mask = ~np.isnan(ndbi_data)
+                ndbi_valid = ndbi_data[mask]
+
+                if len(ndbi_valid) > 0:
+                    if ndvi_data is not None:
+                        ndvi_valid = ndvi_data[mask]
+                        buildup_pixels = np.sum(
+                            (ndbi_valid > NDBI_THRESHOLD)
+                            & (ndvi_valid < NDVI_BUILDUP_MAX)
+                        )
+                    else:
+                        buildup_pixels = np.sum(ndbi_valid > NDBI_THRESHOLD)
+                    frac = safe_float(buildup_pixels / len(ndbi_valid))
+                    with np.errstate(all="ignore"):
+                        mean_val = safe_float(np.nanmean(ndbi_valid))
                     monthly_fractions.append(frac)
                     monthly_means.append(mean_val)
                     if frac > peak_frac:
                         peak_frac = frac
-                        peak_band = band
+                        peak_band = ndbi_band
                 else:
                     monthly_fractions.append(0.0)
                     monthly_means.append(0.0)
 
-        overall_frac = float(np.mean(monthly_fractions)) if monthly_fractions else 0.0
+        overall_frac = safe_float(np.mean(monthly_fractions)) if monthly_fractions else 0.0
         valid_months = sum(1 for m in monthly_means if m != 0.0)
         overall_mean = (
-            float(np.mean([m for m in monthly_means if m != 0.0]))
+            safe_float(np.mean([m for m in monthly_means if m != 0.0]))
             if valid_months > 0 else 0.0
         )
 
@@ -606,52 +631,51 @@ class BuiltupProduct(BaseProduct):
             "monthly_buildup_fractions": monthly_fractions,
             "overall_buildup_fraction": overall_frac,
             "valid_months": valid_months,
-            "valid_months_total": n_bands,
+            "valid_months_total": n_months,
             "peak_buildup_band": peak_band,
             "overall_mean": overall_mean,
             "monthly_means": monthly_means,
         }
 
-    @staticmethod
+    @classmethod
     def _build_seasonal_chart_data(
+        cls,
         current_monthly_fractions: list[float],
-        seasonal_stats: dict[int, dict],
+        baseline_seasonal_fractions: dict[int, dict],
         time_range: TimeRange,
         monthly_zscores: list[float],
         aoi_ha: float,
     ) -> dict[str, Any]:
-        """Build chart data with seasonal baseline envelope, in hectares."""
-        start_month = time_range.start.month
-        n = len(current_monthly_fractions)
-        year = time_range.end.year
+        """Build chart data with seasonal baseline envelope, in hectares.
 
-        dates = []
-        values = []
-        b_mean = []
-        b_min = []
-        b_max = []
-        anomaly_flags = []
+        Both current values and baseline envelope use the same unit
+        (built-up fraction × AOI hectares) so the chart is meaningful.
+        """
+        n = len(current_monthly_fractions)
+        dates = cls._build_monthly_dates(time_range.start, n)
+        values: list[float] = []
+        b_mean: list[float] = []
+        b_min: list[float] = []
+        b_max: list[float] = []
+        anomaly_flags: list[bool] = []
+        start_month = time_range.start.month
 
         for i in range(n):
             cal_month = ((start_month + i - 1) % 12) + 1
-            dates.append(f"{year}-{cal_month:02d}")
-            values.append(round(current_monthly_fractions[i] * aoi_ha, 1))
+            values.append(round(safe_float(current_monthly_fractions[i]) * aoi_ha, 1))
 
-            if cal_month in seasonal_stats and seasonal_stats[cal_month]["n_years"] > 0:
-                s = seasonal_stats[cal_month]
-                # Seasonal stats are raw NDBI means; convert to fraction > threshold,
-                # approximate using the baseline mean as a proxy for buildup fraction.
-                # For the envelope, use min/max from seasonal stats scaled to hectares.
-                b_mean.append(round(s["mean"] * aoi_ha, 1) if s["mean"] > 0 else 0.0)
-                b_min.append(round(s["min"] * aoi_ha, 1) if s["min"] > 0 else 0.0)
-                b_max.append(round(s["max"] * aoi_ha, 1) if s["max"] > 0 else 0.0)
+            if cal_month in baseline_seasonal_fractions:
+                s = baseline_seasonal_fractions[cal_month]
+                b_mean.append(round(safe_float(s["mean"]) * aoi_ha, 1))
+                b_min.append(round(safe_float(s["min"]) * aoi_ha, 1))
+                b_max.append(round(safe_float(s["max"]) * aoi_ha, 1))
             else:
                 b_mean.append(0.0)
                 b_min.append(0.0)
                 b_max.append(0.0)
 
             if i < len(monthly_zscores):
-                anomaly_flags.append(abs(monthly_zscores[i]) > ZSCORE_THRESHOLD)
+                anomaly_flags.append(abs(safe_float(monthly_zscores[i])) > ZSCORE_THRESHOLD)
             else:
                 anomaly_flags.append(False)
 
@@ -662,23 +686,66 @@ class BuiltupProduct(BaseProduct):
             "baseline_min": b_min,
             "baseline_max": b_max,
             "anomaly_flags": anomaly_flags,
-            "label": "Built-up area (ha)",
+            "label": "Built-up area (hectares)",
         }
 
+    @staticmethod
+    def _build_seasonal_buildup_fractions(
+        monthly_buildup_fractions: list[float],
+        n_years: int,
+    ) -> dict[int, dict]:
+        """Group baseline monthly buildup fractions by calendar month."""
+        month_buckets: dict[int, list[float]] = {m: [] for m in range(1, 13)}
+        for idx, frac in enumerate(monthly_buildup_fractions):
+            cal_month = (idx % 12) + 1
+            month_buckets[cal_month].append(safe_float(frac))
+
+        result: dict[int, dict] = {}
+        for m, fracs in month_buckets.items():
+            if fracs:
+                result[m] = {
+                    "mean": float(np.mean(fracs)),
+                    "min": float(np.min(fracs)),
+                    "max": float(np.max(fracs)),
+                }
+        return result
+
     @staticmethod
     def _write_change_raster(current_path: str, baseline_path: str, output_path: str) -> None:
-        """Write single-band change raster: current built-up mask minus baseline."""
-        with rasterio.open(current_path) as csrc:
-            c_data = [csrc.read(b + 1).astype(np.float32) for b in range(csrc.count)]
-            c_mean = np.nanmean(np.stack(c_data), axis=0)
-            profile = csrc.profile.copy()
-
-        with rasterio.open(baseline_path) as bsrc:
-            b_data = [bsrc.read(b + 1).astype(np.float32) for b in range(bsrc.count)]
-            b_mean = np.nanmean(np.stack(b_data), axis=0)
-
-        c_buildup = (c_mean > NDBI_THRESHOLD).astype(np.float32)
-        b_buildup = (b_mean > NDBI_THRESHOLD).astype(np.float32)
+        """Write single-band change raster: current built-up mask minus baseline.
+
+        Built-up mask uses combined NDBI > threshold AND NDVI < veg threshold,
+        when the TIF has paired (NDBI, NDVI) bands per timestep. Falls back
+        to NDBI-only when band layout is not paired (legacy data).
+        """
+        def _build_buildup_mask(path: str) -> tuple[np.ndarray, dict]:
+            with rasterio.open(path) as src:
+                count = src.count
+                profile = src.profile.copy()
+                paired = count >= 2 and count % 2 == 0
+                if paired:
+                    n_months = count // 2
+                    ndbi_stack = []
+                    ndvi_stack = []
+                    for m in range(n_months):
+                        ndbi_stack.append(src.read(m * 2 + 1).astype(np.float32))
+                        ndvi_stack.append(src.read(m * 2 + 2).astype(np.float32))
+                    with np.errstate(all="ignore"):
+                        ndbi_mean = np.nanmean(np.stack(ndbi_stack), axis=0)
+                        ndvi_mean = np.nanmean(np.stack(ndvi_stack), axis=0)
+                    ndbi_mean = np.nan_to_num(ndbi_mean, nan=0.0, posinf=0.0, neginf=0.0)
+                    ndvi_mean = np.nan_to_num(ndvi_mean, nan=1.0, posinf=1.0, neginf=1.0)
+                    mask = (ndbi_mean > NDBI_THRESHOLD) & (ndvi_mean < NDVI_BUILDUP_MAX)
+                else:
+                    ndbi_stack = [src.read(b + 1).astype(np.float32) for b in range(count)]
+                    with np.errstate(all="ignore"):
+                        ndbi_mean = np.nanmean(np.stack(ndbi_stack), axis=0)
+                    ndbi_mean = np.nan_to_num(ndbi_mean, nan=0.0, posinf=0.0, neginf=0.0)
+                    mask = ndbi_mean > NDBI_THRESHOLD
+            return mask.astype(np.float32), profile
+
+        c_buildup, profile = _build_buildup_mask(current_path)
+        b_buildup, _ = _build_buildup_mask(baseline_path)
         change = c_buildup - b_buildup
 
         profile.update(count=1, dtype="float32")

app/eo_products/ndvi.py

@@ -22,7 +22,7 @@ from app.config import (
     ZSCORE_THRESHOLD,
     MIN_CLUSTER_PIXELS,
 )
-from app.eo_products.base import BaseProduct, SpatialData
+from app.eo_products.base import BaseProduct, SpatialData, safe_float
 from app.models import (
     AOI,
     TimeRange,
@@ -138,7 +138,7 @@ class NdviProduct(BaseProduct):
 
         # --- Seasonal baseline analysis ---
         current_stats = self._compute_stats(current_path)
-        current_mean = current_stats["overall_mean"]
+        current_mean = safe_float(current_stats["overall_mean"])
         n_current_bands = current_stats["valid_months"]
 
         spatial_completeness = self._compute_spatial_completeness(current_path)
@@ -152,7 +152,7 @@ class NdviProduct(BaseProduct):
 
             if most_recent_month in seasonal_stats and seasonal_stats[most_recent_month]["n_years"] > 0:
                 s = seasonal_stats[most_recent_month]
-                z_current = compute_zscore(current_mean, s["mean"], s["std"], MIN_STD_NDVI)
+                z_current = safe_float(compute_zscore(current_mean, s["mean"], s["std"], MIN_STD_NDVI))
             else:
                 z_current = 0.0
 
@@ -164,8 +164,8 @@ class NdviProduct(BaseProduct):
                     continue
                 cal_month = ((start_month + i - 1) % 12) + 1
                 if cal_month in seasonal_stats and seasonal_stats[cal_month]["n_years"] > 0:
-                    z = compute_zscore(val, seasonal_stats[cal_month]["mean"],
-                                       seasonal_stats[cal_month]["std"], MIN_STD_NDVI)
+                    z = safe_float(compute_zscore(val, seasonal_stats[cal_month]["mean"],
+                                       seasonal_stats[cal_month]["std"], MIN_STD_NDVI))
                     monthly_zscores.append(z)
                     if abs(z) > ZSCORE_THRESHOLD:
                         anomaly_months += 1
@@ -218,17 +218,22 @@ class NdviProduct(BaseProduct):
             trend = TrendDirection.STABLE
             change = 0.0
             chart_data = {
-                "dates": [f"{time_range.end.year}-{m+1:02d}" for m in range(len(current_stats["monthly_means"]))],
-                "values": [round(v, 3) for v in current_stats["monthly_means"]],
-                "label": "NDVI",
+                "dates": self._build_monthly_dates(time_range.start, len(current_stats["monthly_means"])),
+                "values": [round(safe_float(v), 3) for v in current_stats["monthly_means"]],
+                "label": "Vegetation greenness (NDVI)",
             }
 
-        if abs(z_current) <= 1.0:
-            headline = f"Vegetation within normal range (NDVI {current_mean:.2f}, z={z_current:+.1f})"
-        elif z_current > 0:
-            headline = f"Vegetation greening (NDVI {current_mean:.2f}, z={z_current:+.1f} above seasonal average)"
-        else:
-            headline = f"Vegetation decline (NDVI {current_mean:.2f}, z={z_current:+.1f} below seasonal average)"
+        headline = self._generate_headline(
+            status=status,
+            z_current=z_current,
+            hotspot_pct=hotspot_pct,
+            anomaly_months=anomaly_months,
+            total_months=n_current_bands,
+            value_phrase=f"NDVI {current_mean:.2f}",
+            indicator_label="Vegetation health",
+            direction_up="greening",
+            direction_down="decline",
+        )
 
         self._spatial_data = SpatialData(
             map_type="raster", label="NDVI", colormap="RdYlGn",
@@ -335,7 +340,7 @@ class NdviProduct(BaseProduct):
         # --- Seasonal baseline analysis ---
         current_stats = self._compute_stats(current_path)
         baseline_stats = self._compute_stats(baseline_path)
-        current_mean = current_stats["overall_mean"]
+        current_mean = safe_float(current_stats["overall_mean"])
         n_current_bands = current_stats["valid_months"]
         spatial_completeness = self._compute_spatial_completeness(current_path)
 
@@ -345,7 +350,7 @@ class NdviProduct(BaseProduct):
 
         if most_recent_month in seasonal_stats and seasonal_stats[most_recent_month]["n_years"] > 0:
             s = seasonal_stats[most_recent_month]
-            z_current = compute_zscore(current_mean, s["mean"], s["std"], MIN_STD_NDVI)
+            z_current = safe_float(compute_zscore(current_mean, s["mean"], s["std"], MIN_STD_NDVI))
         else:
             z_current = 0.0
 
@@ -357,8 +362,8 @@ class NdviProduct(BaseProduct):
                 continue
             cal_month = ((start_month + i - 1) % 12) + 1
             if cal_month in seasonal_stats and seasonal_stats[cal_month]["n_years"] > 0:
-                z = compute_zscore(val, seasonal_stats[cal_month]["mean"],
-                                   seasonal_stats[cal_month]["std"], MIN_STD_NDVI)
+                z = safe_float(compute_zscore(val, seasonal_stats[cal_month]["mean"],
+                                   seasonal_stats[cal_month]["std"], MIN_STD_NDVI))
                 monthly_zscores.append(z)
                 if abs(z) > ZSCORE_THRESHOLD:
                     anomaly_months += 1
@@ -399,12 +404,17 @@ class NdviProduct(BaseProduct):
         )
         change = current_mean - baseline_stats["overall_mean"]
 
-        if abs(z_current) <= 1.0:
-            headline = f"Vegetation within normal range (NDVI {current_mean:.2f}, z={z_current:+.1f})"
-        elif z_current > 0:
-            headline = f"Vegetation greening (NDVI {current_mean:.2f}, z={z_current:+.1f} above seasonal average)"
-        else:
-            headline = f"Vegetation decline (NDVI {current_mean:.2f}, z={z_current:+.1f} below seasonal average)"
+        headline = self._generate_headline(
+            status=status,
+            z_current=z_current,
+            hotspot_pct=hotspot_pct,
+            anomaly_months=anomaly_months,
+            total_months=n_current_bands,
+            value_phrase=f"NDVI {current_mean:.2f}",
+            indicator_label="Vegetation health",
+            direction_up="greening",
+            direction_down="decline",
+        )
 
         # Spatial data — store the current NDVI path for map rendering
         self._spatial_data = SpatialData(
@@ -470,7 +480,8 @@ class NdviProduct(BaseProduct):
                 else:
                     valid = data.ravel()
                 if len(valid) > 0:
-                    mean = float(np.nanmean(valid))
+                    with np.errstate(all="ignore"):
+                        mean = safe_float(np.nanmean(valid))
                     monthly_means.append(mean)
                     if mean > peak_val:
                         peak_val = mean
@@ -489,42 +500,40 @@ class NdviProduct(BaseProduct):
             "peak_month_band": peak_band,
         }
 
-    @staticmethod
+    @classmethod
     def _build_seasonal_chart_data(
+        cls,
         current_monthly: list[float],
         seasonal_stats: dict[int, dict],
         time_range: TimeRange,
         monthly_zscores: list[float],
     ) -> dict[str, Any]:
         """Build chart data with seasonal baseline envelope."""
-        start_month = time_range.start.month
         n = len(current_monthly)
-        year = time_range.end.year
-
-        dates = []
-        values = []
-        b_mean = []
-        b_min = []
-        b_max = []
-        anomaly_flags = []
+        dates = cls._build_monthly_dates(time_range.start, n)
+        values: list[float] = []
+        b_mean: list[float] = []
+        b_min: list[float] = []
+        b_max: list[float] = []
+        anomaly_flags: list[bool] = []
+        start_month = time_range.start.month
 
         for i in range(n):
             cal_month = ((start_month + i - 1) % 12) + 1
-            dates.append(f"{year}-{cal_month:02d}")
-            values.append(round(current_monthly[i], 3))
+            values.append(round(safe_float(current_monthly[i]), 3))
 
             if cal_month in seasonal_stats and seasonal_stats[cal_month]["n_years"] > 0:
                 s = seasonal_stats[cal_month]
-                b_mean.append(round(s["mean"], 3))
-                b_min.append(round(s["min"], 3))
-                b_max.append(round(s["max"], 3))
+                b_mean.append(round(safe_float(s["mean"]), 3))
+                b_min.append(round(safe_float(s["min"]), 3))
+                b_max.append(round(safe_float(s["max"]), 3))
             else:
                 b_mean.append(0.0)
                 b_min.append(0.0)
                 b_max.append(0.0)
 
             if i < len(monthly_zscores):
-                anomaly_flags.append(abs(monthly_zscores[i]) > ZSCORE_THRESHOLD)
+                anomaly_flags.append(abs(safe_float(monthly_zscores[i])) > ZSCORE_THRESHOLD)
             else:
                 anomaly_flags.append(False)
 
@@ -535,6 +544,6 @@ class NdviProduct(BaseProduct):
             "baseline_min": b_min,
             "baseline_max": b_max,
             "anomaly_flags": anomaly_flags,
-            "label": "NDVI",
+            "label": "Vegetation greenness (NDVI)",
         }
 

app/eo_products/sar.py

@@ -22,7 +22,7 @@ from app.config import (
     ZSCORE_THRESHOLD,
     MIN_CLUSTER_PIXELS,
 )
-from app.eo_products.base import BaseProduct, SpatialData
+from app.eo_products.base import BaseProduct, SpatialData, safe_float
 from app.models import (
     AOI,
     TimeRange,
@@ -133,7 +133,7 @@ class SarProduct(BaseProduct):
 
         # --- Seasonal baseline analysis ---
         current_stats = self._compute_stats(current_path)
-        current_mean = current_stats["overall_vv_mean"]
+        current_mean = safe_float(current_stats["overall_vv_mean"])
         n_current_bands = current_stats["valid_months"]
 
         if n_current_bands == 0:
@@ -154,7 +154,7 @@ class SarProduct(BaseProduct):
 
             if most_recent_month in seasonal_stats and seasonal_stats[most_recent_month]["n_years"] > 0:
                 s = seasonal_stats[most_recent_month]
-                z_current = compute_zscore(current_mean, s["mean"], s["std"], MIN_STD_SAR)
+                z_current = safe_float(compute_zscore(current_mean, s["mean"], s["std"], MIN_STD_SAR))
             else:
                 z_current = 0.0
 
@@ -167,8 +167,8 @@ class SarProduct(BaseProduct):
                     continue
                 cal_month = ((start_month + i - 1) % 12) + 1
                 if cal_month in seasonal_stats and seasonal_stats[cal_month]["n_years"] > 0:
-                    z = compute_zscore(val, seasonal_stats[cal_month]["mean"],
-                                       seasonal_stats[cal_month]["std"], MIN_STD_SAR)
+                    z = safe_float(compute_zscore(val, seasonal_stats[cal_month]["mean"],
+                                       seasonal_stats[cal_month]["std"], MIN_STD_SAR))
                     monthly_zscores.append(z)
                     if abs(z) > ZSCORE_THRESHOLD:
                         anomaly_months += 1
@@ -220,10 +220,11 @@ class SarProduct(BaseProduct):
                 baseline_stats["vv_std"],
             )
 
-            change_db = current_mean - baseline_stats["overall_vv_mean"]
-            change_pct = self._compute_change_area_pct(
+            change_db = safe_float(current_mean - baseline_stats["overall_vv_mean"])
+            change_pct = safe_float(self._compute_change_area_pct(
                 current_path, baseline_path, current_stats, baseline_stats,
-            )
+            ))
+            hotspot_pct = safe_float(hotspot_pct)
 
             status = self._classify_zscore(z_current, hotspot_pct)
             trend = self._compute_trend_zscore(monthly_zscores)
@@ -232,25 +233,24 @@ class SarProduct(BaseProduct):
                 current_stats["monthly_vv_means"], seasonal_stats, time_range, monthly_zscores,
             )
 
-            # Headline
-            parts = []
-            if abs(z_current) > ZSCORE_THRESHOLD:
-                parts.append(f"z={z_current:+.1f} vs seasonal baseline")
-            if change_pct >= 5:
-                parts.append(f"{change_pct:.0f}% ground surface change")
-            if flood_months > 0:
-                parts.append(f"{flood_months} potential flood event{'s' if flood_months > 1 else ''}")
-            if parts:
-                headline = f"SAR backscatter anomaly: {', '.join(parts)} (mean VV {current_mean:.1f} dB)"
-            else:
-                headline = f"Stable backscatter conditions (mean VV {current_mean:.1f} dB, z={z_current:+.1f})"
+            headline = self._generate_headline(
+                status=status,
+                z_current=z_current,
+                hotspot_pct=hotspot_pct,
+                anomaly_months=anomaly_months,
+                total_months=n_current_bands,
+                value_phrase=f"backscatter {current_mean:.1f} dB",
+                indicator_label="Ground surface",
+                direction_up="brightening (drying or new structures)",
+                direction_down="darkening (possible flooding or moisture)",
+            )
 
             change_map_path = os.path.join(results_dir, "sar_change.tif")
             self._write_change_raster(current_path, baseline_path, change_map_path)
 
             self._spatial_data = SpatialData(
                 map_type="raster",
-                label="SAR VV Change (dB)",
+                label="Ground surface change (dB)",
                 colormap="RdBu_r",
                 vmin=-6,
                 vmax=6,
@@ -405,7 +405,7 @@ class SarProduct(BaseProduct):
         # --- Seasonal baseline analysis ---
         current_stats = self._compute_stats(current_path)
         baseline_stats = self._compute_stats(baseline_path)
-        current_mean = current_stats["overall_vv_mean"]
+        current_mean = safe_float(current_stats["overall_vv_mean"])
         n_current_bands = current_stats["valid_months"]
 
         if n_current_bands == 0:
@@ -423,7 +423,7 @@ class SarProduct(BaseProduct):
 
         if most_recent_month in seasonal_stats and seasonal_stats[most_recent_month]["n_years"] > 0:
             s = seasonal_stats[most_recent_month]
-            z_current = compute_zscore(current_mean, s["mean"], s["std"], MIN_STD_SAR)
+            z_current = safe_float(compute_zscore(current_mean, s["mean"], s["std"], MIN_STD_SAR))
         else:
             z_current = 0.0
 
@@ -436,8 +436,8 @@ class SarProduct(BaseProduct):
                 continue
             cal_month = ((start_month + i - 1) % 12) + 1
             if cal_month in seasonal_stats and seasonal_stats[cal_month]["n_years"] > 0:
-                z = compute_zscore(val, seasonal_stats[cal_month]["mean"],
-                                   seasonal_stats[cal_month]["std"], MIN_STD_SAR)
+                z = safe_float(compute_zscore(val, seasonal_stats[cal_month]["mean"],
+                                   seasonal_stats[cal_month]["std"], MIN_STD_SAR))
                 monthly_zscores.append(z)
                 if abs(z) > ZSCORE_THRESHOLD:
                     anomaly_months += 1
@@ -488,10 +488,11 @@ class SarProduct(BaseProduct):
             baseline_stats["vv_std"],
         )
 
-        change_db = current_mean - baseline_stats["overall_vv_mean"]
-        change_pct = self._compute_change_area_pct(
+        change_db = safe_float(current_mean - baseline_stats["overall_vv_mean"])
+        change_pct = safe_float(self._compute_change_area_pct(
             current_path, baseline_path, current_stats, baseline_stats,
-        )
+        ))
+        hotspot_pct = safe_float(hotspot_pct)
 
         status = self._classify_zscore(z_current, hotspot_pct)
         trend = self._compute_trend_zscore(monthly_zscores)
@@ -500,18 +501,17 @@ class SarProduct(BaseProduct):
             current_stats["monthly_vv_means"], seasonal_stats, time_range, monthly_zscores,
         )
 
-        # Headline
-        parts = []
-        if abs(z_current) > ZSCORE_THRESHOLD:
-            parts.append(f"z={z_current:+.1f} vs seasonal baseline")
-        if change_pct >= 5:
-            parts.append(f"{change_pct:.0f}% ground surface change")
-        if flood_months > 0:
-            parts.append(f"{flood_months} potential flood event{'s' if flood_months > 1 else ''}")
-        if parts:
-            headline = f"SAR backscatter anomaly: {', '.join(parts)} (mean VV {current_mean:.1f} dB)"
-        else:
-            headline = f"Stable backscatter conditions (mean VV {current_mean:.1f} dB, z={z_current:+.1f})"
+        headline = self._generate_headline(
+            status=status,
+            z_current=z_current,
+            hotspot_pct=hotspot_pct,
+            anomaly_months=anomaly_months,
+            total_months=n_current_bands,
+            value_phrase=f"backscatter {current_mean:.1f} dB",
+            indicator_label="Ground surface",
+            direction_up="brightening (drying or new structures)",
+            direction_down="darkening (possible flooding or moisture)",
+        )
 
         # Store raster path for map rendering — write a change map
         change_map_path = os.path.join(results_dir, "sar_change.tif")
@@ -519,7 +519,7 @@ class SarProduct(BaseProduct):
 
         self._spatial_data = SpatialData(
             map_type="raster",
-            label="SAR VV Change (dB)",
+            label="Ground surface change (dB)",
             colormap="RdBu_r",
             vmin=-6,
             vmax=6,
@@ -593,7 +593,8 @@ class SarProduct(BaseProduct):
                 else:
                     valid = data.ravel()
                 if len(valid) > 0:
-                    mean_val = float(np.nanmean(valid))
+                    with np.errstate(all="ignore"):
+                        mean_val = safe_float(np.nanmean(valid))
                     monthly_vv_means.append(mean_val)
                     all_vv_values.extend(valid.tolist())
                 else:
@@ -601,8 +602,8 @@ class SarProduct(BaseProduct):
 
         valid_months = sum(1 for m in monthly_vv_means if m != 0.0)
         valid_means = [m for m in monthly_vv_means if m != 0.0]
-        overall_vv_mean = float(np.mean(valid_means)) if valid_means else 0.0
-        vv_std = float(np.std(all_vv_values)) if all_vv_values else 1.0
+        overall_vv_mean = safe_float(np.mean(valid_means)) if valid_means else 0.0
+        vv_std = safe_float(np.std(all_vv_values), default=1.0) if all_vv_values else 1.0
 
         return {
             "monthly_vv_means": monthly_vv_means,
@@ -685,44 +686,46 @@ class SarProduct(BaseProduct):
         with np.errstate(all="ignore"):
             mean = np.nanmean(arr, axis=0)
             std = np.nanstd(arr, axis=0, ddof=1) if arr.shape[0] > 1 else np.zeros_like(mean)
+        # Replace any all-NaN pixel stats with 0 so downstream z-score math is stable
+        mean = np.nan_to_num(mean, nan=0.0, posinf=0.0, neginf=0.0)
+        std = np.nan_to_num(std, nan=0.0, posinf=0.0, neginf=0.0)
         return mean, std
 
-    @staticmethod
+    @classmethod
     def _build_seasonal_chart_data(
+        cls,
         current_monthly: list[float],
         seasonal_stats: dict[int, dict],
         time_range: TimeRange,
         monthly_zscores: list[float],
     ) -> dict[str, Any]:
         """Build chart data with seasonal baseline envelope."""
-        start_month = time_range.start.month
         n = len(current_monthly)
-        year = time_range.end.year
-
-        dates: list[str] = []
+        dates = cls._build_monthly_dates(time_range.start, n)
         values: list[float] = []
         b_mean: list[float] = []
         b_min: list[float] = []
         b_max: list[float] = []
         anomaly_flags: list[bool] = []
+        start_month = time_range.start.month
 
         for i in range(n):
             cal_month = ((start_month + i - 1) % 12) + 1
-            dates.append(f"{year}-{cal_month:02d}")
-            values.append(round(current_monthly[i], 2))
+            values.append(round(safe_float(current_monthly[i]), 2))
 
             if cal_month in seasonal_stats and seasonal_stats[cal_month]["n_years"] > 0:
                 s = seasonal_stats[cal_month]
-                b_mean.append(round(s["mean"], 2))
-                b_min.append(round(s["min"], 2))
-                b_max.append(round(s["max"], 2))
+                b_mean.append(round(safe_float(s["mean"]), 2))
+                b_min.append(round(safe_float(s["min"]), 2))
+                b_max.append(round(safe_float(s["max"]), 2))
             else:
                 b_mean.append(0.0)
                 b_min.append(0.0)
                 b_max.append(0.0)
 
             if i < len(monthly_zscores):
-                anomaly_flags.append(abs(monthly_zscores[i]) > ZSCORE_THRESHOLD)
+                z = safe_float(monthly_zscores[i])
+                anomaly_flags.append(abs(z) > ZSCORE_THRESHOLD)
             else:
                 anomaly_flags.append(False)
 
@@ -733,7 +736,7 @@ class SarProduct(BaseProduct):
             "baseline_min": b_min,
             "baseline_max": b_max,
             "anomaly_flags": anomaly_flags,
-            "label": "VV Backscatter (dB)",
+            "label": "Ground surface backscatter (dB)",
         }
 
     # ------------------------------------------------------------------
@@ -753,17 +756,21 @@ class SarProduct(BaseProduct):
             c_vv = []
             for m in range(c_months):
                 c_vv.append(csrc.read(m * 2 + 1).astype(np.float32))
-            c_mean = np.nanmean(np.stack(c_vv), axis=0)
+            with np.errstate(all="ignore"):
+                c_mean = np.nanmean(np.stack(c_vv), axis=0)
 
             b_vv = []
             for m in range(b_months):
                 b_vv.append(bsrc.read(m * 2 + 1).astype(np.float32))
-            b_mean = np.nanmean(np.stack(b_vv), axis=0)
+            with np.errstate(all="ignore"):
+                b_mean = np.nanmean(np.stack(b_vv), axis=0)
 
+        c_mean = np.nan_to_num(c_mean, nan=0.0, posinf=0.0, neginf=0.0)
+        b_mean = np.nan_to_num(b_mean, nan=0.0, posinf=0.0, neginf=0.0)
         diff = np.abs(c_mean - b_mean)
         significant = np.sum(diff > CHANGE_THRESHOLD_DB)
         total = diff.size
-        return float(significant / total * 100) if total > 0 else 0.0
+        return safe_float(significant / total * 100) if total > 0 else 0.0
 
     @staticmethod
     def _count_flood_months(
@@ -779,14 +786,18 @@ class SarProduct(BaseProduct):
         with rasterio.open(current_path) as csrc:
             c_months = csrc.count // 2
             c_vv = [csrc.read(m * 2 + 1).astype(np.float32) for m in range(c_months)]
-            c_mean = np.nanmean(np.stack(c_vv), axis=0)
+            with np.errstate(all="ignore"):
+                c_mean = np.nanmean(np.stack(c_vv), axis=0)
             profile = csrc.profile.copy()
 
         with rasterio.open(baseline_path) as bsrc:
             b_months = bsrc.count // 2
             b_vv = [bsrc.read(m * 2 + 1).astype(np.float32) for m in range(b_months)]
-            b_mean = np.nanmean(np.stack(b_vv), axis=0)
+            with np.errstate(all="ignore"):
+                b_mean = np.nanmean(np.stack(b_vv), axis=0)
 
+        c_mean = np.nan_to_num(c_mean, nan=0.0, posinf=0.0, neginf=0.0)
+        b_mean = np.nan_to_num(b_mean, nan=0.0, posinf=0.0, neginf=0.0)
         change = c_mean - b_mean
         profile.update(count=1, dtype="float32")
         with rasterio.open(output_path, "w", **profile) as dst:

app/eo_products/water.py

@@ -22,7 +22,7 @@ from app.config import (
     ZSCORE_THRESHOLD,
     MIN_CLUSTER_PIXELS,
 )
-from app.eo_products.base import BaseProduct, SpatialData
+from app.eo_products.base import BaseProduct, SpatialData, safe_float
 from app.models import (
     AOI,
     TimeRange,
@@ -139,8 +139,8 @@ class WaterProduct(BaseProduct):
 
         # --- Seasonal baseline analysis ---
         current_stats = self._compute_stats(current_path)
-        current_mean = current_stats["overall_mean"]
-        current_frac = current_stats["overall_water_fraction"]
+        current_mean = safe_float(current_stats["overall_mean"])
+        current_frac = safe_float(current_stats["overall_water_fraction"])
         n_current_bands = current_stats["valid_months"]
 
         spatial_completeness = self._compute_spatial_completeness(current_path)
@@ -154,7 +154,7 @@ class WaterProduct(BaseProduct):
 
             if most_recent_month in seasonal_stats and seasonal_stats[most_recent_month]["n_years"] > 0:
                 s = seasonal_stats[most_recent_month]
-                z_current = compute_zscore(current_mean, s["mean"], s["std"], MIN_STD_WATER)
+                z_current = safe_float(compute_zscore(current_mean, s["mean"], s["std"], MIN_STD_WATER))
             else:
                 z_current = 0.0
 
@@ -166,8 +166,8 @@ class WaterProduct(BaseProduct):
                     continue
                 cal_month = ((start_month + i - 1) % 12) + 1
                 if cal_month in seasonal_stats and seasonal_stats[cal_month]["n_years"] > 0:
-                    z = compute_zscore(val, seasonal_stats[cal_month]["mean"],
-                                       seasonal_stats[cal_month]["std"], MIN_STD_WATER)
+                    z = safe_float(compute_zscore(val, seasonal_stats[cal_month]["mean"],
+                                       seasonal_stats[cal_month]["std"], MIN_STD_WATER))
                     monthly_zscores.append(z)
                     if abs(z) > ZSCORE_THRESHOLD:
                         anomaly_months += 1
@@ -228,17 +228,22 @@ class WaterProduct(BaseProduct):
             self._zscore_raster = None
             self._hotspot_mask = None
             chart_data = {
-                "dates": [f"{time_range.end.year}-{m+1:02d}" for m in range(len(current_stats["monthly_water_fractions"]))],
-                "values": [round(v * 100, 1) for v in current_stats["monthly_water_fractions"]],
-                "label": "Water extent (%)",
+                "dates": self._build_monthly_dates(time_range.start, len(current_stats["monthly_water_fractions"])),
+                "values": [round(safe_float(v) * 100, 1) for v in current_stats["monthly_water_fractions"]],
+                "label": "Water extent (% of area)",
             }
 
-        if abs(z_current) <= 1.0:
-            headline = f"Water extent within seasonal range ({current_frac*100:.1f}%, z={z_current:+.1f})"
-        elif z_current > 0:
-            headline = f"Water extent above seasonal average ({current_frac*100:.1f}%, z={z_current:+.1f})"
-        else:
-            headline = f"Water extent anomaly detected ({current_frac*100:.1f}%, z={z_current:+.1f})"
+        headline = self._generate_headline(
+            status=status,
+            z_current=z_current,
+            hotspot_pct=hotspot_pct,
+            anomaly_months=anomaly_months,
+            total_months=n_current_bands,
+            value_phrase=f"{current_frac*100:.1f}% of area covered by water",
+            indicator_label="Water bodies",
+            direction_up="expansion (possible flooding)",
+            direction_down="contraction (possible drought)",
+        )
 
         self._spatial_data = SpatialData(
             map_type="raster",
@@ -345,8 +350,8 @@ class WaterProduct(BaseProduct):
         # --- Seasonal baseline analysis ---
         current_stats = self._compute_stats(current_path)
         baseline_stats = self._compute_stats(baseline_path)
-        current_mean = current_stats["overall_mean"]
-        current_frac = current_stats["overall_water_fraction"]
+        current_mean = safe_float(current_stats["overall_mean"])
+        current_frac = safe_float(current_stats["overall_water_fraction"])
         n_current_bands = current_stats["valid_months"]
         spatial_completeness = self._compute_spatial_completeness(current_path)
 
@@ -356,7 +361,7 @@ class WaterProduct(BaseProduct):
 
         if most_recent_month in seasonal_stats and seasonal_stats[most_recent_month]["n_years"] > 0:
             s = seasonal_stats[most_recent_month]
-            z_current = compute_zscore(current_mean, s["mean"], s["std"], MIN_STD_WATER)
+            z_current = safe_float(compute_zscore(current_mean, s["mean"], s["std"], MIN_STD_WATER))
         else:
             z_current = 0.0
 
@@ -368,8 +373,8 @@ class WaterProduct(BaseProduct):
                 continue
             cal_month = ((start_month + i - 1) % 12) + 1
             if cal_month in seasonal_stats and seasonal_stats[cal_month]["n_years"] > 0:
-                z = compute_zscore(val, seasonal_stats[cal_month]["mean"],
-                                   seasonal_stats[cal_month]["std"], MIN_STD_WATER)
+                z = safe_float(compute_zscore(val, seasonal_stats[cal_month]["mean"],
+                                   seasonal_stats[cal_month]["std"], MIN_STD_WATER))
                 monthly_zscores.append(z)
                 if abs(z) > ZSCORE_THRESHOLD:
                     anomaly_months += 1
@@ -415,12 +420,17 @@ class WaterProduct(BaseProduct):
         )
         change = current_mean - baseline_stats["overall_mean"]
 
-        if abs(z_current) <= 1.0:
-            headline = f"Water extent within seasonal range ({current_frac*100:.1f}%, z={z_current:+.1f})"
-        elif z_current > 0:
-            headline = f"Water extent above seasonal average ({current_frac*100:.1f}%, z={z_current:+.1f})"
-        else:
-            headline = f"Water extent anomaly detected ({current_frac*100:.1f}%, z={z_current:+.1f})"
+        headline = self._generate_headline(
+            status=status,
+            z_current=z_current,
+            hotspot_pct=hotspot_pct,
+            anomaly_months=anomaly_months,
+            total_months=n_current_bands,
+            value_phrase=f"{current_frac*100:.1f}% of area covered by water",
+            indicator_label="Water bodies",
+            direction_up="expansion (possible flooding)",
+            direction_down="contraction (possible drought)",
+        )
 
         self._spatial_data = SpatialData(
             map_type="raster",
@@ -487,9 +497,10 @@ class WaterProduct(BaseProduct):
                     valid = data.ravel()
                 if len(valid) > 0:
                     water_pixels = np.sum(valid > WATER_THRESHOLD)
-                    frac = float(water_pixels / len(valid))
+                    frac = safe_float(water_pixels / len(valid))
                     monthly_fractions.append(frac)
-                    mean_val = float(np.nanmean(valid))
+                    with np.errstate(all="ignore"):
+                        mean_val = safe_float(np.nanmean(valid))
                     monthly_means.append(mean_val)
                     if frac > peak_frac:
                         peak_frac = frac
@@ -549,8 +560,9 @@ class WaterProduct(BaseProduct):
                 }
         return result
 
-    @staticmethod
+    @classmethod
     def _build_seasonal_chart_data(
+        cls,
         current_monthly_fractions: list[float],
         baseline_seasonal_fractions: dict[int, dict],
         time_range: TimeRange,
@@ -571,34 +583,31 @@ class WaterProduct(BaseProduct):
         monthly_zscores:
             Per-month z-scores for anomaly flagging.
         """
-        start_month = time_range.start.month
         n = len(current_monthly_fractions)
-        year = time_range.end.year
-
-        dates = []
-        values = []
-        b_mean = []
-        b_min = []
-        b_max = []
-        anomaly_flags = []
+        dates = cls._build_monthly_dates(time_range.start, n)
+        values: list[float] = []
+        b_mean: list[float] = []
+        b_min: list[float] = []
+        b_max: list[float] = []
+        anomaly_flags: list[bool] = []
+        start_month = time_range.start.month
 
         for i in range(n):
             cal_month = ((start_month + i - 1) % 12) + 1
-            dates.append(f"{year}-{cal_month:02d}")
-            values.append(round(current_monthly_fractions[i] * 100, 1))
+            values.append(round(safe_float(current_monthly_fractions[i]) * 100, 1))
 
             if cal_month in baseline_seasonal_fractions:
                 s = baseline_seasonal_fractions[cal_month]
-                b_mean.append(round(s["mean"] * 100, 1))
-                b_min.append(round(s["min"] * 100, 1))
-                b_max.append(round(s["max"] * 100, 1))
+                b_mean.append(round(safe_float(s["mean"]) * 100, 1))
+                b_min.append(round(safe_float(s["min"]) * 100, 1))
+                b_max.append(round(safe_float(s["max"]) * 100, 1))
             else:
                 b_mean.append(0.0)
                 b_min.append(0.0)
                 b_max.append(0.0)
 
             if i < len(monthly_zscores):
-                anomaly_flags.append(abs(monthly_zscores[i]) > ZSCORE_THRESHOLD)
+                anomaly_flags.append(abs(safe_float(monthly_zscores[i])) > ZSCORE_THRESHOLD)
             else:
                 anomaly_flags.append(False)
 
@@ -609,5 +618,5 @@ class WaterProduct(BaseProduct):
             "baseline_min": b_min,
             "baseline_max": b_max,
             "anomaly_flags": anomaly_flags,
-            "label": "Water extent (%)",
+            "label": "Water extent (% of area)",
         }

app/openeo_client.py

@@ -149,8 +149,10 @@ def build_true_color_graph(
     cloud_mask = (scl == 4) | (scl == 5) | (scl == 6)
     cube = cube.mask(cloud_mask == 0)
 
-    # Drop SCL, keep RGB
-    rgb = cube.filter_bands(["B02", "B03", "B04"])
+    # Drop SCL, keep RGB in actual R,G,B order so band 1=Red, 2=Green, 3=Blue.
+    # (S2 native order is B02 Blue, B03 Green, B04 Red — we reorder here so
+    # downstream renderers can read bands [1,2,3] as RGB without swapping.)
+    rgb = cube.filter_bands(["B04", "B03", "B02"])
 
     # Temporal median composite
     composite = rgb.reduce_dimension(dimension="t", reducer="median")
@@ -240,15 +242,18 @@ def build_buildup_graph(
     temporal_extent: list[str],
     resolution_m: int = 20,
 ) -> openeo.DataCube:
-    """Build an openEO process graph for monthly NDBI built-up index composites.
+    """Build an openEO process graph for monthly built-up composites.
 
-    NDBI = (B11 - B08) / (B11 + B08). Higher values indicate impervious surfaces.
-    Cloud-masked via SCL band, aggregated to monthly medians.
+    Emits two bands per timestep:
+        - NDBI = (B11 - B08) / (B11 + B08)  — built-up index
+        - NDVI = (B08 - B04) / (B08 + B04)  — vegetation index
 
-    Native resolution is 20m (due to B11 SWIR band). Resamples only if coarser resolution requested.
+    The pair is needed because NDBI alone misclassifies bare soil/rock
+    as built-up in arid landscapes. The indicator's _compute_stats applies
+    the combined mask (NDBI > threshold AND NDVI < vegetation threshold)
+    to isolate true impervious surfaces.
 
-    The binary built-up mask (NDBI > 0 AND NDVI < 0.2) is computed in the
-    indicator's process() method, not here — keeping the graph builder simple.
+    Native resolution is 20m (due to B11 SWIR band). Cloud-masked via SCL.
     """
     cube = conn.load_collection(
         collection_id="SENTINEL2_L2A",
@@ -262,13 +267,18 @@ def build_buildup_graph(
     cloud_mask = (scl == 4) | (scl == 5) | (scl == 6)
     cube = cube.mask(cloud_mask == 0)
 
-    # NDBI = (SWIR - NIR) / (SWIR + NIR)
-    b11 = cube.band("B11")
+    b04 = cube.band("B04")
     b08 = cube.band("B08")
+    b11 = cube.band("B11")
+
     ndbi = (b11 - b08) / (b11 + b08)
+    ndvi = (b08 - b04) / (b08 + b04)
+
+    # Stack NDBI and NDVI as a 2-band datacube
+    stacked = ndbi.merge_cubes(ndvi)
 
     # Monthly median composite
-    monthly = ndbi.aggregate_temporal_period("month", reducer="median")
+    monthly = stacked.aggregate_temporal_period("month", reducer="median")
 
     # Always reproject to EPSG:4326
     monthly = monthly.resample_spatial(resolution=resolution_m / 111320, projection="EPSG:4326")

app/outputs/narrative.py

@@ -6,22 +6,42 @@ from typing import Sequence
 from app.models import ProductResult, StatusLevel, TrendDirection
 
 
-# --- Per-indicator interpretation templates ---
+# --- Per-indicator interpretation templates (plain language) ---
 _INTERPRETATIONS: dict[tuple[str, StatusLevel], str] = {
-    ("ndvi", StatusLevel.RED): "A decline of this magnitude typically indicates severe crop stress, overgrazing, or drought impact.",
-    ("ndvi", StatusLevel.AMBER): "Moderate vegetation decline may reflect seasonal stress or early-stage degradation.",
-    ("ndvi", StatusLevel.GREEN): "Vegetation cover is within the normal range for this area and season.",
-    ("water", StatusLevel.RED): "Significant water extent change beyond the baseline suggests major flooding or hydrological disruption.",
-    ("water", StatusLevel.AMBER): "Moderate water extent changes may indicate seasonal flooding or irrigation changes.",
-    ("water", StatusLevel.GREEN): "Water extent is within normal seasonal variation.",
-    ("sar", StatusLevel.RED): "Major SAR backscatter anomalies indicate significant ground surface changes \u2014 possible flooding, construction, or deforestation.",
-    ("sar", StatusLevel.AMBER): "Moderate SAR changes may reflect seasonal soil moisture variation or gradual land-use change.",
-    ("sar", StatusLevel.GREEN): "SAR backscatter is within the normal range, indicating stable ground conditions.",
-    ("buildup", StatusLevel.RED): "Rapid settlement expansion at this rate suggests significant population displacement or unplanned urban growth.",
-    ("buildup", StatusLevel.AMBER): "Moderate settlement growth detected, consistent with gradual urbanization.",
-    ("buildup", StatusLevel.GREEN): "Settlement extent is stable relative to the baseline period.",
+    ("ndvi", StatusLevel.RED): "Vegetation is well below normal for this season. This pattern is consistent with severe drought, widespread crop failure, intense grazing pressure, or rapid land clearing.",
+    ("ndvi", StatusLevel.AMBER): "Vegetation is somewhat below normal for this season. May reflect early-season drought stress, mild degradation, or patchy land-use change.",
+    ("ndvi", StatusLevel.GREEN): "Vegetation cover is within the normal range for this area and season — no anomaly detected.",
+    ("water", StatusLevel.RED): "Surface water differs sharply from the seasonal norm. This may indicate flooding, dam release, drought, or hydrological disruption — direction and pattern matter.",
+    ("water", StatusLevel.AMBER): "Surface water is somewhat outside the normal seasonal range. Possible early flood, irrigation change, or drying.",
+    ("water", StatusLevel.GREEN): "Surface water is within the normal seasonal range.",
+    ("sar", StatusLevel.RED): "Radar signal shows major ground-surface changes. Common causes: flooding, new construction, deforestation, or large soil-moisture shifts.",
+    ("sar", StatusLevel.AMBER): "Radar signal shows moderate ground-surface changes. May reflect seasonal soil moisture variation or gradual land-use change.",
+    ("sar", StatusLevel.GREEN): "Radar signal is within the normal range — ground surface looks stable.",
+    ("buildup", StatusLevel.RED): "Built-up area shows rapid change. In a humanitarian context this can indicate displacement-driven settlement growth, unplanned camps, or destruction.",
+    ("buildup", StatusLevel.AMBER): "Built-up area shows moderate change, consistent with gradual urbanisation.",
+    ("buildup", StatusLevel.GREEN): "Built-up area is stable relative to the baseline period.",
 }
 
+
+# --- "What to verify on the ground" suggestions per indicator + status ---
+_VERIFY_SUGGESTIONS: dict[tuple[str, StatusLevel], str] = {
+    ("ndvi", StatusLevel.RED): "Check rainfall records, FEWS NET food security alerts, and contact local agronomists. Look for fire scars, locust reports, or recent clearing.",
+    ("ndvi", StatusLevel.AMBER): "Compare with seasonal rainfall and consult local extension officers if this falls in a growing season.",
+    ("water", StatusLevel.RED): "Cross-check with river gauge data, dam releases, and recent weather. If flooding is suspected, verify with affected communities or partner organisations downstream.",
+    ("water", StatusLevel.AMBER): "Compare with rainfall logs and seasonal flood calendars for the region.",
+    ("sar", StatusLevel.RED): "Cross-check with optical imagery (cloud-free dates), settlement reports, and conflict event data. Hotspot map shows where to look first.",
+    ("sar", StatusLevel.AMBER): "Compare with rainfall and seasonal moisture patterns; consider whether this aligns with known activity.",
+    ("buildup", StatusLevel.RED): "Check displacement and IDP reports, recent satellite imagery from open sources (Copernicus EMS, UNOSAT), and partner field assessments. Examine the change map for clusters.",
+    ("buildup", StatusLevel.AMBER): "Compare with population estimates and recent infrastructure projects.",
+}
+
+
+def get_verify_suggestion(product_id: str, status: StatusLevel) -> str:
+    """Return a 1-sentence 'what to verify' suggestion, or empty string if none."""
+    if status == StatusLevel.GREEN:
+        return ""
+    return _VERIFY_SUGGESTIONS.get((product_id, status), "")
+
 # --- Cross-indicator pattern rules ---
 _CROSS_PATTERNS: list[tuple[dict[str, set[StatusLevel]], str]] = [
     (
@@ -39,9 +59,9 @@ _CROSS_PATTERNS: list[tuple[dict[str, set[StatusLevel]], str]] = [
 ]
 
 _LEAD_TEMPLATES = {
-    StatusLevel.RED: "The situation shows critical concern across one or more EO products.",
-    StatusLevel.AMBER: "The situation shows elevated concern requiring monitoring.",
-    StatusLevel.GREEN: "All EO products are within normal ranges for this area and period.",
+    StatusLevel.RED: "One or more indicators show major changes that warrant action and ground verification.",
+    StatusLevel.AMBER: "One or more indicators show elevated change that should be monitored.",
+    StatusLevel.GREEN: "All indicators are within normal ranges for this area and period.",
 }
 
 

app/outputs/report.py

@@ -24,10 +24,12 @@ from reportlab.platypus.flowables import KeepTogether
 
 from app.models import AOI, TimeRange, ProductResult, StatusLevel
 
-# Display names for indicator IDs that don't title-case correctly
+# Plain-language display names — non-tech readers see these, not the raw IDs.
 _DISPLAY_NAMES: dict[str, str] = {
-    "sar": "SAR Backscatter",
-    "buildup": "Settlement Extent",
+    "ndvi": "Vegetation health",
+    "water": "Water bodies",
+    "sar": "Ground surface change",
+    "buildup": "Built-up areas",
 }
 
 
@@ -236,8 +238,17 @@ def _product_block(
     elements.append(Paragraph("<b>What this means</b>", styles["body_muted"]))
     elements.append(Paragraph(interpretation, styles["body"]))
 
+    # What to verify on the ground (only when there is a non-GREEN finding)
+    from app.outputs.narrative import get_verify_suggestion
+    verify = get_verify_suggestion(result.product_id, result.status)
+    if verify:
+        elements.append(Paragraph("<b>What to verify on the ground</b>", styles["body_muted"]))
+        elements.append(Paragraph(verify, styles["body"]))
+
     # Data quality line
-    data_source_label = result.data_source or "unknown"
+    data_source_label = (result.data_source or "unknown").capitalize()
+    if data_source_label.lower() == "satellite":
+        data_source_label = "Satellite imagery"
     quality_line = (
         f"Confidence: <b>{result.confidence.value.capitalize()}</b> &nbsp;|&nbsp; "
         f"Trend: <b>{result.trend.value.capitalize()}</b> &nbsp;|&nbsp; "
@@ -419,11 +430,11 @@ def generate_pdf_report(
     green_count = sum(1 for r in results if r.status == StatusLevel.GREEN)
     total = len(results)
     count_line = (
-        f"This report covers <b>{total}</b> EO product(s) for <b>{aoi.name}</b> "
+        f"This report covers <b>{total}</b> indicator(s) for <b>{aoi.name}</b> "
         f"over the period {time_range.start} to {time_range.end}. "
-        f"<b><font color='{_RED_HEX}'>{red_count}</font></b> at RED, "
-        f"<b><font color='{_AMBER_HEX}'>{amber_count}</font></b> at AMBER, "
-        f"<b><font color='{_GREEN_HEX}'>{green_count}</font></b> at GREEN."
+        f"<b><font color='{_RED_HEX}'>{red_count}</font></b> at RED (action recommended), "
+        f"<b><font color='{_AMBER_HEX}'>{amber_count}</font></b> at AMBER (worth monitoring), "
+        f"<b><font color='{_GREEN_HEX}'>{green_count}</font></b> at GREEN (within normal range)."
     )
     story.append(Paragraph(count_line, styles["body"]))
 
@@ -433,11 +444,11 @@ def generate_pdf_report(
 
     # Compact summary table
     summary_header = [
-        Paragraph("<b>EO Product</b>", styles["body"]),
+        Paragraph("<b>Indicator</b>", styles["body"]),
         Paragraph("<b>Status</b>", styles["body"]),
         Paragraph("<b>Trend</b>", styles["body"]),
         Paragraph("<b>Confidence</b>", styles["body"]),
-        Paragraph("<b>Anomalies</b>", styles["body"]),
+        Paragraph("<b>Anomaly months</b>", styles["body"]),
         Paragraph("<b>Headline</b>", styles["body"]),
     ]
     summary_rows = [summary_header]
@@ -453,13 +464,15 @@ def generate_pdf_report(
                 alignment=TA_CENTER,
             ),
         )
+        # Total months observed (extracted from chart_data dates if present)
+        total_months = len(result.chart_data.get("dates", [])) or 12
         summary_rows.append([
             Paragraph(label, styles["body_muted"]),
             status_cell,
             Paragraph(result.trend.value.capitalize(), styles["body_muted"]),
             Paragraph(result.confidence.value.capitalize(), styles["body_muted"]),
-            Paragraph(f"{result.anomaly_months}/12", styles["body_muted"]),
-            Paragraph(result.headline[:70], styles["body_muted"]),
+            Paragraph(f"{result.anomaly_months}/{total_months}", styles["body_muted"]),
+            Paragraph(result.headline[:90], styles["body_muted"]),
         ])
 
     ov_col_w = PAGE_W - 2 * MARGIN
@@ -518,7 +531,7 @@ def generate_pdf_report(
     # ================================================================== #
     #  SECTION 3: Indicator Deep Dives                                    #
     # ================================================================== #
-    story.append(Paragraph("EO Product Detail", styles["section_heading"]))
+    story.append(Paragraph("Indicator Detail", styles["section_heading"]))
     story.append(Spacer(1, 2 * mm))
 
     for result in results:
@@ -558,7 +571,7 @@ def generate_pdf_report(
     story.append(Spacer(1, 2 * mm))
 
     conf_header = [
-        Paragraph("<b>EO Product</b>", styles["body"]),
+        Paragraph("<b>Indicator</b>", styles["body"]),
         Paragraph("<b>Temporal</b>", styles["body"]),
         Paragraph("<b>Baseline Depth</b>", styles["body"]),
         Paragraph("<b>Spatial Compl.</b>", styles["body"]),
@@ -616,7 +629,7 @@ def generate_pdf_report(
         "remote sensing data. Results are intended to support humanitarian situation analysis "
         "and should be interpreted alongside ground-truth information and expert judgement. "
         "Temporal coverage, cloud contamination, and sensor resolution may affect the "
-        "reliability of individual EO products."
+        "reliability of individual indicators."
     )
     story.append(Paragraph("Disclaimer", styles["section_heading"]))
     story.append(Paragraph(disclaimer, styles["body_muted"]))