Upload folder using huggingface_hub (part 2)

.gitattributes

@@ -219,3 +219,4 @@ datasets/c3s_seasonal/hindcast_month08.nc filter=lfs diff=lfs merge=lfs -text
 datasets/meteofrance_precipitation/daily_precipitation.csv filter=lfs diff=lfs merge=lfs -text
 datasets/single_trace_H605641201_2026-01-01.png filter=lfs diff=lfs merge=lfs -text
 datasets/spatiotemporal_gnn/selected_subgraph.png filter=lfs diff=lfs merge=lfs -text
+scripts/training/__pycache__/train_spatiotemporal_gnn.cpython-311.pyc filter=lfs diff=lfs merge=lfs -text

scripts/analysis/analyze_bdtopo_hydro.py

@@ -0,0 +1,245 @@
+"""
+Analyze the BD TOPO hydrography pulled by download_bdtopo_hydro.py:
+
+1. check_karst_near_betoire() -- does surface_hydrographique actually
+   have a karst-classified feature near the amont/aval bétoire stations
+   (H605641101 / H605641201)? Pure Python, no geopandas needed, so this
+   part works immediately regardless of what's installed.
+
+2. export_real_centerline() -- replace our approximate digitized
+   centerline (traced from a road-map screenshot, ~4km georeferencing
+   error) with the real troncon_hydrographique geometry for a named
+   river, properly ordered. Needs geopandas + shapely.
+
+Usage:
+    python analyze_bdtopo_hydro.py --check-karst
+    python analyze_bdtopo_hydro.py --export-centerline "Risle" --output datasets/centerlines/risle_centerline.csv
+"""
+import argparse
+import json
+import math
+from pathlib import Path
+
+# Known amont/aval bétoire station coordinates (from station_list.csv)
+BETOIRE_STATIONS = {
+    "H605641101": ("Ajou [amont bétoire]", 48.98492, 0.78902),
+    "H605641201": ("Grosley-sur-Risle [aval bétoire]", 49.04707, 0.79984),
+}
+
+
+def _haversine_km(lat1, lon1, lat2, lon2) -> float:
+    R = 6371.0
+    lat1, lon1, lat2, lon2 = map(math.radians, [lat1, lon1, lat2, lon2])
+    dlat, dlon = lat2 - lat1, lon2 - lon1
+    a = math.sin(dlat / 2) ** 2 + math.cos(lat1) * math.cos(lat2) * math.sin(dlon / 2) ** 2
+    return R * 2 * math.asin(math.sqrt(a))
+
+
+def _feature_min_distance_km(feature: dict, lat: float, lon: float) -> float:
+    """Minimum distance from (lat, lon) to any vertex of a GeoJSON
+    LineString/MultiLineString/Point feature. Vertex-level, not true
+    point-to-line distance, but plenty precise at this scale given
+    typical vertex spacing."""
+    geom = feature.get("geometry") or {}
+    gtype = geom.get("type")
+    coords = geom.get("coordinates")
+    if coords is None:
+        return float("inf")
+
+    def flatten(c, depth):
+        if depth == 0:
+            yield c
+        else:
+            for sub in c:
+                yield from flatten(sub, depth - 1)
+
+    depth = {"Point": 0, "LineString": 1, "MultiLineString": 2,
+              "Polygon": 2, "MultiPolygon": 3}.get(gtype)
+    if depth is None:
+        return float("inf")
+
+    best = float("inf")
+    for pt in flatten(coords, depth):
+        plon, plat = pt[0], pt[1]
+        d = _haversine_km(lat, lon, plat, plon)
+        if d < best:
+            best = d
+    return best
+
+
+def check_karst_near_betoire(
+    surface_hydro_path: Path,
+    search_radius_km: float = 3.0,
+) -> None:
+    """
+    Search surface_hydrographique.geojson for any feature whose `Nature`
+    property mentions karst, within `search_radius_km` of either bétoire
+    station. Prints a clear verdict either way -- this is the check that
+    actually answers whether the bétoire naming is backed by a mapped
+    feature or just a station-naming convention.
+    """
+    data = json.loads(surface_hydro_path.read_text())
+    features = data.get("features", [])
+    print(f"Loaded {len(features)} feature(s) from {surface_hydro_path}")
+
+    karst_features = []
+    for f in features:
+        nature = (f.get("properties") or {}).get("nature") or (f.get("properties") or {}).get("Nature") or ""
+        if "karst" in str(nature).lower():
+            karst_features.append(f)
+
+    print(f"Features with 'karst' in Nature: {len(karst_features)}")
+    if not karst_features:
+        print()
+        print("VERDICT: No karst-classified surface_hydrographique feature found "
+              "anywhere in the downloaded area. Either this stretch isn't tagged "
+              "as karst in BD TOPO (the 'bétoire' naming may be informal/historical "
+              "rather than a currently-mapped classification), or the Nature "
+              "property uses different wording than expected -- worth printing a "
+              "few sample Nature values to check (see below).")
+        sample_natures = {(f.get("properties") or {}).get("nature") or (f.get("properties") or {}).get("Nature")
+                           for f in features[:200]}
+        print(f"Sample Nature values seen in this file: {sorted(str(n) for n in sample_natures if n)[:20]}")
+        return
+
+    print()
+    for f in karst_features:
+        props = f.get("properties", {})
+        for code, (name, lat, lon) in BETOIRE_STATIONS.items():
+            dist = _feature_min_distance_km(f, lat, lon)
+            flag = " <-- WITHIN SEARCH RADIUS" if dist <= search_radius_km else ""
+            print(f"  Karst feature {props.get('nature', props.get('Nature'))!r} "
+                  f"is {dist:.2f} km from {code} ({name}){flag}")
+
+    close = [f for f in karst_features
+             for code, (name, lat, lon) in BETOIRE_STATIONS.items()
+             if _feature_min_distance_km(f, lat, lon) <= search_radius_km]
+    print()
+    if close:
+        print(f"VERDICT: CONFIRMED -- {len(close)} karst-classified feature(s) found "
+              f"within {search_radius_km} km of the bétoire stations. The station "
+              f"naming is backed by an actual mapped karst feature, not just "
+              f"historical naming convention.")
+    else:
+        nearest = min(
+            (_feature_min_distance_km(f, lat, lon), code)
+            for f in karst_features
+            for code, (name, lat, lon) in BETOIRE_STATIONS.items()
+        )
+        print(f"VERDICT: Karst features exist in this area, but the nearest one to "
+              f"a bétoire station is {nearest[0]:.2f} km away (from {nearest[1]}) -- "
+              f"outside the {search_radius_km} km search radius. Consider widening "
+              f"--search-radius-km if this still seems plausibly related.")
+
+
+def export_real_centerline(
+    troncon_path: Path,
+    river_name: str,
+    output_path: Path,
+    name_field_candidates=("cpx_toponyme_de_cours_d_eau", "toponyme", "nom_cours_d_eau"),
+) -> None:
+    """
+    Filter troncon_hydrographique to the tronçons belonging to a named
+    river, merge and order them into a single sequence, and write out a
+    centerline CSV in the same [seq, longitude, latitude] shape as our
+    digitized centerlines -- so this can be a drop-in replacement with
+    real metric-precision geometry instead of the ~4km-accurate traced
+    version.
+
+    Requires geopandas + shapely.
+    """
+    try:
+        import geopandas as gpd
+        import networkx as nx
+    except ImportError as e:
+        raise ImportError("export_real_centerline needs geopandas and networkx: "
+                           "pip install geopandas networkx") from e
+
+    gdf = gpd.read_file(troncon_path)
+    print(f"Loaded {len(gdf)} tronçons from {troncon_path}")
+    print(f"Available columns: {list(gdf.columns)}")
+
+    name_field = next((c for c in name_field_candidates if c in gdf.columns), None)
+    if name_field is None:
+        raise ValueError(
+            f"None of {name_field_candidates} found in columns. "
+            f"Inspect gdf.columns and pass the right one manually."
+        )
+
+    river_gdf = gdf[gdf[name_field].astype(str).str.contains(river_name, case=False, na=False)]
+    print(f"Matched {len(river_gdf)} tronçon(s) for river name '{river_name}' "
+          f"(field: {name_field})")
+    if river_gdf.empty:
+        sample = gdf[name_field].dropna().unique()[:20]
+        print(f"No matches. Sample values in '{name_field}': {list(sample)}")
+        return
+
+    # Build a graph from tronçon endpoints to find the correct traversal
+    # order (a tronçon's own row order in the file is not guaranteed to
+    # follow the river's course -- same lesson as station_list.csv).
+    G = nx.Graph()
+    for _, row in river_gdf.iterrows():
+        coords = [(c[0], c[1]) for c in row.geometry.coords]  # drop Z (altitude) if present
+        start, end = coords[0], coords[-1]
+        G.add_edge(start, end, coords=coords)
+
+    if G.number_of_nodes() == 0:
+        print("No valid geometry found.")
+        return
+
+    components = list(nx.connected_components(G))
+    if len(components) > 1:
+        print(f"Warning: river tronçons form {len(components)} disconnected "
+              f"component(s) -- using the largest one ({max(len(c) for c in components)} nodes). "
+              f"This can happen at basin edges or with name-matching gaps.")
+    main_component = max(components, key=len)
+    subG = G.subgraph(main_component)
+
+    # Walk the longest path through the component (same double-BFS
+    # technique used for the digitized centerline extraction).
+    start_node = next(iter(subG.nodes))
+    lengths = nx.single_source_shortest_path_length(subG, start_node)
+    a = max(lengths, key=lengths.get)
+    lengths2 = nx.single_source_shortest_path_length(subG, a)
+    b = max(lengths2, key=lengths2.get)
+    node_path = nx.shortest_path(subG, a, b)
+
+    all_coords = []
+    for u, v in zip(node_path[:-1], node_path[1:]):
+        edge_coords = subG.edges[u, v]["coords"]
+        if edge_coords[0] != u:
+            edge_coords = list(reversed(edge_coords))
+        all_coords.extend(edge_coords if not all_coords else edge_coords[1:])
+
+    import pandas as pd
+    result = pd.DataFrame(all_coords, columns=["longitude", "latitude"])
+    result.insert(0, "seq", range(len(result)))
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    result.to_csv(output_path, index=False)
+    print(f"Saved {len(result)}-point real centerline for '{river_name}' to {output_path}")
+    print("This is real metric-precision BD TOPO geometry -- replace the old "
+          "digitized version by pointing centerline_dir at this file.")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Analyze BD TOPO hydrography")
+    parser.add_argument("--data-dir", type=Path, default=Path("datasets/bdtopo_hydro"))
+    parser.add_argument("--check-karst", action="store_true")
+    parser.add_argument("--search-radius-km", type=float, default=3.0)
+    parser.add_argument("--export-centerline", type=str, default=None,
+                         help="River name to extract, e.g. 'Risle' or 'Eure'")
+    parser.add_argument("--output", type=Path, default=None)
+    args = parser.parse_args()
+
+    if args.check_karst:
+        check_karst_near_betoire(args.data_dir / "surface_hydrographique.geojson",
+                                  args.search_radius_km)
+
+    if args.export_centerline:
+        out = args.output or Path(f"datasets/centerlines/{args.export_centerline.lower()}_centerline_real.csv")
+        export_real_centerline(args.data_dir / "troncon_hydrographique.geojson",
+                                args.export_centerline, out)
+
+
+if __name__ == "__main__":
+    main()

scripts/analysis/check_cavity_proximity.py

@@ -0,0 +1,169 @@
+"""
+Real, independent karst cross-check for every real gauge station, using
+the actual raw BDCavités data -- not the precomputed distance_to_
+nearest_cavity_km column, which turned out to never have been saved
+anywhere in the current reach-graph pipeline (confirmed directly: the
+column is absent from both real enriched node files, despite the raw
+cavité data itself existing on disk).
+
+Built specifically because the current karst/losing-reach flag
+(verified_continuous=False on 3 real edges of La Risle's bétoire
+stretch) is a hardcoded list based on real station naming evidence
+("[amont bétoire]"/"[aval bétoire]"), not a systematic scan -- it can
+only ever confirm what was already suspected from names, never surface
+a DIFFERENT real station that also sits near a real cavity but never
+got a "bétoire"-style name. This script is that systematic scan.
+
+Usage:
+    python -m scripts.analysis.check_cavity_proximity --data-root datasets
+"""
+import argparse
+import json
+from pathlib import Path
+from typing import List, Optional
+
+import numpy as np
+import pandas as pd
+
+
+def _haversine_km_vec(lat1, lon1, lat2, lon2):
+    """Real haversine distance, vectorized -- same formula used
+    throughout this project's other real distance computations."""
+    R = 6371.0
+    lat1, lon1, lat2, lon2 = map(np.radians, [lat1, lon1, lat2, lon2])
+    dlat, dlon = lat2 - lat1, lon2 - lon1
+    a = np.sin(dlat / 2) ** 2 + np.cos(lat1) * np.cos(lat2) * np.sin(dlon / 2) ** 2
+    return R * 2 * np.arcsin(np.sqrt(a))
+
+
+def load_real_cavity_coordinates(geojson_path: Path, allowed_types: Optional[List[str]] = None) -> np.ndarray:
+    """
+    Extracts real [lat, lon] pairs directly from the raw BDCavités
+    GeoJSON -- point features only, skipping anything malformed rather
+    than crashing the whole load on a single bad real record (large
+    real government datasets do have occasional genuine data-quality
+    issues; skip-and-count is more useful here than a hard failure).
+
+    allowed_types, when given, filters on the real "type_cavite" field.
+    Confirmed as a real, necessary filter, not an optional refinement:
+    an unfiltered first run showed 24 of 27 real stations within 1km of
+    *some* cavity, with counts in the thousands -- because BDCavités
+    catalogs every cavity type, and the real breakdown (confirmed
+    directly against this project's actual file) is dominated by
+    quarries (carrière, 21,813), civil/military structures (ouvrage
+    civil/militaire, ~9,900), and cellars (cave, 3,990) -- none
+    hydrologically meaningful. Only "naturelle" (8,313) corresponds to
+    genuine natural cavities, the category that could actually indicate
+    real karst/water-loss connectivity. "indéterminé" (18,349) is
+    genuinely ambiguous -- could hide real unclassified natural
+    features or unclassified quarries -- so it's deliberately not
+    included by default; check separately with it included rather than
+    assume either way.
+    """
+    with open(geojson_path) as f:
+        data = json.load(f)
+
+    coords = []
+    n_skipped = 0
+    n_filtered = 0
+    for feature in data.get("features", []):
+        geom = feature.get("geometry")
+        if geom is None or geom.get("type") != "Point":
+            n_skipped += 1
+            continue
+        if allowed_types is not None:
+            real_type = feature.get("properties", {}).get("type_cavite")
+            if real_type not in allowed_types:
+                n_filtered += 1
+                continue
+        lon, lat = geom["coordinates"][0], geom["coordinates"][1]
+        coords.append((lat, lon))
+
+    filter_msg = f", {n_filtered} filtered out by type" if allowed_types is not None else ""
+    print(f"Loaded {len(coords)} real cavity point(s) from {geojson_path.name} "
+          f"({n_skipped} non-point/malformed feature(s) skipped{filter_msg})")
+    return np.array(coords)
+
+
+def check_cavity_proximity(stations_df: pd.DataFrame, cavity_coords: np.ndarray, radius_km: float = 20.0) -> pd.DataFrame:
+    """
+    Real nearest-cavity distance and real cavity count within radius_km,
+    per real station -- same two metrics documented for the (never
+    actually saved) distance_to_nearest_cavity_km / n_cavities_within_
+    20km features, computed fresh here directly against the real raw
+    data.
+    """
+    cav_lat, cav_lon = cavity_coords[:, 0], cavity_coords[:, 1]
+    results = []
+    for _, row in stations_df.iterrows():
+        dists = _haversine_km_vec(row["latitude"], row["longitude"], cav_lat, cav_lon)
+        nearest_km = float(dists.min())
+        n_within_radius = int((dists <= radius_km).sum())
+        results.append({
+            "station_code": row["station_code"],
+            "distance_to_nearest_cavity_km": nearest_km,
+            "n_cavities_within_20km": n_within_radius,
+        })
+    return pd.DataFrame(results).sort_values("distance_to_nearest_cavity_km")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Real cavity-proximity cross-check for every real gauge station")
+    parser.add_argument("--data-root", type=Path, default=Path("datasets"))
+    parser.add_argument("--stations-path", type=Path, default=None)
+    parser.add_argument("--close-threshold-km", type=float, default=1.0,
+                         help="Real distance below which a station is flagged as plausibly karst-connected.")
+    args = parser.parse_args()
+
+    stations_path = args.stations_path or (args.data_root / "station_elevations.csv")
+    stations_df = pd.read_csv(stations_path)
+
+    geojson_path = args.data_root / "bdcavites" / "cavite_localisee.geojson"
+    if not geojson_path.exists():
+        print(f"No real cavity file found at {geojson_path} -- run "
+              f"scripts.data_acquisition.download_bdcavites first.")
+        return
+
+    # Two real, confirmed-necessary filtered runs, not one -- an
+    # unfiltered check showed 24/27 real stations within 1km of *some*
+    # cavity (counts in the thousands), because BDCavités catalogs
+    # every cavity type and quarries/civil structures/cellars dominate
+    # the real breakdown. "naturelle" is the conservative, defensible
+    # filter; "naturelle + indéterminé" is a broader one that also
+    # captures any real natural feature that was never properly typed
+    # -- reported side by side rather than picking one and hiding the
+    # other's disagreement.
+    for label, allowed_types in [
+        ("naturelle only (conservative)", ["naturelle"]),
+        ("naturelle + indéterminé (broader)", ["naturelle", "indéterminé"]),
+    ]:
+        print()
+        print("=" * 70)
+        print(f"Filter: {label}")
+        print("=" * 70)
+        cavity_coords = load_real_cavity_coordinates(geojson_path, allowed_types=allowed_types)
+        if len(cavity_coords) == 0:
+            print("Zero real cavities matched this filter -- nothing to check against.")
+            continue
+
+        result_df = check_cavity_proximity(stations_df, cavity_coords)
+        print(result_df.to_string(index=False))
+
+        close = result_df[result_df["distance_to_nearest_cavity_km"] < args.close_threshold_km]
+        print()
+        if len(close) > 0:
+            print(f"Station(s) within {args.close_threshold_km}km of a real, filtered cavity "
+                  f"(cross-check against the known bétoire stations -- H605641101, H605022010, "
+                  f"H605641401, H605641201 -- anything else here is a real, new candidate):")
+            print(close.to_string(index=False))
+        else:
+            print(f"No real station within {args.close_threshold_km}km of a real, filtered cavity.")
+
+        output_path = args.data_root / f"cavity_proximity_check_{allowed_types[0]}.csv"
+        result_df.to_csv(output_path, index=False)
+        print(f"Saved to {output_path}")
+    print(f"\nSaved to {output_path}")
+
+
+if __name__ == "__main__":
+    main()

scripts/analysis/check_forecast_lead5_anomaly.py

@@ -0,0 +1,120 @@
+"""
+Direct check of the raw previous_runs_forecast.csv archive, independent
+of the model/evaluation pipeline -- built specifically because
+evaluate_flood_detection.py's --dump-fp-details showed something
+systematic and graph-wide at the 5-day horizon (185/185 real test
+examples produced at least one real false positive there, often
+several stations simultaneously, including stations on different
+rivers with no surface connection). --check-forecast-fp-correlation
+already ruled out forecast AVAILABILITY as the driver; this checks
+whether the real forecast VALUES themselves are anomalous specifically
+at lead time 5, compared to the other real lead times in the same file.
+
+Usage:
+    python -m scripts.analysis.check_forecast_lead5_anomaly --data-root datasets
+"""
+import argparse
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+FORECAST_LEAD_TIMES = [1, 2, 3, 5, 7]  # matches dynamic_features.py's real, confirmed coverage
+
+
+def summarize_lead_time_column(df: pd.DataFrame, lead_time: int) -> dict:
+    """
+    Real summary statistics for one real precipitation_previous_dayN
+    column -- real coverage, real central tendency, real spread, and
+    explicit counts of two real, concrete anomaly types (negative
+    precipitation, which is physically impossible, and implausibly
+    extreme values) rather than just eyeballing a mean/max pair.
+    """
+    col = f"precipitation_previous_day{lead_time}"
+    if col not in df.columns:
+        return {"lead_time": lead_time, "column_present": False}
+
+    values = df[col].dropna()
+    n_negative = int((values < 0).sum())
+    # A real, extreme daily precipitation threshold -- the wettest days
+    # ever recorded anywhere are on the order of a few hundred mm; used
+    # here only to flag values worth a second look, not as a hard
+    # physical cutoff.
+    n_extreme = int((values > 300).sum())
+
+    return {
+        "lead_time": lead_time,
+        "column_present": True,
+        "n_real": len(values),
+        "mean": float(values.mean()) if len(values) else float("nan"),
+        "median": float(values.median()) if len(values) else float("nan"),
+        "std": float(values.std()) if len(values) else float("nan"),
+        "min": float(values.min()) if len(values) else float("nan"),
+        "max": float(values.max()) if len(values) else float("nan"),
+        "n_negative": n_negative,
+        "n_extreme_gt_300mm": n_extreme,
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Check the real ECMWF forecast archive for a lead-time-5-specific anomaly")
+    parser.add_argument("--data-root", type=Path, default=Path("datasets"))
+    parser.add_argument("--forecast-path", type=Path, default=None,
+                         help="Defaults to <data-root>/previous_runs_forecast.csv")
+    args = parser.parse_args()
+
+    forecast_path = args.forecast_path or (args.data_root / "previous_runs_forecast.csv")
+    if not forecast_path.exists():
+        print(f"No real forecast archive found at {forecast_path}.")
+        return
+
+    df = pd.read_csv(forecast_path)
+    print(f"Loaded {len(df)} real row(s) from {forecast_path}")
+    print()
+
+    rows = []
+    for lead_time in FORECAST_LEAD_TIMES:
+        summary = summarize_lead_time_column(df, lead_time)
+        rows.append(summary)
+
+    result_df = pd.DataFrame(rows)
+    print("=" * 70)
+    print("Real forecast precipitation, by lead time (mm)")
+    print("=" * 70)
+    print(result_df.to_string(index=False))
+
+    present = result_df[result_df["column_present"]]
+    if len(present) < 2:
+        print("\nFewer than 2 real lead-time columns present -- nothing to compare.")
+        return
+
+    if 5 in present["lead_time"].values:
+        lead5 = present[present["lead_time"] == 5].iloc[0]
+        others = present[present["lead_time"] != 5]
+        others_mean_of_means = others["mean"].mean()
+        others_mean_of_maxes = others["max"].mean()
+        print(f"\nLead time 5 mean ({lead5['mean']:.2f}mm) vs. real average of other lead times' means "
+              f"({others_mean_of_means:.2f}mm)")
+        print(f"Lead time 5 max ({lead5['max']:.2f}mm) vs. real average of other lead times' maxes "
+              f"({others_mean_of_maxes:.2f}mm)")
+        print(f"Lead time 5 negative values: {int(lead5['n_negative'])}; extreme (>300mm) values: "
+              f"{int(lead5['n_extreme_gt_300mm'])}")
+
+        mean_ratio = lead5["mean"] / others_mean_of_means if others_mean_of_means > 0 else float("inf")
+        max_ratio = lead5["max"] / others_mean_of_maxes if others_mean_of_maxes > 0 else float("inf")
+        if mean_ratio > 2.0 or max_ratio > 2.0 or lead5["n_negative"] > 0:
+            print(f"\nLead time 5 shows a real, meaningful anomaly relative to the other real lead times "
+                  f"(mean ratio {mean_ratio:.2f}x, max ratio {max_ratio:.2f}x) -- real, direct evidence "
+                  f"worth investigating further as the actual cause of the day-5 false-positive pattern.")
+        else:
+            print(f"\nLead time 5 does NOT show a meaningful anomaly relative to the other real lead "
+                  f"times (mean ratio {mean_ratio:.2f}x, max ratio {max_ratio:.2f}x) -- the raw forecast "
+                  f"values themselves aren't the explanation; the real cause likely lies in how this "
+                  f"lead time's data is being consumed downstream (e.g. the anchor/target-date mapping, "
+                  f"or the model's own horizon-conditioning for h=5 specifically), not the raw archive.")
+    else:
+        print("\nLead time 5 column not present in this real file -- can't run the real comparison.")
+
+
+if __name__ == "__main__":
+    main()

scripts/analysis/cross_check_catchments.py

@@ -0,0 +1,50 @@
+"""
+Spatially match each station to the catchment polygon that actually
+contains it (point-in-polygon), rather than guessing at a shared ID
+field across BD TOPO and Hub'Eau. This is the correct approach when
+two datasets don't share a clean join key.
+"""
+import sys
+sys.path.insert(0, ".")
+from pathlib import Path
+import pandas as pd
+import geopandas as gpd
+
+from src.data.loaders.bdtopo_hydro import BDTopoHydroLoader
+
+loader = BDTopoHydroLoader(data_path=Path("datasets/bdtopo_hydro"))
+catchments = loader.load_catchments()
+catchments_metric = catchments.to_crs(epsg=2154)  # Lambert-93 for accurate area in meters
+catchments["area_km2"] = catchments_metric.geometry.area / 1e6
+
+stations = pd.read_csv("datasets/station_elevations.csv")
+hubeau = pd.read_csv("datasets/catchment_area.csv").dropna(subset=["catchment_area_km2"])
+
+stations_gdf = gpd.GeoDataFrame(
+    stations,
+    geometry=gpd.points_from_xy(stations["longitude"], stations["latitude"]),
+    crs="EPSG:4326",
+).to_crs(catchments.crs)
+
+# Spatial join: which catchment polygon contains each station?
+joined = gpd.sjoin(stations_gdf, catchments[["area_km2", "toponyme", "geometry"]],
+                    how="left", predicate="within")
+
+result = joined[["station_code", "toponyme", "area_km2"]].rename(
+    columns={"area_km2": "bdtopo_area_km2", "toponyme": "bdtopo_catchment_name"}
+)
+result = result.merge(hubeau[["station_code", "catchment_area_km2"]], on="station_code", how="left")
+result = result.rename(columns={"catchment_area_km2": "hubeau_area_km2"})
+result["ratio"] = result["bdtopo_area_km2"] / result["hubeau_area_km2"]
+
+print(result.to_string(index=False))
+print()
+matched = result.dropna(subset=["bdtopo_area_km2", "hubeau_area_km2"])
+print(f"Stations with BOTH a containing BD TOPO polygon AND a Hub'Eau value: {len(matched)}")
+if len(matched) > 0:
+    print(f"Area ratio (BD TOPO / Hub'Eau) — mean: {matched['ratio'].mean():.2f}, "
+          f"median: {matched['ratio'].median():.2f}")
+    print("(A ratio near 1.0 across most stations would confirm both sources agree; "
+          "large/inconsistent ratios would suggest the polygons represent something "
+          "other than the gauge's own catchment -- e.g. a downstream aggregate, or "
+          "no polygon actually contains that point due to bbox edge effects.)")

scripts/analysis/run_bdtopo_checks.py

@@ -0,0 +1,71 @@
+"""
+Run this against your real downloaded BD TOPO data to:
+1. Actually answer the karst/bétoire question with real data.
+2. Cross-validate the new catchment polygons against Hub'Eau's surface_bv
+   numbers (from catchment_area.csv, built earlier via download_catchment_area.py).
+"""
+import sys
+sys.path.insert(0, ".")
+from pathlib import Path
+from src.data.loaders.bdtopo_hydro import BDTopoHydroLoader
+
+loader = BDTopoHydroLoader(data_path=Path("datasets/bdtopo_hydro"))
+
+# --- 1. The karst question, for real this time ---
+print("=" * 70)
+print("KARST CHECK near amont/aval bétoire stations")
+print("=" * 70)
+BETOIRE_STATIONS = {
+    "H605641101": ("Ajou [amont bétoire]", 48.98492, 0.78902),
+    "H605641201": ("Grosley-sur-Risle [aval bétoire]", 49.04707, 0.79984),
+}
+surfaces = loader.load_surfaces()
+any_found = False
+for code, (name, lat, lon) in BETOIRE_STATIONS.items():
+    results = loader.check_karst_near_point(lat, lon, search_radius_km=3.0, surfaces_geojson=surfaces)
+    print(f"\n{code} ({name}):")
+    if results:
+        any_found = True
+        for r in results:
+            print(f"  -> {r['nature']!r} at {r['distance_km']:.2f} km")
+    else:
+        print("  -> no karst-classified feature within 3 km")
+
+print()
+if any_found:
+    print("VERDICT: CONFIRMED by real BD TOPO data -- the bétoire naming is backed "
+          "by an actual mapped karst feature.")
+else:
+    print("VERDICT: No karst feature found within 3km. Try a wider search radius, "
+          "or this may just be historical/informal naming not reflected in the "
+          "current BD TOPO classification.")
+
+# --- 2. Cross-validate catchment polygons against Hub'Eau surface_bv ---
+print()
+print("=" * 70)
+print("CATCHMENT POLYGON CROSS-CHECK vs Hub'Eau surface_bv")
+print("=" * 70)
+try:
+    import geopandas as gpd
+    import pandas as pd
+
+    catchments = loader.load_catchments()
+    print(f"Loaded {len(catchments)} catchment polygon(s)")
+    print(f"Columns: {list(catchments.columns)}")
+
+    hubeau_path = Path("datasets/catchment_area.csv")
+    if hubeau_path.exists():
+        hubeau = pd.read_csv(hubeau_path).dropna(subset=["catchment_area_km2"])
+        print(f"\nLoaded {len(hubeau)} Hub'Eau reference values from {hubeau_path}")
+        # Compute polygon areas in km^2 (reproject to a metric CRS for accurate area)
+        catchments_metric = catchments.to_crs(epsg=2154)  # Lambert-93, standard for France
+        catchments["area_km2_computed"] = catchments_metric.geometry.area / 1e6
+        print(catchments[["area_km2_computed"]].describe())
+        print("\n(Match these against datasets/catchment_area.csv's real Hub'Eau values "
+              "by whichever ID field the polygons carry -- check catchments.columns "
+              "above for a station/site code to join on.)")
+    else:
+        print(f"\n{hubeau_path} not found -- skipping cross-check. "
+              f"(Run download_catchment_area.py first if you want this comparison.)")
+except ImportError:
+    print("geopandas not installed -- skipping catchment polygon check.")

scripts/analysis/trace_forecast_lookup.py

@@ -0,0 +1,127 @@
+"""
+Directly traces a handful of real false positives (from evaluate_flood_
+detection.py's --dump-fp-details output) through build_forecast_tensor's
+actual real lookup logic, by hand, to check for a real date-convention
+mismatch -- built after noticing something concrete while investigating
+the day-5 false-positive pattern:
+
+Every other real place in this project that maps a horizon h to a real
+calendar date uses target_date = anchor + (h - 1) -- confirmed directly
+in both prepare_graph_training_windows (the real training-target
+construction) and evaluate_flood_detection.py's own confusion-matrix
+loop. But build_forecast_tensor uses target_date = anchor + h (no "-1").
+
+This means: for horizon h, the real target this project is actually
+predicting is at anchor + (h-1), but the forecast value FED INTO the
+model for that same horizon slot is looked up at anchor + h -- one
+real calendar day later than the thing actually being predicted. This
+script shows exactly what real forecast row/column gets retrieved for
+real (anchor, h=5) pairs pulled from an actual false-positive dump, so
+the real size and direction of this mismatch is visible directly,
+not just asserted.
+
+Usage:
+    python -m scripts.analysis.trace_forecast_lookup --data-root datasets \
+        --fp-details datasets/fp_details_horizon_5.csv --horizon 5
+"""
+import argparse
+from pathlib import Path
+
+import pandas as pd
+
+
+def trace_one(anchor: pd.Timestamp, station_code: str, horizon: int, df_indexed: pd.DataFrame) -> dict:
+    """
+    Mirrors build_forecast_tensor's real lookup exactly -- same
+    target_date/column formula, same real row lookup -- so this shows
+    precisely what that function actually retrieves for this real
+    (anchor, horizon) pair, not an approximation of it.
+    """
+    real_target_date = anchor + pd.Timedelta(days=horizon - 1)  # what's ACTUALLY being predicted
+    forecast_lookup_date = anchor + pd.Timedelta(days=horizon)  # what build_forecast_tensor ACTUALLY queries
+    col = f"precipitation_previous_day{horizon}"
+
+    result = {
+        "anchor": anchor.date().isoformat(),
+        "real_target_date": real_target_date.date().isoformat(),
+        "forecast_lookup_date": forecast_lookup_date.date().isoformat(),
+        "date_mismatch_days": (forecast_lookup_date - real_target_date).days,
+        "station_code": station_code,
+        "column": col,
+    }
+    try:
+        value = df_indexed.loc[(forecast_lookup_date, station_code), col]
+        result["forecast_value_actually_used"] = float(value) if pd.notna(value) else None
+    except KeyError:
+        result["forecast_value_actually_used"] = None
+
+    # What the forecast value WOULD have been if looked up at the real
+    # target date instead, for direct comparison -- not necessarily a
+    # "correct" value (that date's own previous_day{h} column reflects
+    # a different, (h) days in advance forecast, not h-1), just useful
+    # to see whether it's meaningfully different from what's actually used.
+    try:
+        value_at_real_target = df_indexed.loc[(real_target_date, station_code), col]
+        result["value_at_real_target_date_same_column"] = float(value_at_real_target) if pd.notna(value_at_real_target) else None
+    except KeyError:
+        result["value_at_real_target_date_same_column"] = None
+
+    return result
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Trace real forecast lookups for a handful of real false positives")
+    parser.add_argument("--data-root", type=Path, default=Path("datasets"))
+    parser.add_argument("--forecast-path", type=Path, default=None,
+                         help="Defaults to <data-root>/previous_runs_forecast.csv")
+    parser.add_argument("--fp-details", type=Path, required=True,
+                         help="Path to a real fp_details_horizon_N.csv from evaluate_flood_detection.py's --dump-fp-details")
+    parser.add_argument("--horizon", type=int, required=True)
+    parser.add_argument("--n-samples", type=int, default=10)
+    args = parser.parse_args()
+
+    forecast_path = args.forecast_path or (args.data_root / "previous_runs_forecast.csv")
+    if not forecast_path.exists():
+        print(f"No real forecast archive found at {forecast_path}.")
+        return
+    if not args.fp_details.exists():
+        print(f"No real false-positive detail file found at {args.fp_details}.")
+        return
+
+    forecast_df = pd.read_csv(forecast_path)
+    forecast_df["date"] = pd.to_datetime(forecast_df["date"])
+    df_indexed = forecast_df.set_index(["date", "station_code"])
+
+    fp_df = pd.read_csv(args.fp_details)
+    fp_df["target_date"] = pd.to_datetime(fp_df["target_date"])
+    # fp_details' own target_date IS the real target date (h-1
+    # convention, matching evaluate_flood_detection.py's own confusion-
+    # matrix loop) -- recover the real anchor from it directly.
+    fp_df["anchor"] = fp_df["target_date"] - pd.Timedelta(days=args.horizon - 1)
+
+    sample = fp_df.head(args.n_samples)
+    print(f"Tracing {len(sample)} real false positive(s) at horizon={args.horizon}d through the real "
+          f"forecast lookup logic\n")
+
+    rows = []
+    for _, row in sample.iterrows():
+        traced = trace_one(row["anchor"], row["station_code"], args.horizon, df_indexed)
+        rows.append(traced)
+
+    result_df = pd.DataFrame(rows)
+    print(result_df.to_string(index=False))
+
+    n_mismatched_dates = int((result_df["date_mismatch_days"] != 0).sum())
+    print(f"\n{n_mismatched_dates}/{len(result_df)} real traced examples show a real date mismatch "
+          f"between what's being predicted (real_target_date) and what the forecast is actually "
+          f"looked up for (forecast_lookup_date).")
+    if n_mismatched_dates > 0:
+        print(f"This is a real, systematic {result_df['date_mismatch_days'].iloc[0]}-day offset (from "
+              f"build_forecast_tensor's target_date = anchor + h, vs. every other real place in this "
+              f"project using anchor + h - 1) -- the model is being conditioned on the forecast for the "
+              f"day AFTER what it's actually predicting at this horizon, not the forecast for the real "
+              f"target date itself.")
+
+
+if __name__ == "__main__":
+    main()

scripts/data_acquisition/download_bdcavites.py

@@ -0,0 +1,146 @@
+"""
+Downloads BDCavités (BRGM's national underground cavity inventory --
+karst sinkholes, quarries, marl pits, natural cavities) for the Eure/
+Risle area, via Géorisques' WFS.
+
+Directly relevant to the bétoire investigation: this is an independent,
+purpose-built dataset for exactly this phenomenon, unlike inferring it
+from Hub'Eau station naming or BD TOPO's provisional karst attribute.
+
+CONFIRMED (fetched GetCapabilities directly): endpoint
+https://georisques.gouv.fr/services, WFS 1.1.0, typeName
+CAVITE_LOCALISEE ("Cavités souterraines abandonnées d'origine non
+minière"), GeoJSON output supported directly. Axis order for this
+specific server is NOT separately confirmed -- reusing the same
+lon,lat-then-lat,lon retry that scripts/download_bdtopo_hydro.py needed
+for a different WFS server, since different servers have behaved
+differently on this before and there's no reason to assume this one
+won't too.
+
+Usage:
+    python -m scripts.download_bdcavites --check
+    python -m scripts.download_bdcavites
+"""
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import requests
+
+WFS_URL = "https://georisques.gouv.fr/services"
+TYPE_NAME = "CAVITE_LOCALISEE"
+
+# Same widened bbox as scripts/download_bdtopo_hydro.py's BBOX (updated
+# after confirmed real evidence of truncation on the original, tighter
+# box) -- keeping both scripts scoped to the same area.
+BBOX = (-0.1, 47.7, 2.1, 49.9)  # (min_lon, min_lat, max_lon, max_lat)
+
+
+def check_typename() -> bool:
+    params = {
+        "SERVICE": "WFS", "VERSION": "1.1.0", "REQUEST": "GetFeature",
+        "TYPENAME": TYPE_NAME, "MAXFEATURES": 1, "OUTPUTFORMAT": "application/json; subtype=geojson; charset=utf-8",
+    }
+    resp = requests.get(WFS_URL, params=params, timeout=30)
+    ok, detail = _parse_response(resp)
+    print(f"  {TYPE_NAME}: {'OK' if ok else 'FAILED'}")
+    if not ok:
+        print(f"    {detail}")
+    return ok
+
+
+def _parse_response(resp: "requests.Response"):
+    if resp.status_code != 200:
+        return False, f"HTTP {resp.status_code}: {resp.text[:400]}"
+    try:
+        data = resp.json()
+    except ValueError:
+        return False, f"Response was not JSON (likely a WFS ExceptionReport): {resp.text[:400]}"
+    if isinstance(data, dict) and data.get("type") == "FeatureCollection":
+        return True, ""
+    return False, f"Response was JSON but not a FeatureCollection: {str(data)[:400]}"
+
+
+def fetch_all_pages(bbox_param: str, page_size: int = 1000) -> list:
+    all_features = []
+    start_index = 0
+    while True:
+        params = {
+            "SERVICE": "WFS", "VERSION": "1.1.0", "REQUEST": "GetFeature",
+            "TYPENAME": TYPE_NAME, "BBOX": bbox_param,
+            "OUTPUTFORMAT": "application/json; subtype=geojson; charset=utf-8",
+            "MAXFEATURES": page_size, "STARTINDEX": start_index,
+        }
+        resp = requests.get(WFS_URL, params=params, timeout=60)
+        ok, detail = _parse_response(resp)
+        if not ok:
+            print(f"    ERROR at startIndex={start_index}: {detail}")
+            break
+        data = resp.json()
+        features = data.get("features", [])
+        if not features:
+            break
+        all_features.extend(features)
+        if len(features) < page_size:
+            break
+        start_index += page_size
+    return all_features
+
+
+def fetch_with_axis_retry(bbox: tuple, out_path: Path) -> None:
+    min_lon, min_lat, max_lon, max_lat = bbox
+    orderings = [
+        ("lon,lat", f"{min_lon},{min_lat},{max_lon},{max_lat},urn:ogc:def:crs:EPSG::4326"),
+        ("lat,lon", f"{min_lat},{min_lon},{max_lat},{max_lon},urn:ogc:def:crs:EPSG::4326"),
+    ]
+    features = []
+    for label, bbox_param in orderings:
+        print(f"  trying axis order {label}...")
+        features = fetch_all_pages(bbox_param)
+        if features:
+            print(f"  -> {label} worked ({len(features)} feature(s))")
+            break
+        print(f"  -> {label} returned 0 features")
+
+    geojson = {"type": "FeatureCollection", "features": features}
+    out_path.write_text(json.dumps(geojson))
+    if features:
+        print(f"Saved {len(features)} feature(s) to {out_path}")
+    else:
+        print(f"Saved an EMPTY file to {out_path} -- both axis orders returned nothing. "
+              f"Run --check first, or this area may genuinely have zero recorded cavities "
+              f"(plausible -- BDCavités coverage is built department-by-department and "
+              f"isn't uniformly complete everywhere).")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Download BDCavités for the Eure/Risle area")
+    parser.add_argument("--check", action="store_true")
+    parser.add_argument("--output-dir", type=Path, default=Path("datasets/bdcavites"))
+    args = parser.parse_args()
+
+    if args.check:
+        print("Testing typeName against the live service...")
+        ok = check_typename()
+        if not ok:
+            print("\nFailed -- the typeName or service details may have changed since this "
+                  "script was written. Fetch GetCapabilities directly to check:")
+            print(f"  {WFS_URL}?SERVICE=WFS&VERSION=1.1.0&REQUEST=GetCapabilities")
+        else:
+            print("\nOK. Re-run without --check to download.")
+        return
+
+    args.output_dir.mkdir(parents=True, exist_ok=True)
+    print("Fetching CAVITE_LOCALISEE (BDCavités)...")
+    fetch_with_axis_retry(BBOX, args.output_dir / "cavite_localisee.geojson")
+    print()
+    print("Once downloaded, cross-reference against the amont/aval bétoire stations "
+          "(H605641101 at 48.98492,0.78902 and H605641201 at 49.04707,0.79984) the same "
+          "way scripts/analyze_bdtopo_hydro.py's check_karst_near_betoire did for the "
+          "BD TOPO karst attribute -- this is a genuinely independent second check, "
+          "not a re-run of the same one.")
+
+
+if __name__ == "__main__":
+    main()

scripts/data_acquisition/download_bdcharm.py

@@ -0,0 +1,107 @@
+"""
+Downloads BD Charm-50 (BRGM's harmonized 1:50,000 geological maps) for
+the departments covering the Eure/Risle study area.
+
+CONFIRMED (via data.gouv.fr / InfoTerre): free, open (Licence Ouverte),
+no authentication -- direct per-department ZIP download from InfoTerre.
+This is a genuinely different access pattern than the WFS sources
+elsewhere in this project (BD TOPO, BDCavités): no bbox query, no axis-
+order ambiguity, just a fixed URL per department. Real, working URL
+pattern (found directly, not guessed):
+    http://infoterre.brgm.fr/telechargements/BDCharm50/GEO050K_HARM_XXX.zip
+where XXX is the 3-digit department code (e.g. 027 for Eure).
+
+NOTE: a separate, DIFFERENT distribution of this same underlying dataset
+exists that requires CIGAL network membership (seen for at least Alsace
+regional data) -- that is NOT what this script uses. This script only
+uses the free InfoTerre download confirmed via data.gouv.fr.
+
+DEPARTMENTS: 27 (Eure), 61 (Orne), 28 (Eure-et-Loir) -- 27 and 61
+confirmed directly from real INSEE codes seen in this project's own
+station_list.csv (61342, 27040, 27116, 27468); 28 included because the
+Eure's own southern tributaries (Voise, Drouette) run through Chartres/
+Dreux, unambiguously in Eure-et-Loir. Add more department codes via
+--departments if the real geographic extent turns out to need them.
+
+Usage:
+    python -m scripts.download_bdcharm50
+"""
+import argparse
+import zipfile
+from pathlib import Path
+
+import requests
+
+DEFAULT_DEPARTMENTS = ["027", "028", "061"]
+BASE_URL = "http://infoterre.brgm.fr/telechargements/BDCharm50"
+
+
+def download_department(dept: str, output_dir: Path) -> bool:
+    url = f"{BASE_URL}/GEO050K_HARM_{dept}.zip"
+    zip_path = output_dir / f"GEO050K_HARM_{dept}.zip"
+
+    print(f"  department {dept}: {url}")
+    try:
+        resp = requests.get(url, timeout=120, stream=True)
+    except requests.RequestException as e:
+        print(f"    FAILED: {e}")
+        return False
+
+    if resp.status_code != 200:
+        print(f"    FAILED: HTTP {resp.status_code}")
+        return False
+
+    content_type = resp.headers.get("Content-Type", "")
+    if "zip" not in content_type and "octet-stream" not in content_type:
+        # A 200 status with an HTML content-type here usually means an
+        # error page or a "department not available" page was returned
+        # instead of the real ZIP -- catching this explicitly rather
+        # than silently saving an HTML file with a .zip extension.
+        print(f"    WARNING: Content-Type is {content_type!r}, not zip -- "
+              f"this department's file may not exist at this URL. Saving "
+              f"anyway for inspection, but verify before trusting it.")
+
+    zip_path.write_bytes(resp.content)
+    size_kb = zip_path.stat().st_size / 1024
+    print(f"    saved {zip_path} ({size_kb:.0f} KB)")
+
+    extract_dir = output_dir / f"dept_{dept}"
+    try:
+        with zipfile.ZipFile(zip_path) as zf:
+            zf.extractall(extract_dir)
+        shp_files = list(extract_dir.rglob("*.shp"))
+        print(f"    extracted to {extract_dir} ({len(shp_files)} .shp file(s) found)")
+        return True
+    except zipfile.BadZipFile:
+        print(f"    FAILED: downloaded file is not a valid zip -- likely an error page, "
+              f"not real data. Check {zip_path} directly.")
+        return False
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Download BD Charm-50 geological maps")
+    parser.add_argument("--departments", nargs="+", default=DEFAULT_DEPARTMENTS,
+                         help="3-digit department codes, e.g. 027 028 061")
+    parser.add_argument("--output-dir", type=Path, default=Path("datasets/bdcharm50"))
+    args = parser.parse_args()
+
+    args.output_dir.mkdir(parents=True, exist_ok=True)
+    print(f"Downloading BD Charm-50 for departments: {args.departments}")
+    print()
+
+    results = {}
+    for dept in args.departments:
+        results[dept] = download_department(dept, args.output_dir)
+        print()
+
+    print("=" * 60)
+    ok = [d for d, r in results.items() if r]
+    failed = [d for d, r in results.items() if not r]
+    print(f"Succeeded: {ok}")
+    if failed:
+        print(f"Failed: {failed} -- check the URL pattern still matches by visiting "
+              f"https://infoterre.brgm.fr/page/telechargement-cartes-geologiques directly")
+
+
+if __name__ == "__main__":
+    main()

scripts/data_acquisition/download_bdtopo_hydro.py

@@ -0,0 +1,244 @@
+"""
+Download BD TOPO hydrography (troncon_hydrographique, surface_hydrographique)
+for the Eure/Risle area via IGN's Geoplateforme WFS, instead of pulling the
+whole national dataset.
+
+VERIFICATION NOTE: I confirmed the WFS endpoint itself is real and live
+(https://data.geopf.fr/wfs, WFS 2.0.0) and that a "BDTOPO_V3" namespace
+exists on it, by fetching GetCapabilities directly. I could NOT confirm
+the exact typeName for the hydrography layers within it — the full
+capabilities document is huge (thousands of layers across all IGN
+products) and got truncated before reaching them. DEFAULT_TYPENAMES
+below is my best guess based on IGN's usual naming convention, NOT a
+verified value. This script's first step (check_typenames) tests each
+name with a tiny query before attempting the real extraction, and tells
+you exactly how to find the right name yourself if my guess is wrong.
+
+Usage:
+    python download_bdtopo_hydro.py --check          # verify typeNames first
+    python download_bdtopo_hydro.py                  # then run the real extraction
+"""
+import argparse
+import sys
+from pathlib import Path
+
+import requests
+import pandas as pd
+
+WFS_URL = "https://data.geopf.fr/wfs"
+
+# Best-guess typeNames -- see VERIFICATION NOTE above. Override with
+# --troncon-typename / --surface-typename / --catchment-typename if wrong.
+# troncon/surface confirmed correct against the real service (see
+# CONFIRMED note below); catchment is still an unverified guess.
+DEFAULT_TRONCON_TYPENAME = "BDTOPO_V3:troncon_hydrographique"
+DEFAULT_SURFACE_TYPENAME = "BDTOPO_V3:surface_hydrographique"
+DEFAULT_CATCHMENT_TYPENAME = "BDTOPO_V3:bassin_versant_topographique"
+
+# CONFIRMED: both troncon_hydrographique and surface_hydrographique
+# typeNames work against the live service (verified in this project's
+# actual run: 30045 tronçons fetched successfully). bassin_versant_
+# topographique has NOT been verified the same way -- run --check
+# before trusting it.
+
+# Bounding box around the Eure/Risle stations, in WGS84 (matches the
+# lon/lat range in your real station_list.csv, with a small margin).
+BBOX = (0.3, 48.3, 1.7, 49.5)  # (min_lon, min_lat, max_lon, max_lat)
+
+
+def find_hydro_typenames(keyword: str = "hydrographique") -> list:
+    """
+    Fetch GetCapabilities and search for FeatureType <Name> entries
+    containing `keyword`. This is the fallback if DEFAULT_*_TYPENAME
+    turns out to be wrong -- run this to get the real list.
+    """
+    print(f"Fetching WFS GetCapabilities and searching for '{keyword}'...")
+    resp = requests.get(WFS_URL, params={
+        "SERVICE": "WFS", "VERSION": "2.0.0", "REQUEST": "GetCapabilities",
+    }, timeout=60)
+    resp.raise_for_status()
+
+    import re
+    names = re.findall(r"<Name>([^<]*)</Name>", resp.text)
+    matches = [n for n in names if keyword.lower() in n.lower()]
+    print(f"Found {len(matches)} matching layer(s):")
+    for m in matches:
+        print(f"  {m}")
+    return matches
+
+
+def check_typename(type_name: str) -> bool:
+    """Tiny test query (count=1, no bbox) to confirm a typeName is valid
+    before running the real extraction against it."""
+    params = {
+        "SERVICE": "WFS", "VERSION": "2.0.0", "REQUEST": "GetFeature",
+        "TYPENAMES": type_name, "COUNT": 1, "OUTPUTFORMAT": "application/json",
+    }
+    resp = requests.get(WFS_URL, params=params, timeout=30)
+    ok, error_detail = _parse_wfs_response(resp)
+    status = "OK" if ok else f"FAILED"
+    print(f"  {type_name}: {status}")
+    if not ok:
+        print(f"    {error_detail}")
+    return ok
+
+
+def _parse_wfs_response(resp: "requests.Response") -> "tuple[bool, str]":
+    """
+    Check whether a WFS response is a real FeatureCollection or an error
+    (WFS ExceptionReport, or a non-JSON/HTML error page). Returns
+    (is_valid, detail) -- detail is empty on success, otherwise a
+    human-readable explanation of what actually came back, so a failure
+    is never silently swallowed into "0 features".
+    """
+    if resp.status_code != 200:
+        return False, f"HTTP {resp.status_code}: {resp.text[:400]}"
+
+    try:
+        data = resp.json()
+    except ValueError:
+        # Not JSON at all -- almost always means an XML ExceptionReport
+        # or an HTML error page came back instead.
+        return False, f"Response was not JSON (likely a WFS ExceptionReport): {resp.text[:400]}"
+
+    if isinstance(data, dict) and data.get("type") == "FeatureCollection":
+        return True, ""
+
+    # Some WFS error responses come back as JSON but without a
+    # FeatureCollection shape (e.g. {"exceptionText": [...]})
+    return False, f"Response was JSON but not a FeatureCollection: {str(data)[:400]}"
+
+
+def fetch_features(type_name: str, bbox: tuple, out_path: Path, srs: str = "EPSG:4326") -> None:
+    """
+    GetFeature request over the given bbox, paginated via startIndex
+    since a national layer clipped to a small bbox can still exceed the
+    server's per-request feature limit.
+
+    AXIS ORDER: when BBOX specifies its CRS via the URN form
+    (urn:ogc:def:crs:EPSG::4326), the OGC spec requires lat,lon axis
+    order -- NOT the traditional lon,lat most tools use. Getting this
+    backwards doesn't error, it just silently matches zero real-world
+    features (a well-known WFS 2.0 gotcha). Rather than guess, this
+    tries lon,lat first and automatically retries with lat,lon swapped
+    if the first attempt comes back empty, so a silent axis-order bug
+    can't hide as "no data in this area" again.
+    """
+    min_lon, min_lat, max_lon, max_lat = bbox
+    orderings = [
+        ("lon,lat", f"{min_lon},{min_lat},{max_lon},{max_lat},urn:ogc:def:crs:EPSG::4326"),
+        ("lat,lon", f"{min_lat},{min_lon},{max_lat},{max_lon},urn:ogc:def:crs:EPSG::4326"),
+    ]
+
+    all_features = []
+    for label, bbox_param in orderings:
+        print(f"  trying axis order {label}...")
+        all_features = _fetch_paginated(type_name, bbox_param)
+        if all_features:
+            print(f"  -> {label} worked ({len(all_features)} feature(s)). "
+                  f"Use this axis order for future queries against this endpoint.")
+            break
+        print(f"  -> {label} returned 0 features.")
+
+    import json
+    geojson = {"type": "FeatureCollection", "features": all_features}
+    out_path.write_text(json.dumps(geojson))
+    if all_features:
+        print(f"Saved {len(all_features)} feature(s) to {out_path}")
+    else:
+        print(f"Saved an EMPTY file to {out_path} -- both axis orders returned "
+              f"nothing real. The typeName is valid (confirmed by --check), so this "
+              f"suggests the bbox itself doesn't overlap any features in this layer, "
+              f"or another parameter is off. Try a much larger bbox (e.g. all of "
+              f"France: -5,41,10,51) as a sanity check.")
+
+
+def _fetch_paginated(type_name: str, bbox_param: str) -> list:
+    """One bbox ordering's worth of paginated GetFeature calls."""
+    all_features = []
+    start_index = 0
+    page_size = 1000
+
+    while True:
+        params = {
+            "SERVICE": "WFS", "VERSION": "2.0.0", "REQUEST": "GetFeature",
+            "TYPENAMES": type_name, "BBOX": bbox_param,
+            "OUTPUTFORMAT": "application/json",
+            "COUNT": page_size, "STARTINDEX": start_index,
+        }
+        resp = requests.get(WFS_URL, params=params, timeout=60)
+        is_valid, error_detail = _parse_wfs_response(resp)
+        if not is_valid:
+            print(f"    ERROR at startIndex={start_index}: {error_detail}")
+            break
+        data = resp.json()
+        features = data.get("features", [])
+        if not features:
+            break
+        all_features.extend(features)
+        if len(features) < page_size:
+            break
+        start_index += page_size
+
+    return all_features
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Download BD TOPO hydrography for Eure/Risle")
+    parser.add_argument("--check", action="store_true",
+                         help="Only verify typeNames, don't download anything")
+    parser.add_argument("--troncon-typename", default=DEFAULT_TRONCON_TYPENAME)
+    parser.add_argument("--surface-typename", default=DEFAULT_SURFACE_TYPENAME)
+    parser.add_argument("--catchment-typename", default=DEFAULT_CATCHMENT_TYPENAME)
+    parser.add_argument("--skip-catchments", action="store_true",
+                         help="Skip bassin_versant_topographique (untested typeName)")
+    parser.add_argument("--output-dir", type=Path, default=Path("datasets/bdtopo_hydro"))
+    args = parser.parse_args()
+
+    if args.check:
+        print("=" * 70)
+        print("Testing default typeNames...")
+        print("=" * 70)
+        ok_troncon = check_typename(args.troncon_typename)
+        ok_surface = check_typename(args.surface_typename)
+        ok_catchment = args.skip_catchments or check_typename(args.catchment_typename)
+        if not (ok_troncon and ok_surface and ok_catchment):
+            print()
+            print("At least one default typeName failed. Searching capabilities "
+                  "for the real name(s) instead:")
+            find_hydro_typenames("hydrographique")
+            find_hydro_typenames("bassin_versant")
+            print()
+            print("Re-run with --troncon-typename / --surface-typename / "
+                  "--catchment-typename set to whatever the search above found, "
+                  "then --check again to confirm.")
+        else:
+            print()
+            print("All typeNames OK. Re-run without --check to download the real data.")
+        return
+
+    args.output_dir.mkdir(parents=True, exist_ok=True)
+
+    print("Fetching troncon_hydrographique (river centerline geometry + attributes)...")
+    fetch_features(args.troncon_typename, BBOX, args.output_dir / "troncon_hydrographique.geojson")
+
+    print()
+    print("Fetching surface_hydrographique (includes karst/Nature classification)...")
+    fetch_features(args.surface_typename, BBOX, args.output_dir / "surface_hydrographique.geojson")
+
+    if not args.skip_catchments:
+        print()
+        print("Fetching bassin_versant_topographique (catchment polygons)...")
+        print("NOTE: this typeName is unverified -- if it fails, run --check first "
+              "to find the real name, or pass --skip-catchments to skip it.")
+        fetch_features(args.catchment_typename, BBOX, args.output_dir / "bassin_versant_topographique.geojson")
+
+    print()
+    print("Done. Load with: BDTopoHydroLoader(data_path=...)")
+    print("To check for the karst-flagged reach near Grosley-sur-Risle/Ajou, use "
+          "loader.check_karst_near_point(lat, lon) -- that's the check that would "
+          "confirm or deny the bétoire location.")
+
+
+if __name__ == "__main__":
+    main()

scripts/data_acquisition/download_c3s_seasonal.py

@@ -0,0 +1,181 @@
+"""
+Downloads real seasonal forecast data from Copernicus's C3S service --
+genuine physics-based forecasts from operational centers (ECMWF's SEAS5
+by default), not our own statistical extrapolation from ERA5 history.
+Same account/library (cdsapi) already used for download_era5_full.py.
+
+CONFIRMED (via ECMWF/Copernicus documentation, not guessed): dataset
+'seasonal-original-single-levels' for daily-resolution data, real
+request parameters originating_centre/system/variable/year/month/
+leadtime_hour/area/format. GRIB is the CDS default format; netCDF
+("experimental" per ECMWF's own docs) must be requested explicitly to
+match this project's existing xarray-based pipeline (SAFRANLoader etc.)
+rather than adding a new GRIB-reading dependency.
+
+NOT independently confirmed, flagged rather than assumed:
+  - The exact 'system' version number for ECMWF SEAS5 -- these get
+    revised over time by the provider. Run --check first; if it fails,
+    check the real current value at
+    https://cds.climate.copernicus.eu/datasets/seasonal-original-single-levels
+  - Whether a separate monthly-statistics dataset (rather than daily
+    with an hourly leadtime) is the better fit here -- --frequency lets
+    you try both; daily-with-leadtime_hour is what's directly confirmed
+    in the docs, so it's the default.
+
+AREA / AXIS ORDER: the CDS 'area' parameter uses [North, West, South,
+East] order -- confirmed different from this project's own
+(min_lon, min_lat, max_lon, max_lat) bbox convention used everywhere
+else (download_bdtopo_hydro.py, download_bdcavites.py). Converted
+explicitly in build_area_param below rather than passed through
+unchanged -- getting an axis order wrong has silently broken a request
+in this project before (BD TOPO's WFS), so this is checked directly,
+not assumed compatible.
+
+Two request types, genuinely different, both needed:
+  - hindcasts (1993-2016): historical reforecasts, needed to bias-
+    correct/calibrate the real-time forecast against local climatology
+    the same way climate_climatology.py already does for ERA5.
+  - real-time forecasts (2017+): the actual current forecast to use at
+    inference time.
+
+Usage:
+    python -m scripts.download_c3s_seasonal --check
+    python -m scripts.download_c3s_seasonal --mode hindcast --month 1
+    python -m scripts.download_c3s_seasonal --mode forecast --year 2026 --month 8
+"""
+import argparse
+from pathlib import Path
+
+# Matches download_bdtopo_hydro.py's widened bbox, same study area.
+BBOX = (-0.1, 47.7, 2.1, 49.9)  # (min_lon, min_lat, max_lon, max_lat)
+
+DATASET = "seasonal-original-single-levels"
+DEFAULT_ORIGINATING_CENTRE = "ecmwf"
+DEFAULT_SYSTEM = "51"  # SEAS5 -- NOT independently confirmed, see module docstring
+
+# ERA5-style variable names, matching this project's existing SAFRANLoader
+# VAR_MAP naming convention where the CDS names line up (t2m, tp) --
+# NOT independently confirmed identical for the seasonal dataset
+# specifically; run --check before trusting this list.
+DEFAULT_VARIABLES = ["2m_temperature", "total_precipitation"]
+
+
+def build_area_param(bbox: tuple) -> list:
+    """
+    CDS 'area' is [North, West, South, East] -- confirmed different
+    from this project's own (min_lon, min_lat, max_lon, max_lat)
+    convention. Converts explicitly rather than passing bbox through
+    unchanged.
+    """
+    min_lon, min_lat, max_lon, max_lat = bbox
+    return [max_lat, min_lon, min_lat, max_lon]  # [North, West, South, East]
+
+
+def build_hindcast_request(month: int, variables: list, system: str, originating_centre: str) -> dict:
+    """
+    One request per initialization MONTH, covering all hindcast years
+    at once -- ECMWF's own efficiency guidance (confirmed in their
+    documentation) is that this is much more efficient than looping
+    per-year, since a single month across many years reuses the same
+    underlying data partition.
+    """
+    return {
+        "originating_centre": originating_centre,
+        "system": system,
+        "variable": variables,
+        "year": [str(y) for y in range(1993, 2017)],
+        "month": [f"{month:02d}"],
+        "day": ["01"],
+        "leadtime_hour": [str(h) for h in range(24, 24 * 186, 24)],  # daily steps out to ~6 months
+        "area": build_area_param(BBOX),
+        "format": "netcdf",
+    }
+
+
+def build_forecast_request(year: int, month: int, variables: list, system: str, originating_centre: str) -> dict:
+    """One real-time forecast initialization (a specific year+month), same variables/area/format as hindcasts."""
+    return {
+        "originating_centre": originating_centre,
+        "system": system,
+        "variable": variables,
+        "year": [str(year)],
+        "month": [f"{month:02d}"],
+        "day": ["01"],
+        "leadtime_hour": [str(h) for h in range(24, 24 * 186, 24)],
+        "area": build_area_param(BBOX),
+        "format": "netcdf",
+    }
+
+
+def check_access(originating_centre: str, system: str) -> bool:
+    """Small real request (single variable, single hindcast month, short
+    leadtime range) to validate credentials/dataset/system/variable
+    names actually work before committing to a full download."""
+    import cdsapi
+
+    client = cdsapi.Client()
+    request = {
+        "originating_centre": originating_centre,
+        "system": system,
+        "variable": ["2m_temperature"],
+        "year": ["2015"],
+        "month": ["01"],
+        "day": ["01"],
+        "leadtime_hour": ["24", "48"],
+        "area": build_area_param(BBOX),
+        "format": "netcdf",
+    }
+    print(f"Testing {DATASET} with originating_centre={originating_centre!r}, system={system!r}...")
+    try:
+        client.retrieve(DATASET, request, "/tmp/c3s_check.nc")
+        print("OK -- request succeeded, real data downloaded to /tmp/c3s_check.nc")
+        return True
+    except Exception as e:
+        print(f"FAILED: {e}")
+        print(f"Check the real current dataset/parameter values at "
+              f"https://cds.climate.copernicus.eu/datasets/{DATASET}")
+        return False
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Download C3S seasonal forecast data")
+    parser.add_argument("--check", action="store_true")
+    parser.add_argument("--mode", choices=["hindcast", "forecast"], default="hindcast")
+    parser.add_argument("--month", type=int, required=False, help="Initialization month (1-12)")
+    parser.add_argument("--year", type=int, required=False, help="Forecast year (--mode forecast only)")
+    parser.add_argument("--originating-centre", type=str, default=DEFAULT_ORIGINATING_CENTRE)
+    parser.add_argument("--system", type=str, default=DEFAULT_SYSTEM)
+    parser.add_argument("--variables", type=str, nargs="+", default=DEFAULT_VARIABLES)
+    parser.add_argument("--output-dir", type=Path, default=Path("datasets/c3s_seasonal"))
+    args = parser.parse_args()
+
+    if args.check:
+        check_access(args.originating_centre, args.system)
+        return
+
+    if args.month is None:
+        print("--month is required (1-12) unless using --check")
+        return
+
+    import cdsapi
+    client = cdsapi.Client()
+    args.output_dir.mkdir(parents=True, exist_ok=True)
+
+    if args.mode == "hindcast":
+        request = build_hindcast_request(args.month, args.variables, args.system, args.originating_centre)
+        out_path = args.output_dir / f"hindcast_month{args.month:02d}.nc"
+    else:
+        if args.year is None:
+            print("--year is required for --mode forecast")
+            return
+        request = build_forecast_request(args.year, args.month, args.variables, args.system, args.originating_centre)
+        out_path = args.output_dir / f"forecast_{args.year}_{args.month:02d}.nc"
+
+    print(f"Requesting {DATASET} ({args.mode}, month={args.month})...")
+    print("This can take a while -- CDS queues large seasonal forecast requests.")
+    client.retrieve(DATASET, request, str(out_path))
+    print(f"Saved to {out_path}")
+
+
+if __name__ == "__main__":
+    main()

scripts/data_acquisition/download_catchment.py

@@ -0,0 +1,114 @@
+"""
+Download catchment (drainage basin) area for all stations from Hub'Eau's
+own hydrometrie referentiel — the same API download_hubeau.py already
+uses, just a different endpoint.
+
+Catchment area is NOT on the station referentiel directly; it lives on
+the SITE referentiel (`surface_bv`, "Superficie du BV en km2"). A site
+can have multiple stations, so this does two passes:
+  1. referentiel/stations -> get each station's code_site
+  2. referentiel/sites     -> get surface_bv for those code_site values
+  3. join back onto station_code
+
+This gives real drainage-area data usable for area-ratio discharge
+scaling between gauges on the same river (Q_ungauged ~= Q_gauged *
+(area_ungauged / area_gauged)) — a physically grounded alternative to
+naive geographic proximity interpolation.
+"""
+import requests
+import pandas as pd
+from pathlib import Path
+
+BASE_URL = "https://hubeau.eaufrance.fr/api/v2/hydrometrie"
+OUTPUT_DIR = Path("datasets")
+OUTPUT_DIR.mkdir(exist_ok=True)
+
+stations_df = pd.read_csv("datasets/station_list.csv")
+station_codes = stations_df["station_code"].tolist()
+
+print(f"Fetching catchment area for {len(station_codes)} stations...")
+print()
+
+
+def fetch_all(endpoint: str, params: dict) -> list:
+    """Fetch every page from a Hub'Eau referentiel endpoint (cursor pagination)."""
+    all_data = []
+    cursor = ""
+    while True:
+        query = dict(params, cursor=cursor, size=1000, format="json")
+        response = requests.get(f"{BASE_URL}/{endpoint}", params=query, timeout=30)
+        if response.status_code not in (200, 206):
+            print(f"  Error {response.status_code}: {response.text[:200]}")
+            break
+        data = response.json()
+        results = data.get("data", [])
+        if not results:
+            break
+        all_data.extend(results)
+        next_url = data.get("next")
+        if not next_url:
+            break
+        if "cursor=" in next_url:
+            cursor = next_url.split("cursor=")[1].split("&")[0]
+        else:
+            break
+    return all_data
+
+
+# --- Step 1: station -> code_site -----------------------------------------
+print("=" * 80)
+print("STEP 1: Looking up code_site for each station")
+print("=" * 80)
+
+station_to_site = {}
+# code_station accepts up to 100 comma-separated codes per request
+for i in range(0, len(station_codes), 100):
+    batch = station_codes[i:i + 100]
+    results = fetch_all("referentiel/stations", {"code_station": ",".join(batch)})
+    for r in results:
+        station_to_site[r["code_station"]] = r.get("code_site")
+        print(f"  {r['code_station']} -> site {r.get('code_site')}")
+
+missing = set(station_codes) - set(station_to_site)
+if missing:
+    print(f"\n  Warning: {len(missing)} station(s) not found in referentiel/stations: {missing}")
+
+# --- Step 2: code_site -> surface_bv ---------------------------------------
+print()
+print("=" * 80)
+print("STEP 2: Fetching surface_bv (catchment area) for each site")
+print("=" * 80)
+
+site_codes = sorted(set(s for s in station_to_site.values() if s))
+site_to_area = {}
+for i in range(0, len(site_codes), 100):
+    batch = site_codes[i:i + 100]
+    results = fetch_all("referentiel/sites", {"code_site": ",".join(batch)})
+    for r in results:
+        area = r.get("surface_bv")
+        site_to_area[r["code_site"]] = area
+        print(f"  site {r['code_site']} ({r.get('libelle_site', '?')}): "
+              f"{area if area is not None else 'no data'} km²")
+
+# --- Step 3: join back onto station_code -----------------------------------
+rows = []
+for code in station_codes:
+    site = station_to_site.get(code)
+    area = site_to_area.get(site) if site else None
+    rows.append({"station_code": code, "code_site": site, "catchment_area_km2": area})
+
+result_df = pd.DataFrame(rows)
+output_file = OUTPUT_DIR / "catchment_area.csv"
+result_df.to_csv(output_file, index=False)
+
+print()
+print("=" * 80)
+print("DONE")
+print("=" * 80)
+n_ok = result_df["catchment_area_km2"].notna().sum()
+print(f"Catchment area found for {n_ok}/{len(result_df)} stations")
+print(f"Saved to: {output_file}")
+if n_ok < len(result_df):
+    missing_codes = result_df[result_df["catchment_area_km2"].isna()]["station_code"].tolist()
+    print(f"\nNo area found for: {missing_codes}")
+    print("(Hub'Eau doesn't publish surface_bv for every site — some are genuinely blank.)")

scripts/data_acquisition/download_elevation.py

@@ -0,0 +1,67 @@
+"""Download elevation data for all 27 stations using Open Topo Data API."""
+import requests
+import pandas as pd
+import time
+from pathlib import Path
+
+# Load stations
+stations = pd.read_csv('datasets/station_list.csv')
+
+print(f"Downloading elevation for {len(stations)} stations...")
+
+elevations = []
+
+for idx, row in stations.iterrows():
+    station_code = row['station_code']
+    lat = row['lat']
+    lon = row['lon']
+
+    # Query Open Topo Data API
+    url = f"https://api.opentopodata.org/v1/eudem25m?locations={lat},{lon}"
+
+    try:
+        response = requests.get(url, timeout=10)
+        if response.status_code == 200:
+            data = response.json()
+            elevation = data['results'][0]['elevation']
+            elevations.append({
+                'station_code': station_code,
+                'station_name': row['station_name'],
+                'latitude': lat,
+                'longitude': lon,
+                'elevation_m': elevation,
+                'data_source': 'EU-DEM 25m (Open Topo Data)'
+            })
+            print(f"✓ {station_code}: {elevation:.1f} m")
+        else:
+            print(f"✗ {station_code}: API error {response.status_code}")
+            elevations.append({
+                'station_code': station_code,
+                'station_name': row['station_name'],
+                'latitude': lat,
+                'longitude': lon,
+                'elevation_m': None,
+                'data_source': 'Failed'
+            })
+    except Exception as e:
+        print(f"✗ {station_code}: {e}")
+        elevations.append({
+            'station_code': station_code,
+            'station_name': row['station_name'],
+            'latitude': lat,
+            'longitude': lon,
+            'elevation_m': None,
+            'data_source': 'Failed'
+        })
+
+    # Rate limiting
+    time.sleep(3)
+
+# Save
+df_elevation = pd.DataFrame(elevations)
+output_file = Path('datasets/station_elevations.csv')
+df_elevation.to_csv(output_file, index=False)
+
+print(f"\n✓ Saved to: {output_file}")
+print(f"✓ Success: {df_elevation['elevation_m'].notna().sum()}/{len(df_elevation)} stations")
+print(f"\nElevation range: {df_elevation['elevation_m'].min():.1f} - {df_elevation['elevation_m'].max():.1f} m")

scripts/data_acquisition/download_era5_full.py

@@ -0,0 +1,180 @@
+"""
+Download full ERA5 dataset (1960-2026) for all 27 stations.
+Downloads year by year with separate requests for instantaneous vs accumulated variables.
+
+NOTE: ERA5 separates instantaneous (temperature, wind) from accumulated
+(precipitation, evaporation, radiation) variables. They must be requested separately.
+"""
+import cdsapi
+import pandas as pd
+import xarray as xr
+import zipfile
+import shutil
+from pathlib import Path
+
+# Load station coordinates
+stations = pd.read_csv('datasets/station_list.csv')
+lat_min = stations['lat'].min() - 0.1
+lat_max = stations['lat'].max() + 0.1
+lon_min = stations['lon'].min() - 0.1
+lon_max = stations['lon'].max() + 0.1
+
+print("="*80)
+print("ERA5 FULL DOWNLOAD (1960-2026)")
+print("="*80)
+print(f"Study area: [{lat_min:.2f}, {lon_min:.2f}] to [{lat_max:.2f}, {lon_max:.2f}]")
+print(f"Years: 1960-2026 (67 years)")
+print(f"Output: datasets/safran/")
+print("="*80)
+
+# Split variables by type (instantaneous vs accumulated)
+instantaneous_vars = [
+    '2m_temperature',               # T_Q
+    '10m_u_component_of_wind',      # FF_Q
+    '10m_v_component_of_wind',      # FF_Q
+]
+
+accumulated_vars = [
+    'total_precipitation',                 # PRELIQ_Q
+    'potential_evaporation',               # ETP_Q
+    'surface_solar_radiation_downwards',   # DLI_Q / SSI_Q
+    'snowfall',                            # PRENEI_Q
+    'runoff',                              # RUNC_Q
+]
+
+def extract_netcdf(zip_file):
+    """Extract NetCDF from ZIP archive."""
+    if zipfile.is_zipfile(zip_file):
+        with zipfile.ZipFile(zip_file, 'r') as zip_ref:
+            # Find all .nc files in the zip
+            nc_files = [f for f in zip_ref.namelist() if f.endswith('.nc')]
+            extracted_files = []
+            for nc_file in nc_files:
+                temp_file = zip_file.parent / f'temp_{nc_file}'
+                with zip_ref.open(nc_file) as source:
+                    with open(temp_file, 'wb') as target:
+                        shutil.copyfileobj(source, target)
+                extracted_files.append(temp_file)
+        zip_file.unlink()
+        return extracted_files
+    return [zip_file]
+
+def merge_datasets(instant_file, accum_file, output_file):
+    """Merge instantaneous and accumulated variable datasets."""
+    ds_instant = xr.open_dataset(instant_file)
+    ds_accum = xr.open_dataset(accum_file)
+
+    # Merge datasets
+    ds_merged = xr.merge([ds_instant, ds_accum])
+    ds_merged.to_netcdf(output_file)
+
+    ds_instant.close()
+    ds_accum.close()
+    instant_file.unlink()
+    accum_file.unlink()
+
+c = cdsapi.Client()
+output_dir = Path('datasets/safran')
+output_dir.mkdir(exist_ok=True)
+
+# Download year by year (1960-2026)
+years = list(range(1960, 2027))  # 1960 to 2026 inclusive
+failed_years = []
+
+for year in years:
+    output_file = output_dir / f'era5_{year}.nc'
+
+    # Skip if already exists and contains all 8 variables
+    if output_file.exists():
+        try:
+            ds = xr.open_dataset(output_file)
+            if len(ds.data_vars) >= 8:
+                print(f"✓ {year} - Already downloaded with all variables, skipping")
+                ds.close()
+                continue
+            else:
+                print(f"⚠ {year} - Incomplete ({len(ds.data_vars)} vars), re-downloading")
+                ds.close()
+                output_file.unlink()
+        except:
+            output_file.unlink()
+
+    print(f"\nDownloading {year}...")
+
+    instant_file = output_dir / f'era5_{year}_instant.nc'
+    accum_file = output_dir / f'era5_{year}_accum.nc'
+
+    try:
+        # Download instantaneous variables
+        print(f"  → Instantaneous variables...")
+        c.retrieve(
+            'reanalysis-era5-single-levels',
+            {
+                'product_type': 'reanalysis',
+                'format': 'netcdf',
+                'variable': instantaneous_vars,
+                'year': str(year),
+                'month': [f'{m:02d}' for m in range(1, 13)],
+                'day': [f'{d:02d}' for d in range(1, 32)],
+                'time': '12:00',
+                'area': [lat_max, lon_min, lat_min, lon_max],
+            },
+            str(instant_file)
+        )
+
+        # Extract if ZIP
+        extracted = extract_netcdf(instant_file)
+        if len(extracted) > 0:
+            instant_file = extracted[0]
+
+        # Download accumulated variables
+        print(f"  → Accumulated variables...")
+        c.retrieve(
+            'reanalysis-era5-single-levels',
+            {
+                'product_type': 'reanalysis',
+                'format': 'netcdf',
+                'variable': accumulated_vars,
+                'year': str(year),
+                'month': [f'{m:02d}' for m in range(1, 13)],
+                'day': [f'{d:02d}' for d in range(1, 32)],
+                'time': '12:00',
+                'area': [lat_max, lon_min, lat_min, lon_max],
+            },
+            str(accum_file)
+        )
+
+        # Extract if ZIP
+        extracted = extract_netcdf(accum_file)
+        if len(extracted) > 0:
+            accum_file = extracted[0]
+
+        # Merge both datasets
+        print(f"  → Merging datasets...")
+        merge_datasets(instant_file, accum_file, output_file)
+
+        size_kb = output_file.stat().st_size / 1024
+        print(f"✓ {year} - Downloaded ({size_kb:.1f} KB)")
+
+    except Exception as e:
+        print(f"✗ {year} - Failed: {e}")
+        failed_years.append(year)
+        # Cleanup partial files
+        for f in [instant_file, accum_file]:
+            if f.exists():
+                f.unlink()
+        continue
+
+print("\n" + "="*80)
+print("DOWNLOAD COMPLETE")
+print("="*80)
+print(f"Successful: {len(years) - len(failed_years)}/{len(years)} years")
+
+if failed_years:
+    print(f"\nFailed years: {failed_years}")
+    print("You can re-run this script to retry failed downloads")
+else:
+    print("\n✓ All years downloaded successfully!")
+
+print(f"\nFiles saved to: {output_dir}")
+print("Total files:", len(list(output_dir.glob('era5_*.nc'))))

scripts/data_acquisition/download_era5_sample.py

@@ -0,0 +1,44 @@
+"""Download ERA5 sample (Jan 2020) to test setup."""
+import cdsapi
+import pandas as pd
+from pathlib import Path
+
+# Load station coordinates for bounding box
+stations = pd.read_csv('datasets/station_list.csv')
+lat_min = stations['lat'].min() - 0.1
+lat_max = stations['lat'].max() + 0.1
+lon_min = stations['lon'].min() - 0.1
+lon_max = stations['lon'].max() + 0.1
+
+print(f"Study area: [{lat_min:.2f}, {lon_min:.2f}] to [{lat_max:.2f}, {lon_max:.2f}]")
+print("Downloading ERA5 sample: January 2020...")
+
+c = cdsapi.Client()
+
+output_file = Path('datasets/safran/era5_2020_jan.nc')
+
+# Download sample month
+c.retrieve(
+    'reanalysis-era5-single-levels',
+    {
+        'product_type': 'reanalysis',
+        'format': 'netcdf',
+        'variable': [
+            '2m_temperature',
+            'total_precipitation',
+            'potential_evaporation',
+            'surface_solar_radiation_downwards',
+            '10m_u_component_of_wind',
+            '10m_v_component_of_wind',
+        ],
+        'year': '2020',
+        'month': '01',
+        'day': [f'{d:02d}' for d in range(1, 32)],
+        'time': '12:00',
+        'area': [lat_max, lon_min, lat_min, lon_max],
+    },
+    str(output_file)
+)
+
+print(f"✓ Downloaded: {output_file}")
+print(f"✓ Size: {output_file.stat().st_size / 1024 / 1024:.1f} MB")

scripts/data_acquisition/download_hubeau.py

@@ -0,0 +1,162 @@
+"""
+Download hydrometric data from Hub'Eau API v2.
+Downloads QmJ (daily discharge), HIJ (daily water level) for all 27 stations.
+"""
+import requests
+import pandas as pd
+from pathlib import Path
+from tqdm import tqdm
+import time
+
+# Configuration
+OUTPUT_DIR = Path("datasets/hydrometric")
+OUTPUT_DIR.mkdir(exist_ok=True)
+
+BASE_URL = "https://hubeau.eaufrance.fr/api/v2/hydrometrie"
+
+# Load stations
+stations_df = pd.read_csv("datasets/station_list.csv")
+station_codes = stations_df["station_code"].tolist()
+
+print(f"Downloading hydrometric data for {len(station_codes)} stations...")
+print(f"Output: {OUTPUT_DIR}")
+print()
+
+def download_observations(station_code, grandeur_hydro="Q", max_results=100000):
+    """
+    Download observations for a station.
+
+    Args:
+        station_code: Station code (e.g., H602021010)
+        grandeur_hydro: H (water level) or Q (discharge)
+        max_results: Maximum results to fetch
+
+    Returns:
+        DataFrame with observations
+    """
+    url = f"{BASE_URL}/obs_elab"
+
+    all_data = []
+    cursor = ""
+    page = 1
+
+    while len(all_data) < max_results:
+        params = {
+            "code_entite": station_code,
+            "grandeur_hydro": grandeur_hydro,
+            "size": 20000,  # Max per request
+            "format": "json",
+            "cursor": cursor
+        }
+
+        try:
+            response = requests.get(url, params=params, timeout=30)
+
+            if response.status_code == 200:
+                data = response.json()
+                results = data.get("data", [])
+
+                if not results:
+                    break
+
+                all_data.extend(results)
+
+                # Check for next page
+                next_url = data.get("next")
+                if not next_url or len(results) < 20000:
+                    break
+
+                # Extract cursor from next URL
+                if "cursor=" in next_url:
+                    cursor = next_url.split("cursor=")[1].split("&")[0]
+                else:
+                    break
+
+                page += 1
+                time.sleep(0.1)  # Rate limiting
+
+            else:
+                print(f"  Error {response.status_code}")
+                break
+
+        except Exception as e:
+            print(f"  Exception: {e}")
+            break
+
+    if all_data:
+        return pd.DataFrame(all_data)
+    else:
+        return pd.DataFrame()
+
+
+# Download discharge (Q) for all stations
+print("="*80)
+print("DOWNLOADING DISCHARGE (Q)")
+print("="*80)
+
+discharge_data = []
+
+for station_code in tqdm(station_codes, desc="Discharge"):
+    df = download_observations(station_code, grandeur_hydro="Q")
+
+    if not df.empty:
+        df["station_code"] = station_code
+        discharge_data.append(df)
+        tqdm.write(f"✓ {station_code}: {len(df)} observations")
+    else:
+        tqdm.write(f"✗ {station_code}: No data")
+
+    time.sleep(0.2)
+
+if discharge_data:
+    discharge_df = pd.concat(discharge_data, ignore_index=True)
+
+    # Save
+    discharge_df.to_csv(OUTPUT_DIR / "discharge_observations.csv", index=False)
+    discharge_df.to_json(OUTPUT_DIR / "discharge_observations.json", orient="records", indent=2)
+
+    print(f"\n✓ Discharge: {len(discharge_df)} total observations")
+    print(f"  Stations: {discharge_df['station_code'].nunique()}")
+    print(f"  Date range: {discharge_df['date_obs_elab'].min()} to {discharge_df['date_obs_elab'].max()}")
+
+
+# Download water level (H) for all stations
+print("\n" + "="*80)
+print("DOWNLOADING WATER LEVEL (H)")
+print("="*80)
+
+waterlevel_data = []
+
+for station_code in tqdm(station_codes, desc="Water Level"):
+    df = download_observations(station_code, grandeur_hydro="H")
+
+    if not df.empty:
+        df["station_code"] = station_code
+        waterlevel_data.append(df)
+        tqdm.write(f"✓ {station_code}: {len(df)} observations")
+    else:
+        tqdm.write(f"✗ {station_code}: No data")
+
+    time.sleep(0.2)
+
+if waterlevel_data:
+    waterlevel_df = pd.concat(waterlevel_data, ignore_index=True)
+
+    # Save
+    waterlevel_df.to_csv(OUTPUT_DIR / "waterlevel_observations.csv", index=False)
+    waterlevel_df.to_json(OUTPUT_DIR / "waterlevel_observations.json", orient="records", indent=2)
+
+    print(f"\n✓ Water level: {len(waterlevel_df)} total observations")
+    print(f"  Stations: {waterlevel_df['station_code'].nunique()}")
+    print(f"  Date range: {waterlevel_df['date_obs_elab'].min()} to {waterlevel_df['date_obs_elab'].max()}")
+
+
+# Summary
+print("\n" + "="*80)
+print("DOWNLOAD COMPLETE")
+print("="*80)
+print(f"Files saved to: {OUTPUT_DIR}")
+print(f"\nFiles created:")
+for f in OUTPUT_DIR.glob("*"):
+    size_mb = f.stat().st_size / 1024 / 1024
+    print(f"  - {f.name} ({size_mb:.1f} MB)")

scripts/data_acquisition/extract_era5.py

@@ -0,0 +1,57 @@
+"""
+Extract NetCDF files from ERA5 ZIP archives.
+CDS API downloads NetCDF data as compressed ZIP files.
+"""
+import zipfile
+from pathlib import Path
+import shutil
+
+safran_dir = Path('datasets/safran')
+
+print("=" * 80)
+print("EXTRACTING ERA5 NETCDF FILES FROM ZIP ARCHIVES")
+print("=" * 80)
+
+# Find all .nc files that are actually ZIP archives
+nc_files = list(safran_dir.glob('era5_*.nc'))
+extracted = 0
+skipped = 0
+
+for nc_file in sorted(nc_files):
+    # Check if it's a ZIP file
+    try:
+        with zipfile.ZipFile(nc_file, 'r') as zip_ref:
+            # It's a ZIP file - extract it
+            zip_contents = zip_ref.namelist()
+
+            # Find the actual NetCDF file inside (usually data.nc or similar)
+            actual_nc = [f for f in zip_contents if f.endswith('.nc')][0]
+
+            # Extract to temporary location
+            temp_file = safran_dir / f'temp_{nc_file.name}'
+            with zip_ref.open(actual_nc) as source:
+                with open(temp_file, 'wb') as target:
+                    shutil.copyfileobj(source, target)
+
+            # Replace the ZIP with the extracted NetCDF
+            nc_file.unlink()
+            temp_file.rename(nc_file)
+
+            size_kb = nc_file.stat().st_size / 1024
+            print(f"✓ Extracted {nc_file.name} ({size_kb:.1f} KB)")
+            extracted += 1
+
+    except zipfile.BadZipFile:
+        # Not a ZIP file - it's already a proper NetCDF, skip
+        size_kb = nc_file.stat().st_size / 1024
+        print(f"  {nc_file.name} - Already extracted ({size_kb:.1f} KB)")
+        skipped += 1
+    except Exception as e:
+        print(f"✗ Failed to extract {nc_file.name}: {e}")
+
+print("\n" + "=" * 80)
+print("EXTRACTION COMPLETE")
+print("=" * 80)
+print(f"Extracted: {extracted} files")
+print(f"Already extracted: {skipped} files")
+print(f"Total NetCDF files: {len(nc_files)}")

scripts/data_acquisition/fetch_ecmwf_forecast.py

@@ -0,0 +1,152 @@
+"""
+Fetches real, physics-based short-to-medium-range forecast data from
+Open-Meteo's dedicated ECMWF endpoint -- built specifically for genuine
+flood early-warning lead time, which (per the recent design discussion)
+structurally requires a real precipitation forecast, not just discharge
+history extrapolated forward.
+
+CONFIRMED real API details (not guessed): base endpoint
+https://api.open-meteo.com/v1/ecmwf, HTTP GET, no authentication, CC BY
+4.0 licence, up to 10 real forecast days. Also confirmed to exist (not
+yet used here): an archived-individual-model-run-by-init-time feature
+explicitly described by Open-Meteo as built for bias-correction
+pipelines without look-ahead leakage -- exactly what a later step would
+need to calibrate this forecast against our own real climatology (see
+climate_climatology.py). The exact endpoint for that archive wasn't
+directly confirmed in this pass -- flagged for a follow-up check, not
+guessed at here.
+
+Usage:
+    python -m scripts.fetch_ecmwf_forecast --check
+    python -m scripts.fetch_ecmwf_forecast --stations-path datasets/station_elevations.csv
+"""
+import argparse
+from pathlib import Path
+
+import pandas as pd
+import requests
+
+BASE_URL = "https://api.open-meteo.com/v1/ecmwf"
+
+# Daily aggregates, matching this project's existing daily-resolution
+# pipeline convention (ERA5 climatology etc.) rather than pulling hourly
+# data that would need its own separate aggregation step.
+DAILY_VARIABLES = [
+    "precipitation_sum", "temperature_2m_max", "temperature_2m_min",
+    "wind_speed_10m_max", "shortwave_radiation_sum", "et0_fao_evapotranspiration",
+]
+
+
+def check_access() -> bool:
+    """Single real request against a real coordinate in the study area
+    (matches H602021010's real location) to confirm the endpoint and
+    variable names actually work before looping over every station."""
+    params = {
+        "latitude": 48.748705218, "longitude": 0.58156195,
+        "daily": ",".join(DAILY_VARIABLES), "forecast_days": 5,
+        "timezone": "Europe/Paris",
+    }
+    print(f"Testing {BASE_URL} with a real study-area coordinate...")
+    try:
+        resp = requests.get(BASE_URL, params=params, timeout=30)
+        resp.raise_for_status()
+        data = resp.json()
+    except Exception as e:
+        print(f"FAILED: {e}")
+        return False
+
+    if "daily" not in data:
+        print(f"FAILED: response has no 'daily' key. Full response: {data}")
+        return False
+
+    print("OK -- real forecast returned:")
+    for var in DAILY_VARIABLES:
+        if var in data["daily"]:
+            print(f"  {var}: {data['daily'][var][:3]}... ({len(data['daily'][var])} real day(s))")
+        else:
+            print(f"  WARNING: '{var}' not found in response -- variable name may be wrong. "
+                  f"Real keys returned: {list(data['daily'].keys())}")
+    return True
+
+
+def fetch_forecast(lat: float, lon: float, forecast_days: int = 10, max_retries: int = 3) -> pd.DataFrame:
+    """
+    Retries on read timeout -- confirmed as a real, not hypothetical,
+    intermittent failure mode against the live API: 2 of 27 real
+    stations hit a 30s read timeout on an otherwise-clean run, while
+    the other 25 succeeded immediately. A short exponential backoff
+    handles this automatically rather than requiring a manual re-run
+    for whichever stations happen to be unlucky that run.
+    """
+    import time
+
+    params = {
+        "latitude": lat, "longitude": lon,
+        "daily": ",".join(DAILY_VARIABLES), "forecast_days": forecast_days,
+        "timezone": "Europe/Paris",
+    }
+    last_error = None
+    for attempt in range(max_retries):
+        try:
+            resp = requests.get(BASE_URL, params=params, timeout=30)
+            resp.raise_for_status()
+            data = resp.json()
+            break
+        except requests.exceptions.RequestException as e:
+            last_error = e
+            if attempt < max_retries - 1:
+                wait = 2 ** attempt  # 1s, 2s, 4s
+                print(f"    attempt {attempt + 1}/{max_retries} failed ({e}), retrying in {wait}s...")
+                time.sleep(wait)
+    else:
+        raise last_error
+
+    if "daily" not in data:
+        raise ValueError(f"No 'daily' data in response for ({lat}, {lon}): {data}")
+
+    df = pd.DataFrame(data["daily"])
+    df["latitude"] = lat
+    df["longitude"] = lon
+    return df
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Fetch real ECMWF forecast data from Open-Meteo")
+    parser.add_argument("--check", action="store_true")
+    parser.add_argument("--stations-path", type=Path, default=Path("datasets/station_elevations.csv"))
+    parser.add_argument("--forecast-days", type=int, default=10)
+    parser.add_argument("--output", type=Path, default=Path("datasets/ecmwf_forecast.csv"))
+    args = parser.parse_args()
+
+    if args.check:
+        check_access()
+        return
+
+    stations = pd.read_csv(args.stations_path)
+    lat_col = "latitude" if "latitude" in stations.columns else "lat"
+    lon_col = "longitude" if "longitude" in stations.columns else "lon"
+
+    all_dfs = []
+    for _, row in stations.iterrows():
+        code = row.get("station_code", f"{row[lat_col]:.3f}_{row[lon_col]:.3f}")
+        print(f"Fetching real forecast for {code}...")
+        try:
+            df = fetch_forecast(row[lat_col], row[lon_col], args.forecast_days)
+            df["station_code"] = code
+            all_dfs.append(df)
+        except Exception as e:
+            print(f"  FAILED for {code}: {e}")
+
+    if not all_dfs:
+        print("No real forecast data fetched at all -- check connectivity, or run --check first.")
+        return
+
+    combined = pd.concat(all_dfs, ignore_index=True)
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    combined.to_csv(args.output, index=False)
+    print(f"\nSaved real forecast data for {combined['station_code'].nunique()} station(s), "
+          f"{args.forecast_days} real day(s) each, to {args.output}")
+
+
+if __name__ == "__main__":
+    main()

scripts/data_acquisition/fetch_idpr_brgm.py

@@ -0,0 +1,144 @@
+"""
+Fetches fresh IDPR (Indice de Développement et de Persistance des
+Réseaux) values directly from BRGM's live geoservice, replacing/
+supplementing the manually-uploaded idpr.csv.
+
+CONFIRMED (fetched GetCapabilities directly): endpoint
+http://geoservices.brgm.fr/geologie, WMS 1.3.0, live and responding.
+IDPR is raster/grid data at five resolutions (IDPR_50M down to
+IDPR_5000M) -- not a vector feature type, so WFS GetFeature (the
+pattern used everywhere else in this project) doesn't apply. The
+correct WMS operation for extracting a value at a specific point from a
+raster layer is GetFeatureInfo: request a small map image centered on
+the point, then ask "what's the value at this pixel."
+
+This queries ONE point at a time (GetFeatureInfo has no bulk/vectorized
+equivalent the way BD TOPO's WFS BBOX queries did) -- scoped to the 27
+real gauge stations, matching what "redownload IDPR" means (fresh
+values at known station points), not the full ~4,500-node reach graph
+(which would mean thousands of individual HTTP requests -- a different,
+much larger undertaking than this).
+
+Usage:
+    python -m scripts.fetch_idpr_brgm --check
+    python -m scripts.fetch_idpr_brgm --stations datasets/station_elevations.csv
+"""
+import argparse
+import re
+from pathlib import Path
+
+import pandas as pd
+import requests
+
+WMS_URL = "http://geoservices.brgm.fr/geologie"
+LAYER = "IDPR_50M"  # highest resolution; use --layer to try a coarser one if this fails
+
+
+def get_feature_info_at_point(lat: float, lon: float, layer: str = LAYER,
+                               half_extent_deg: float = 0.001) -> "float | None":
+    """
+    Query IDPR value at a single point via WMS GetFeatureInfo: request a
+    tiny 3x3 pixel map centered on (lat, lon), then ask for the value at
+    the center pixel.
+    """
+    minx, miny = lon - half_extent_deg, lat - half_extent_deg
+    maxx, maxy = lon + half_extent_deg, lat + half_extent_deg
+    params = {
+        "SERVICE": "WMS", "VERSION": "1.1.1", "REQUEST": "GetFeatureInfo",
+        "LAYERS": layer, "QUERY_LAYERS": layer, "STYLES": "",
+        "BBOX": f"{minx},{miny},{maxx},{maxy}", "SRS": "EPSG:4326",
+        "WIDTH": 3, "HEIGHT": 3, "X": 1, "Y": 1,
+        "INFO_FORMAT": "text/plain",
+    }
+    try:
+        resp = requests.get(WMS_URL, params=params, timeout=30)
+    except requests.RequestException as e:
+        print(f"    request failed: {e}")
+        return None
+
+    if resp.status_code != 200:
+        print(f"    HTTP {resp.status_code}")
+        return None
+
+    return parse_getfeatureinfo_value(resp.text)
+
+
+def parse_getfeatureinfo_value(text: str) -> "float | None":
+    """
+    MapServer's text/plain GetFeatureInfo output is typically a small
+    block like:
+        Layer 'IDPR_50M'
+        Feature 0
+          value = '885'
+    Parsing defensively: find any line with 'value' (case-insensitive)
+    and extract the first number on it, rather than assuming an exact
+    format -- MapServer's plain-text output format has enough real
+    variation across deployments that a strict parser is more likely to
+    silently return nothing than a permissive one is to return a wrong
+    number.
+    """
+    for line in text.splitlines():
+        if "value" in line.lower():
+            match = re.search(r"[-+]?\d*\.?\d+", line)
+            if match:
+                return float(match.group())
+    return None
+
+
+def check_service() -> bool:
+    # A real point known to be in mainland France, well within IDPR coverage
+    test_lat, test_lon = 49.03, 0.79
+    print(f"Testing {LAYER} at ({test_lat}, {test_lon})...")
+    value = get_feature_info_at_point(test_lat, test_lon)
+    if value is not None:
+        print(f"  OK: value = {value}")
+        return True
+    print("  FAILED: no value returned. Try --layer IDPR_100M or IDPR_500M "
+          "(coarser resolutions), or check GetCapabilities directly:")
+    print(f"  {WMS_URL}?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetCapabilities")
+    return False
+
+
+def fetch_for_stations(stations_path: Path, layer: str, output_path: Path) -> None:
+    stations = pd.read_csv(stations_path)
+    lat_col = "latitude" if "latitude" in stations.columns else "lat"
+    lon_col = "longitude" if "longitude" in stations.columns else "lon"
+
+    rows = []
+    for _, row in stations.iterrows():
+        code = row["station_code"]
+        value = get_feature_info_at_point(row[lat_col], row[lon_col], layer=layer)
+        print(f"  {code}: {value}")
+        rows.append({"station_code": code, "idpr_value_brgm_live": value,
+                      "latitude": row[lat_col], "longitude": row[lon_col]})
+
+    out = pd.DataFrame(rows)
+    n_ok = out["idpr_value_brgm_live"].notna().sum()
+    print()
+    print(f"{n_ok}/{len(out)} stations got a real value")
+    out.to_csv(output_path, index=False)
+    print(f"Saved to {output_path}")
+    if n_ok < len(out):
+        print("Some stations got no value -- this could mean they're just outside "
+              "IDPR's coverage, or the layer/resolution needs adjusting. Compare "
+              "against the existing idpr.csv for those specific stations before "
+              "assuming the live fetch is wrong.")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Fetch fresh IDPR values from BRGM's live geoservice")
+    parser.add_argument("--check", action="store_true")
+    parser.add_argument("--stations", type=Path, default=Path("datasets/station_elevations.csv"))
+    parser.add_argument("--layer", type=str, default=LAYER)
+    parser.add_argument("--output", type=Path, default=Path("datasets/idpr_brgm_live.csv"))
+    args = parser.parse_args()
+
+    if args.check:
+        check_service()
+        return
+
+    fetch_for_stations(args.stations, args.layer, args.output)
+
+
+if __name__ == "__main__":
+    main()

scripts/data_acquisition/fetch_landcover.py

@@ -0,0 +1,134 @@
+"""
+Samples ESA WorldCover landcover classification and NDVI at station
+points, from the public AWS S3 Cloud-Optimized GeoTIFF tiles -- not the
+Terrascope WMS.
+
+WHY NOT WMS: a source dated July 2026 reports Terrascope's WMS actively
+resets connections from non-browser HTTP clients (TLS fingerprinting,
+confirmed across curl/wget/Node fetch with multiple User-Agents) --
+this is not a coding problem to work around, it's the service
+declining non-browser clients. Separately, that WMS was scheduled for
+full phase-out in January 2026, already past. Using ESA's own
+recommended alternative instead: direct S3 access, "avoids unzipping
+steps" per ESA's own documentation, genuinely public, no auth/signing.
+
+TILE: ESA WorldCover ships as 3x3 degree COG tiles named by their
+southwest corner, e.g. "N48E000". All of this project's real station
+coordinates (lon 0.43-1.54E, lat 48.39-49.34N) fall inside exactly one
+tile: N48E000 -- computed directly (floor each coordinate to the
+nearest 3-degree grid line), not guessed.
+
+CAVEAT: the exact object key/path within the S3 bucket is reasoned from
+documented ESA WorldCover file-naming conventions
+(ESA_WorldCover_10m_2021_v200_{tile}_Map.tif for classification), NOT
+independently verified against a live S3 listing -- no network access
+in the environment this was written in to confirm it directly. Run
+--check first.
+
+NEEDS: rasterio (for reading COG tiles and sampling point values).
+
+Usage:
+    python -m scripts.fetch_worldcover_landcover --check
+    python -m scripts.fetch_worldcover_landcover --stations datasets/station_elevations.csv
+"""
+import argparse
+from pathlib import Path
+
+import pandas as pd
+
+BUCKET_BASE = "https://esa-worldcover.s3.eu-central-1.amazonaws.com"
+TILE = "N48E000"
+CLASSIFICATION_URL = f"{BUCKET_BASE}/v200/2021/map/ESA_WorldCover_10m_2021_v200_{TILE}_Map.tif"
+
+# 11-class legend, from ESA's own product documentation -- needed to make
+# the raw integer codes in the classification raster human-readable.
+LANDCOVER_CLASSES = {
+    10: "Tree cover", 20: "Shrubland", 30: "Grassland", 40: "Cropland",
+    50: "Built-up", 60: "Bare/sparse vegetation", 70: "Snow and ice",
+    80: "Permanent water bodies", 90: "Herbaceous wetland",
+    95: "Mangrove", 100: "Moss and lichen",
+}
+
+
+def compute_tile_id(lat: float, lon: float) -> str:
+    """3-degree grid tile ID containing (lat, lon), named by SW corner."""
+    import math
+    tile_lat = math.floor(lat / 3) * 3
+    tile_lon = math.floor(lon / 3) * 3
+    lat_str = f"N{tile_lat:02d}" if tile_lat >= 0 else f"S{-tile_lat:02d}"
+    lon_str = f"E{tile_lon:03d}" if tile_lon >= 0 else f"W{-tile_lon:03d}"
+    return f"{lat_str}{lon_str}"
+
+
+def check_access() -> bool:
+    try:
+        import rasterio
+    except ImportError:
+        print("rasterio is not installed -- this is required. "
+              "pip install rasterio --break-system-packages")
+        return False
+
+    print(f"Checking {CLASSIFICATION_URL} ...")
+    try:
+        with rasterio.open(CLASSIFICATION_URL) as src:
+            print(f"  OK: opened tile, shape={src.shape}, crs={src.crs}, dtype={src.dtypes[0]}")
+            # sample one known real point (a real station's coordinates)
+            test_lat, test_lon = 49.03, 0.79
+            vals = list(src.sample([(test_lon, test_lat)]))
+            print(f"  Sample at ({test_lat}, {test_lon}): {vals[0][0]} "
+                  f"({LANDCOVER_CLASSES.get(int(vals[0][0]), 'unknown class')})")
+        return True
+    except Exception as e:
+        print(f"  FAILED: {e}")
+        print(f"  The object key may not match the real S3 layout. Check the ESA WorldCover "
+              f"AWS registry page directly: https://registry.opendata.aws/esa-worldcover/")
+        return False
+
+
+def fetch_for_stations(stations_path: Path, output_path: Path) -> None:
+    import rasterio
+
+    stations = pd.read_csv(stations_path)
+    lat_col = "latitude" if "latitude" in stations.columns else "lat"
+    lon_col = "longitude" if "longitude" in stations.columns else "lon"
+
+    # Confirm every station actually falls in the hardcoded tile before
+    # trusting a single-tile fetch -- if a future node set (e.g. the
+    # full ~4,500-node reach graph, not just the 27 gauges) extends
+    # beyond N48E000, this needs multiple tiles, not silently wrong data
+    # from the one tile that happens to be loaded.
+    tile_ids = stations.apply(lambda r: compute_tile_id(r[lat_col], r[lon_col]), axis=1)
+    unexpected = tile_ids[tile_ids != TILE].unique()
+    if len(unexpected) > 0:
+        print(f"WARNING: some stations fall outside tile {TILE}: {list(unexpected)}. "
+              f"This script only fetches {TILE} -- results for those stations will be wrong "
+              f"or missing. Extend BUCKET fetching to cover {list(unexpected)} too.")
+
+    with rasterio.open(CLASSIFICATION_URL) as src:
+        coords = list(zip(stations[lon_col], stations[lat_col]))
+        values = [v[0] for v in src.sample(coords)]
+
+    out = stations[["station_code"]].copy()
+    out["landcover_class_code"] = values
+    out["landcover_class_name"] = [LANDCOVER_CLASSES.get(int(v), "unknown") for v in values]
+    out.to_csv(output_path, index=False)
+    print(f"Saved {len(out)} stations' landcover class to {output_path}")
+    print(out["landcover_class_name"].value_counts())
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Sample ESA WorldCover landcover at station points")
+    parser.add_argument("--check", action="store_true")
+    parser.add_argument("--stations", type=Path, default=Path("datasets/station_elevations.csv"))
+    parser.add_argument("--output", type=Path, default=Path("datasets/worldcover_landcover.csv"))
+    args = parser.parse_args()
+
+    if args.check:
+        check_access()
+        return
+
+    fetch_for_stations(args.stations, args.output)
+
+
+if __name__ == "__main__":
+    main()

scripts/data_acquisition/fetch_meteofrance_precipitation.py

@@ -0,0 +1,240 @@
+"""
+Fetches real, directly-measured historical precipitation from
+Météo-France's public "Données climatologiques de base - horaires"
+dataset -- genuine rain-gauge observations, not reanalysis. This
+matters specifically for precipitation: it's known to vary sharply over
+short distances in ways a ~9km reanalysis grid cell (ERA5, used
+elsewhere in this project's climate work) can miss, so a real gauge
+near our actual stations is more authoritative where one exists.
+
+CONFIRMED real details (via Météo-France's own dataset page and a
+working third-party example querying the same API, not guessed):
+  - Producer: Météo-France, Open Licence 2.0, no authentication needed.
+  - Dataset API: https://www.data.gouv.fr/api/1/datasets/
+    donnees-climatologiques-de-base-horaires/ -- returns a real JSON
+    resource list (title + download url per file).
+  - Files are organized by department and decade-scale time period,
+    downloadable as compressed CSV (.csv.gz).
+  - Real temporal coverage extends to 1908 (varies by source/station),
+    covering this project's entire 2013+ study period with room to
+    spare.
+
+Usage:
+    python -m scripts.data_acquisition.fetch_meteofrance_precipitation --check --department 27
+"""
+import argparse
+import gzip
+from io import BytesIO
+from pathlib import Path
+
+import pandas as pd
+import requests
+
+DATASET_API = "https://www.data.gouv.fr/api/1/datasets/donnees-climatologiques-de-base-horaires/"
+
+# This project's real study departments -- Eure, Eure-et-Loir, Orne --
+# confirmed earlier in this project via the government bassin-versant
+# documentation and the real station roster.
+STUDY_DEPARTMENTS = ["27", "28", "61"]
+
+
+def list_real_resources() -> list:
+    """Fetches the real, current resource list directly from the dataset
+    API -- not a cached or guessed file listing, so this always reflects
+    whatever Météo-France currently has published."""
+    resp = requests.get(DATASET_API, timeout=30)
+    resp.raise_for_status()
+    data = resp.json()
+    return data.get("resources", [])
+
+
+def find_department_resources(resources: list, department: str) -> list:
+    """
+    Matches a department code against each real resource's title using
+    an explicit delimiter set (space, hyphen, underscore, or string
+    start/end) around the number -- confirmed as needing two real fixes,
+    not one: a first version only checked underscore/hyphen delimiters
+    and missed a realistic space-delimited title ("département 027");
+    a second version tried \\b (regex word boundary) instead, which
+    looked more robust but Python's \\b treats underscore as a WORD
+    character, so it doesn't create a boundary in "departement_27" --
+    "_27" reads as one unbroken token to \\b, and the match silently
+    fails there too. This explicitly enumerates the real delimiters
+    that actually appear in these titles instead of trusting a regex
+    primitive whose definition of "boundary" doesn't match what's
+    actually being delimited here.
+    """
+    import re
+    dept_2 = department.zfill(2)
+    dept_3 = department.zfill(3)
+    delim = r"[ \-_]|^"
+    end_delim = r"[ \-_]|$"
+    pattern = re.compile(rf"(?:{delim})(?:{re.escape(dept_2)}|{re.escape(dept_3)})(?:{end_delim})")
+    return [r for r in resources if pattern.search(r.get("title", ""))]
+
+
+def parse_decade_range(title: str):
+    """Extracts the (start_year, end_year) a resource title encodes,
+    e.g. "HOR_departement_27_periode_1920-1929" -> (1920, 1929). Returns
+    None if the title doesn't contain a real recognizable year range,
+    rather than guessing."""
+    import re
+    m = re.search(r"(\d{4})-(\d{4})", title)
+    if not m:
+        return None
+    return int(m.group(1)), int(m.group(2))
+
+
+def filter_relevant_decades(resources: list, start_year: int, end_year: int) -> list:
+    """Keeps only real resources whose decade range overlaps
+    [start_year, end_year] -- no reason to download 1900s data for a
+    project starting in 2013."""
+    relevant = []
+    for r in resources:
+        decade = parse_decade_range(r.get("title", ""))
+        if decade is None:
+            continue
+        decade_start, decade_end = decade
+        if decade_end >= start_year and decade_start <= end_year:
+            relevant.append(r)
+    return relevant
+
+
+def parse_and_aggregate_daily(csv_bytes: bytes) -> pd.DataFrame:
+    """
+    Parses one real downloaded, gzip-decompressed CSV and aggregates
+    real hourly RR1 (1-hour precipitation, mm) to daily totals per
+    station -- sum, not mean, since precipitation is an accumulated
+    quantity (matches the same aggregation choice already used for the
+    ECMWF forecast data in fetch_previous_runs.py's aggregate_to_daily).
+
+    AAAAMMJJHH is the real confirmed column name/format: a 10-digit
+    YYYYMMDDHH timestamp, parsed explicitly with that format rather
+    than left to pandas' generic date inference, which could silently
+    misparse an unusual all-digit string.
+    """
+    with gzip.open(BytesIO(csv_bytes)) as f:
+        df = pd.read_csv(f, sep=";", usecols=["NUM_POSTE", "NOM_USUEL", "LAT", "LON", "AAAAMMJJHH", "RR1"])
+
+    df["date"] = pd.to_datetime(df["AAAAMMJJHH"].astype(str), format="%Y%m%d%H").dt.date
+    daily = df.groupby(["NUM_POSTE", "NOM_USUEL", "LAT", "LON", "date"], as_index=False)["RR1"].sum(min_count=1)
+    daily = daily.rename(columns={"RR1": "precip_mm_daily"})
+    return daily
+
+
+def fetch_department_daily_precipitation(department: str, start_year: int, end_year: int) -> pd.DataFrame:
+    resources = list_real_resources()
+    dept_resources = find_department_resources(resources, department)
+    relevant = filter_relevant_decades(dept_resources, start_year, end_year)
+    print(f"  department {department}: {len(relevant)} real decade file(s) overlap "
+          f"[{start_year}, {end_year}]")
+
+    all_daily = []
+    for r in relevant:
+        print(f"    downloading {r['title']} ...")
+        try:
+            resp = requests.get(r["url"], timeout=120)
+            resp.raise_for_status()
+            daily = parse_and_aggregate_daily(resp.content)
+        except Exception as e:
+            print(f"    FAILED for {r['title']}: {e}")
+            continue
+        # Real files span a full decade -- restrict to the actual
+        # requested range so a "2010-2019" file doesn't pull in years
+        # before start_year that weren't asked for.
+        daily = daily[(pd.to_datetime(daily["date"]).dt.year >= start_year) &
+                       (pd.to_datetime(daily["date"]).dt.year <= end_year)]
+        all_daily.append(daily)
+
+    if not all_daily:
+        return pd.DataFrame(columns=["NUM_POSTE", "NOM_USUEL", "LAT", "LON", "date", "precip_mm_daily"])
+    return pd.concat(all_daily, ignore_index=True)
+
+
+def check_access(department: str) -> bool:
+    print(f"Fetching real resource list from {DATASET_API} ...")
+    try:
+        resources = list_real_resources()
+    except Exception as e:
+        print(f"FAILED to fetch dataset resource list: {e}")
+        return False
+    print(f"Real dataset has {len(resources)} total resource(s) listed")
+
+    matches = find_department_resources(resources, department)
+    print(f"Resources matching department {department} (checked both 2-digit and 3-digit forms): {len(matches)}")
+    if not matches:
+        print("No matches -- printing the first 10 real resource titles so the actual naming "
+              "convention can be inspected directly, rather than guessed at again:")
+        for r in resources[:10]:
+            print(f"  {r.get('title')}")
+        return False
+
+    for r in matches[:5]:
+        print(f"  {r.get('title')} -> {r.get('url')}")
+
+    # Download the smallest real match and inspect its actual real columns
+    # before trusting any assumption about the precipitation column name.
+    test_resource = min(matches, key=lambda r: r.get("filesize") or float("inf"))
+    print(f"\nDownloading a real sample file to inspect actual columns: {test_resource.get('title')}")
+    try:
+        resp = requests.get(test_resource["url"], timeout=60)
+        resp.raise_for_status()
+        with gzip.open(BytesIO(resp.content)) as f:
+            df = pd.read_csv(f, sep=";", nrows=5)
+    except Exception as e:
+        print(f"FAILED to download or parse the real sample file: {e}")
+        return False
+
+    print(f"Real columns found: {list(df.columns)}")
+    if "RR1" in df.columns:
+        print("CONFIRMED: 'RR1' (1-hour precipitation) is present, matching the standard convention.")
+    else:
+        print("'RR1' not found in the real columns above -- the precipitation column has a "
+              "different real name here; check the printed list directly rather than assume RR1.")
+    print(df.head())
+    return True
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Fetch real historical precipitation from Météo-France")
+    parser.add_argument("--check", action="store_true")
+    parser.add_argument("--department", type=str, default="27")
+    parser.add_argument("--departments", type=str, nargs="+", default=STUDY_DEPARTMENTS,
+                         help="Full fetch mode only -- defaults to all three real study departments.")
+    parser.add_argument("--start-year", type=int, default=2013)
+    parser.add_argument("--end-year", type=int, default=2026)
+    parser.add_argument("--output-dir", type=Path, default=Path("datasets/meteofrance_precipitation"))
+    args = parser.parse_args()
+
+    if args.check:
+        check_access(args.department)
+        return
+
+    args.output_dir.mkdir(parents=True, exist_ok=True)
+    all_departments = []
+    for dept in args.departments:
+        print(f"Fetching real precipitation for department {dept}...")
+        daily = fetch_department_daily_precipitation(dept, args.start_year, args.end_year)
+        if daily.empty:
+            print(f"  no real data retrieved for department {dept}")
+            continue
+        daily["department"] = dept
+        all_departments.append(daily)
+
+    if not all_departments:
+        print("No real data retrieved for any department -- run --check first if this is unexpected.")
+        return
+
+    combined = pd.concat(all_departments, ignore_index=True)
+    n_stations = combined["NUM_POSTE"].nunique()
+    n_real_values = combined["precip_mm_daily"].notna().sum()
+    print(f"\nReal daily precipitation: {n_stations} station(s) across {len(args.departments)} department(s), "
+          f"{n_real_values} real day-station value(s)")
+
+    output_path = args.output_dir / "daily_precipitation.csv"
+    combined.to_csv(output_path, index=False)
+    print(f"Saved to {output_path}")
+
+
+if __name__ == "__main__":
+    main()

scripts/data_acquisition/fetch_previous_runs.py

@@ -0,0 +1,175 @@
+"""
+Fetches Open-Meteo's Previous Runs API -- real past forecasts at fixed
+lead-time offsets (1-7 days), the piece needed to validate whether
+ECMWF's forecast would genuinely have caught real historical flood
+conditions, without look-ahead leakage. This is the actual prerequisite
+for real bias-correction: comparing what was forecast N days ahead
+against what really happened, per lead time.
+
+CONFIRMED real details (via Open-Meteo's own documentation): variable
+suffix pattern `{variable}_previous_day{N}` for N=1..7 (e.g.
+precipitation_sum_previous_day3 = what was forecast 3 days before the
+valid date). Data starts January 2024 for most models; ECMWF IFS HRES
+specifically from March 2024 -- meaning real lead-time-stratified
+validation is only possible for roughly the last 2.5 years, not this
+project's full multi-decade discharge record. Multiple locations can be
+queried in one request via comma-separated coordinate lists.
+
+NOT directly confirmed: the exact hostname for this specific API.
+Open-Meteo's two sibling historical products have confirmed hostnames
+following a clear pattern (archive-api.open-meteo.com,
+historical-forecast-api.open-meteo.com) -- "previous-runs-api.open-
+meteo.com" is inferred from that pattern, not verified by a direct
+source. Run --check first; if it 404s, the real hostname needs a fresh
+search rather than a second guess.
+
+Usage:
+    python -m scripts.fetch_previous_runs --check
+    python -m scripts.fetch_previous_runs --stations-path datasets/station_elevations.csv
+"""
+import argparse
+from pathlib import Path
+
+import pandas as pd
+import requests
+
+BASE_URL = "https://previous-runs-api.open-meteo.com/v1/forecast"  # confirmed real hostname -- see module docstring
+
+# HOURLY variable names, not daily aggregates -- confirmed as the real
+# fix, not a second blind guess: every real documentation example of
+# the _previous_dayN suffix used "temperature_2m_previous_day1" (the
+# hourly variable name), never "temperature_2m_max_previous_day1" (a
+# daily aggregate). The first real request against this endpoint used
+# daily aggregate names and got a genuine 400 (invalid variable value),
+# confirming the hostname was right but the parameter convention was
+# wrong. Daily aggregation happens client-side in aggregate_to_daily
+# below, matching this project's own established convention rather than
+# assuming the API supports a suffix pattern it apparently doesn't for
+# daily variables.
+HOURLY_VARIABLES = ["precipitation", "temperature_2m", "wind_speed_10m"]
+LEAD_DAYS = [1, 2, 3, 5, 7]
+
+
+def build_hourly_params(lead_days: list) -> list:
+    """{variable}_previous_day{N} for every requested variable/lead-time
+    combination, plus day0 (the run closest to the live forecast) as a
+    reference point."""
+    params = []
+    for var in HOURLY_VARIABLES:
+        params.append(f"{var}_previous_day0")
+        for n in lead_days:
+            params.append(f"{var}_previous_day{n}")
+    return params
+
+
+def aggregate_to_daily(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Collapses the real hourly response to daily values -- sum for
+    precipitation, max for temperature/wind, matching standard
+    meteorological daily-aggregate convention and this project's
+    existing daily-resolution pipeline (climate_climatology.py etc.).
+    """
+    df = df.copy()
+    df["date"] = pd.to_datetime(df["time"]).dt.date
+    agg_rules = {}
+    for col in df.columns:
+        if col in ("time", "date", "latitude", "longitude", "station_code"):
+            continue
+        agg_rules[col] = "sum" if col.startswith("precipitation") else "max"
+    daily = df.groupby("date").agg(agg_rules).reset_index()
+    return daily
+
+
+def check_access() -> bool:
+    params = {
+        "latitude": 48.748705218, "longitude": 0.58156195,
+        "hourly": ",".join(build_hourly_params(LEAD_DAYS)),
+        "start_date": "2024-06-01", "end_date": "2024-06-07",
+        "timezone": "Europe/Paris",
+    }
+    print(f"Testing {BASE_URL} with hourly variable names (the confirmed real convention)...")
+    try:
+        resp = requests.get(BASE_URL, params=params, timeout=30)
+        print(f"HTTP status: {resp.status_code}")
+        if resp.status_code != 200:
+            print(f"Response body: {resp.text[:500]}")
+            return False
+        data = resp.json()
+    except Exception as e:
+        print(f"FAILED: {e}")
+        return False
+
+    if "hourly" not in data:
+        print(f"FAILED: no 'hourly' key in response. Full response: {data}")
+        return False
+
+    print("OK -- real lead-time-stratified hourly data returned:")
+    for key in list(data["hourly"].keys())[:6]:
+        print(f"  {key}: {data['hourly'][key][:3]}...")
+    return True
+
+
+def fetch_previous_runs(lat: float, lon: float, start_date: str, end_date: str,
+                         lead_days: list = LEAD_DAYS) -> pd.DataFrame:
+    params = {
+        "latitude": lat, "longitude": lon,
+        "hourly": ",".join(build_hourly_params(lead_days)),
+        "start_date": start_date, "end_date": end_date,
+        "timezone": "Europe/Paris",
+    }
+    resp = requests.get(BASE_URL, params=params, timeout=60)
+    resp.raise_for_status()
+    data = resp.json()
+    if "hourly" not in data:
+        raise ValueError(f"No 'hourly' data for ({lat}, {lon}): {data}")
+
+    df = pd.DataFrame(data["hourly"])
+    df["latitude"] = lat
+    df["longitude"] = lon
+    return df
+
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Fetch Open-Meteo Previous Runs data for bias-correction validation")
+    parser.add_argument("--check", action="store_true")
+    parser.add_argument("--stations-path", type=Path, default=Path("datasets/station_elevations.csv"))
+    parser.add_argument("--start-date", type=str, default="2024-03-01",
+                         help="Defaults to when ECMWF IFS HRES coverage begins in this archive")
+    parser.add_argument("--end-date", type=str, default="2026-08-30")
+    parser.add_argument("--output", type=Path, default=Path("datasets/previous_runs_forecast.csv"))
+    args = parser.parse_args()
+
+    if args.check:
+        check_access()
+        return
+
+    stations = pd.read_csv(args.stations_path)
+    lat_col = "latitude" if "latitude" in stations.columns else "lat"
+    lon_col = "longitude" if "longitude" in stations.columns else "lon"
+
+    all_dfs = []
+    for _, row in stations.iterrows():
+        code = row.get("station_code", f"{row[lat_col]:.3f}_{row[lon_col]:.3f}")
+        print(f"Fetching real previous-runs data for {code}...")
+        try:
+            df = fetch_previous_runs(row[lat_col], row[lon_col], args.start_date, args.end_date)
+            df = aggregate_to_daily(df)
+            df["station_code"] = code
+            all_dfs.append(df)
+        except Exception as e:
+            print(f"  FAILED for {code}: {e}")
+
+    if not all_dfs:
+        print("No real data fetched -- run --check first if every station failed.")
+        return
+
+    combined = pd.concat(all_dfs, ignore_index=True)
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    combined.to_csv(args.output, index=False)
+    print(f"\nSaved real lead-time-stratified forecast history for "
+          f"{combined['station_code'].nunique()} station(s) to {args.output}")
+
+
+if __name__ == "__main__":
+    main()

scripts/data_acquisition/fetch_worldcover_ndvi.py

@@ -0,0 +1,155 @@
+"""
+Samples ESA WorldCover's Sentinel-2 NDVI yearly percentile composite
+(p10/p50/p90) at station points, via the public S3 COGs.
+
+Unlike fetch_worldcover_landcover.py, this does NOT hand-compute the
+tile ID and guess the S3 key pattern -- VITO provides an authoritative
+grid file for exactly this purpose (found directly, not guessed):
+    https://esa-worldcover.s3.eu-central-1.amazonaws.com/esa_worldcover_grid_composites.fgb
+This is a FlatGeobuf containing one feature per 1x1 degree composite
+tile, with (per VITO's own documentation) the real S3 path/URL for
+each tile as an attribute -- reading it means never guessing a file
+naming convention, which is exactly the class of guess that failed for
+the IDPR WMS layer name earlier in this session.
+
+The composites use a 1x1 degree grid, NOT the 3x3 degree grid the
+landcover classification map uses -- so unlike fetch_worldcover_
+landcover.py's single hardcoded tile, station coordinates spanning
+more than 1 degree in either direction genuinely need more than one
+tile here. This script looks up each station's tile individually
+rather than assuming one tile covers everyone.
+
+NEEDS: geopandas (to read the grid FlatGeobuf) and rasterio (to sample
+the COGs). CAVEAT: the grid file's actual column names/schema are not
+independently verified here (no network access to inspect it directly)
+-- the script prints all columns and searches for a plausible URL/path
+column rather than assuming an exact name, and reports clearly if it
+can't find one.
+
+Usage:
+    python -m scripts.fetch_worldcover_ndvi --check
+    python -m scripts.fetch_worldcover_ndvi --stations datasets/station_elevations.csv
+"""
+import argparse
+from pathlib import Path
+
+import pandas as pd
+
+GRID_URL = "https://esa-worldcover.s3.eu-central-1.amazonaws.com/esa_worldcover_grid_composites.fgb"
+
+# The grid file's tile URLs use the s3:// scheme (confirmed against real
+# output: s3://esa-worldcover-s2/ndvi/2020/N48/...) -- GDAL's S3 driver
+# tries to SIGN requests with real AWS credentials by default even
+# though this bucket is fully public, unlike the HTTPS URL
+# fetch_worldcover_landcover.py used (a plain HTTPS GET needs no
+# signing at all, which is why that one worked without this). This
+# environment variable is the standard fix for reading a public S3
+# bucket without needing real credentials.
+import os
+os.environ.setdefault("AWS_NO_SIGN_REQUEST", "YES")
+
+
+def load_grid():
+    import geopandas as gpd
+    print(f"Loading tile grid from {GRID_URL} ...")
+    grid = gpd.read_file(GRID_URL)
+    print(f"  {len(grid)} tile(s), columns: {list(grid.columns)}")
+    return grid
+
+
+def find_url_column(grid) -> str:
+    """
+    The grid's real column name for the tile's S3 path isn't
+    independently confirmed -- search for a plausible one rather than
+    assume, and fail loudly (not silently) if nothing matches.
+    """
+    candidates = [c for c in grid.columns if any(
+        kw in c.lower() for kw in ("url", "href", "path", "s3", "ndvi", "product", "file")
+    )]
+    if not candidates:
+        raise ValueError(
+            f"No column looks like a tile URL/path among {list(grid.columns)}. "
+            f"Inspect the grid file's real schema directly (e.g. print(grid.head()) "
+            f"in a notebook) and adjust find_url_column accordingly."
+        )
+    print(f"  candidate URL/path column(s): {candidates} -- using {candidates[0]!r}")
+    return candidates[0]
+
+
+def check_access() -> bool:
+    try:
+        import geopandas  # noqa: F401
+        import rasterio  # noqa: F401
+    except ImportError as e:
+        print(f"Missing dependency: {e}. pip install geopandas rasterio --break-system-packages")
+        return False
+
+    try:
+        grid = load_grid()
+        url_col = find_url_column(grid)
+        print(f"  Sample values from {url_col!r}: {grid[url_col].head(3).tolist()}")
+        return True
+    except Exception as e:
+        print(f"  FAILED: {e}")
+        return False
+
+
+def fetch_for_stations(stations_path: Path, output_path: Path) -> None:
+    import geopandas as gpd
+    import rasterio
+    from shapely.geometry import Point
+
+    stations = pd.read_csv(stations_path)
+    lat_col = "latitude" if "latitude" in stations.columns else "lat"
+    lon_col = "longitude" if "longitude" in stations.columns else "lon"
+
+    grid = load_grid()
+    url_col = find_url_column(grid)
+
+    station_points = gpd.GeoDataFrame(
+        stations,
+        geometry=[Point(lon, lat) for lon, lat in zip(stations[lon_col], stations[lat_col])],
+        crs=grid.crs,
+    )
+    joined = gpd.sjoin(station_points, grid[[url_col, "geometry"]], how="left", predicate="within")
+
+    rows = []
+    for tile_url, group in joined.groupby(url_col):
+        if pd.isna(tile_url):
+            for _, row in group.iterrows():
+                rows.append({"station_code": row["station_code"], "ndvi_p10": None,
+                             "ndvi_p50": None, "ndvi_p90": None})
+            continue
+        print(f"  opening {tile_url} for {len(group)} station(s)...")
+        with rasterio.Env(AWS_NO_SIGN_REQUEST="YES"), rasterio.open(tile_url) as src:
+            coords = list(zip(group[lon_col], group[lat_col]))
+            values = list(src.sample(coords))
+        for (_, row), val in zip(group.iterrows(), values):
+            # NDVI percentile composite is documented as 3 bands: p90, p50, p10
+            rows.append({"station_code": row["station_code"],
+                         "ndvi_p90": float(val[0]) if len(val) > 0 else None,
+                         "ndvi_p50": float(val[1]) if len(val) > 1 else None,
+                         "ndvi_p10": float(val[2]) if len(val) > 2 else None})
+
+    out = pd.DataFrame(rows)
+    out.to_csv(output_path, index=False)
+    print(f"Saved {len(out)} stations' NDVI values to {output_path}")
+    print(out.describe())
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Sample ESA WorldCover NDVI at station points")
+    parser.add_argument("--check", action="store_true")
+    parser.add_argument("--stations", type=Path, default=Path("datasets/station_elevations.csv"))
+    parser.add_argument("--output", type=Path, default=Path("datasets/worldcover_ndvi.csv"))
+    args = parser.parse_args()
+
+    if args.check:
+        check_access()
+        return
+
+    fetch_for_stations(args.stations, args.output)
+
+
+if __name__ == "__main__":
+    main()

scripts/evaluation/evaluate_flood_detection.py

@@ -0,0 +1,986 @@
+"""
+Evaluates whether the currently trained spatiotemporal GNN would have
+flagged the real historical high-flow events identified by
+identify_flood_events.py. This is the test that actually matters for
+this project's stated purpose -- beating a naive mean-baseline says
+the model learned real structure, but says nothing about whether it
+would catch a real flood. Those are different questions, and only
+this one answers the second.
+
+Reuses the exact data pipeline from train_spatiotemporal_gnn.py (same
+subgraph selection, same standardization) rather than rebuilding it
+independently -- the model's saved weights only make sense against the
+exact input shapes and standardization statistics they were trained
+with, so any mismatch here would silently produce meaningless
+predictions rather than a clean error.
+
+For every real (anchor_date, node, horizon) combination in the held-out
+test split, checks whether the model's own discharge prediction --
+converted back to real L/s, not left in standardized units -- exceeds
+that station's real event threshold (the same threshold
+identify_flood_events.py used to define a "high-flow day" there).
+Confusion matrix is computed per horizon: catching a real event a day
+out and catching it a week out are different questions, and averaging
+them together would hide which lead times the model is actually
+useful at.
+
+Usage:
+    python -m scripts.evaluation.evaluate_flood_detection --data-root datasets
+"""
+import argparse
+from pathlib import Path
+from typing import Dict, List
+
+import numpy as np
+import pandas as pd
+import torch
+
+try:
+    from scripts.training.train_spatiotemporal_gnn import (
+        BASIN_FILE_NAMES, HORIZONS, QUANTILES, load_basin_graph, combine_basins,
+        build_combined_dynamic_tensors, standardize_dynamic_tensors, standardize_static_features,
+        extract_catchment_area_km2,
+        compute_rolling_precip_sum, fit_specific_discharge_coefficient, estimate_discharge_from_precip,
+        build_forecast_tensor, compute_days_since_last_real, compress_days_since_last_real,
+        get_dynamic_channel_index, ROUTING_HORIZON_COUNT, FORECAST_LEAD_TIMES,
+    )
+    from src.graph.subgraph_selection import build_collapsed_subgraph
+    from src.graph.spatiotemporal_gnn import prepare_graph_training_windows, SpatiotemporalGNN
+except ImportError:
+    import sys
+    sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent))
+    from scripts.training.train_spatiotemporal_gnn import (
+        BASIN_FILE_NAMES, HORIZONS, QUANTILES, load_basin_graph, combine_basins,
+        build_combined_dynamic_tensors, standardize_dynamic_tensors, standardize_static_features,
+        extract_catchment_area_km2,
+        compute_rolling_precip_sum, fit_specific_discharge_coefficient, estimate_discharge_from_precip,
+        build_forecast_tensor, compute_days_since_last_real, compress_days_since_last_real,
+        get_dynamic_channel_index, ROUTING_HORIZON_COUNT, FORECAST_LEAD_TIMES,
+    )
+    from src.graph.subgraph_selection import build_collapsed_subgraph
+    from src.graph.spatiotemporal_gnn import prepare_graph_training_windows, SpatiotemporalGNN
+
+
+def build_event_lookup(events_df: pd.DataFrame) -> dict:
+    """
+    Real event date ranges, indexed by station, for fast membership
+    checks -- {station_code: [(start_date, end_date, threshold), ...]}.
+    A single station can have several real events across the record, so
+    this stays a list per station rather than assuming at most one.
+    """
+    lookup = {}
+    for _, row in events_df.iterrows():
+        lookup.setdefault(row["station_code"], []).append(
+            (pd.Timestamp(row["start_date"]), pd.Timestamp(row["end_date"]), row["threshold"])
+        )
+    return lookup
+
+
+def is_real_event_day(station_code: str, date: pd.Timestamp, event_lookup: dict):
+    """
+    Returns the real threshold if `date` falls within a real event for
+    this station, else None -- distinguishing "not an event" from
+    "no threshold defined" matters for how the caller should treat it,
+    so this returns the threshold itself rather than a bare boolean.
+    """
+    for start, end, threshold in event_lookup.get(station_code, []):
+        if start <= date <= end:
+            return threshold
+    return None
+
+
+def days_to_nearest_real_event(station_code: str, date: pd.Timestamp, event_lookup: dict) -> "float":
+    """
+    Real, signed distance in days from `date` to the nearest real event
+    window for this station -- 0 if `date` falls inside one. Built to
+    distinguish a real false positive that's a near-miss (a day or two
+    from an actual real event) from one with no real event anywhere
+    nearby, which are genuinely different situations worth telling
+    apart when inspecting false positives directly.
+
+    Returns float("inf") if this station has no real events at all.
+    """
+    best = float("inf")
+    for start, end, _ in event_lookup.get(station_code, []):
+        if start <= date <= end:
+            return 0.0
+        gap = min(abs((date - start).days), abs((date - end).days))
+        best = min(best, gap)
+    return best
+
+
+def build_station_thresholds(events_df: pd.DataFrame) -> dict:
+    """
+    One real threshold per station -- identify_flood_events.py computes
+    this once per station (that station's own historical percentile),
+    so every real event row for a given station carries the same value;
+    this collapses that back down to {station_code: threshold}.
+
+    This threshold is what gets compared against EVERY day's
+    prediction, event or not -- comparing only on real event days (and
+    treating every other day as an automatic non-flag) would make false
+    positives structurally impossible and precision meaningless by
+    construction, not just optimistic.
+    """
+    return events_df.groupby("station_code")["threshold"].first().to_dict()
+
+
+def plot_confusion_matrices_by_horizon(confusion: dict, horizons: list, output_path: Path) -> None:
+    """
+    A real 2x2 confusion matrix heatmap per horizon, arranged in a grid
+    -- gives an immediate visual read on how tp/fp/fn/tn actually shift
+    across lead times, rather than reading raw counts out of a printed
+    table.
+    """
+    import matplotlib.pyplot as plt
+
+    n_horizons = len(horizons)
+    n_cols = min(5, n_horizons)
+    n_rows = (n_horizons + n_cols - 1) // n_cols
+    fig, axes = plt.subplots(n_rows, n_cols, figsize=(3.2 * n_cols, 3.2 * n_rows))
+    axes = axes.flatten() if n_horizons > 1 else [axes]
+
+    for idx, h in enumerate(horizons):
+        ax = axes[idx]
+        c = confusion[h]
+        # rows = actual (event, no event), cols = predicted (flag, no flag)
+        matrix = [[c["tp"], c["fn"]], [c["fp"], c["tn"]]]
+        im = ax.imshow(matrix, cmap="Blues", vmin=0)
+        for i in range(2):
+            for j in range(2):
+                value = matrix[i][j]
+                # Text color flips for readability against the
+                # colormap's own darker high-value cells.
+                text_color = "white" if value > (max(max(row) for row in matrix) / 2) else "black"
+                ax.text(j, i, str(value), ha="center", va="center", color=text_color, fontsize=11)
+        ax.set_xticks([0, 1])
+        ax.set_yticks([0, 1])
+        ax.set_xticklabels(["flagged", "not flagged"], fontsize=8)
+        ax.set_yticklabels(["event", "no event"], fontsize=8)
+        ax.set_title(f"{h}-day", fontsize=10)
+
+    for idx in range(n_horizons, len(axes)):
+        axes[idx].axis("off")
+
+    fig.suptitle("Flood-detection confusion matrix by lead time (real held-out test data)")
+    fig.tight_layout()
+    fig.savefig(output_path, dpi=150)
+    plt.close(fig)
+
+
+def plot_precision_recall_by_horizon(result_df: "object", output_path: Path) -> None:
+    """
+    Precision, recall, and the real base rate, all against horizon on
+    one plot -- deliberately including base rate directly rather than
+    leaving it as a separate manual calculation, since this project has
+    repeatedly found that a horizon's precision only means something
+    when read against how often a real event actually occurs there (a
+    horizon with very few real events can show inflated-looking
+    precision/recall from a handful of lucky flags).
+    """
+    import matplotlib.pyplot as plt
+
+    horizons = result_df["horizon_days"].values
+    precision = result_df["precision"].values
+    recall = result_df["recall"].values
+    base_rate = (result_df["tp"] + result_df["fn"]) / (
+        result_df["tp"] + result_df["fp"] + result_df["fn"] + result_df["tn"]
+    )
+
+    fig, ax = plt.subplots(figsize=(9, 5))
+    x_pos = range(len(horizons))  # evenly spaced positions -- HORIZONS jumps unevenly
+    # (5 -> 10 -> 30 -> 60 -> 90 -> 180), so a real numeric x-axis would
+    # compress the 1-10 day range (where most of the real signal lives)
+    # into a small sliver of the plot.
+    ax.plot(x_pos, precision, marker="o", label="precision", color="#2563eb")
+    ax.plot(x_pos, recall, marker="o", label="recall", color="#16a34a")
+    ax.plot(x_pos, base_rate, marker="o", label="real event base rate", color="#94a3b8", linestyle="--")
+    ax.set_xticks(list(x_pos))
+    ax.set_xticklabels([str(h) for h in horizons])
+    ax.set_xlabel("Lead time (days)")
+    ax.set_ylabel("Rate")
+    ax.set_ylim(-0.02, 1.02)
+    ax.set_title("Precision/recall vs. lead time, against the real event base rate")
+    ax.legend(loc="best")
+    ax.grid(True, alpha=0.3)
+    fig.tight_layout()
+    fig.savefig(output_path, dpi=150)
+    plt.close(fig)
+
+
+def plot_single_trace(
+    horizons: list, quantiles: list, quantile_values_real: "object",
+    threshold: float, routing_horizon_count: int, station_code: str, anchor_str: str,
+    output_path: Path,
+) -> None:
+    """
+    Real predicted discharge, every quantile, across every real
+    horizon, for one specific (anchor, station) example -- with the
+    real station threshold and the real ROUTING_HORIZON_COUNT boundary
+    both marked directly on the plot. Built specifically to check for a
+    real visual discontinuity right at the physics-loss boundary, which
+    an aggregate statistic (mean/ratio across many examples) could
+    smooth over or miss entirely.
+    """
+    import matplotlib.pyplot as plt
+
+    fig, ax = plt.subplots(figsize=(10, 6))
+    x_pos = range(len(horizons))
+    colors = {0.5: "#2563eb", 0.9: "#f59e0b", 0.95: "#dc2626", 0.99: "#7c3aed"}
+    for q_idx, q in enumerate(quantiles):
+        ax.plot(x_pos, quantile_values_real[:, q_idx], marker="o",
+                label=f"quantile {q}", color=colors.get(q, "#333333"))
+
+    ax.axhline(threshold, color="#16a34a", linestyle="--", linewidth=1.5, label="real station threshold")
+
+    # Real ROUTING_HORIZON_COUNT boundary -- physics losses (routing,
+    # soft-DTW, water balance) apply up through this horizon and no
+    # further; marked as a real, vertical reference line, not just
+    # mentioned in the title, so it's directly visible against whatever
+    # the quantile lines actually do there.
+    if routing_horizon_count in horizons:
+        boundary_x = horizons.index(routing_horizon_count)
+        ax.axvline(boundary_x, color="#94a3b8", linestyle=":", linewidth=1.5,
+                   label=f"ROUTING_HORIZON_COUNT boundary ({routing_horizon_count}d)")
+
+    ax.set_xticks(list(x_pos))
+    ax.set_xticklabels([str(h) for h in horizons])
+    ax.set_xlabel("Lead time (days)")
+    ax.set_ylabel("Discharge (real L/s)")
+    ax.set_title(f"Real predicted discharge quantiles -- station {station_code}, anchor {anchor_str}")
+    ax.legend(loc="best", fontsize=9)
+    ax.grid(True, alpha=0.3)
+    fig.tight_layout()
+    fig.savefig(output_path, dpi=150)
+    plt.close(fig)
+
+
+def plot_station_timeseries(
+    dates_list: list, real_observed: "object", predicted_median: "object", predicted_q95: "object",
+    naive_median: float, naive_q95: float, threshold: float, station_code: str, horizon: int,
+    output_path: Path,
+) -> None:
+    """
+    Real observed discharge, the model's real predicted median/0.95
+    quantile, and a real per-station naive baseline, all plotted
+    together across the real test period for one station at one fixed
+    horizon -- a direct, visual, station-specific complement to the
+    aggregate confusion-matrix metrics.
+
+    The naive baseline is a station-specific value (that station's own
+    real training-period empirical median/0.95), not the single global
+    naive baseline used for the overall skill percentage elsewhere in
+    this project -- a global naive value mixes together stations with
+    very different real flow scales, which would make this specific,
+    per-station comparison less meaningful, not more.
+
+    real_observed may be NaN on many real dates (only real gauges with
+    real observations ever have a value) -- plotted as a real, genuine
+    gap in the line via matplotlib's own NaN handling, not filled or
+    interpolated, since a filled gap would misrepresent what's actually
+    known versus not.
+    """
+    import matplotlib.pyplot as plt
+
+    fig, ax = plt.subplots(figsize=(12, 6))
+    ax.plot(dates_list, real_observed, color="#16a34a", linewidth=1.5, marker="o", markersize=3,
+            label="real observed discharge")
+    ax.plot(dates_list, predicted_median, color="#2563eb", linewidth=1.5, label="predicted median")
+    ax.plot(dates_list, predicted_q95, color="#dc2626", linewidth=1.5, label="predicted 0.95 quantile")
+    ax.axhline(naive_median, color="#2563eb", linestyle=":", linewidth=1.2, alpha=0.7,
+               label="naive baseline (station median)")
+    ax.axhline(naive_q95, color="#dc2626", linestyle=":", linewidth=1.2, alpha=0.7,
+               label="naive baseline (station 0.95)")
+    ax.axhline(threshold, color="#7c3aed", linestyle="--", linewidth=1.5, label="real station threshold")
+
+    ax.set_xlabel("Real target date")
+    ax.set_ylabel("Discharge (real L/s)")
+    ax.set_title(f"Station {station_code} -- real observed vs. predicted vs. naive baseline, horizon={horizon}d")
+    ax.legend(loc="best", fontsize=9)
+    ax.grid(True, alpha=0.3)
+    fig.autofmt_xdate()
+    fig.tight_layout()
+    fig.savefig(output_path, dpi=150)
+    plt.close(fig)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Evaluate flood-event detection against the trained model")
+    parser.add_argument("--data-root", type=Path, default=Path("datasets"))
+    parser.add_argument("--model-path", type=Path, default=None,
+                         help="Defaults to <data-root>/spatiotemporal_gnn/model.pt")
+    parser.add_argument("--events-path", type=Path, default=None,
+                         help="Defaults to <data-root>/flood_events_discharge.csv")
+    parser.add_argument("--lookback-days", type=int, default=30)
+    parser.add_argument("--train-end", type=str, default="2021-12-31")
+    parser.add_argument("--val-end", type=str, default="2023-12-31")
+    parser.add_argument("--test-end", type=str, default="2026-12-31")
+    parser.add_argument("--max-nodes", type=int, default=100)
+    parser.add_argument("--flag-quantile", type=float, default=0.95,
+                         help="Which of the model's predicted quantiles counts as a real flood flag, "
+                              "for any horizon not covered by --flag-quantile-overrides. Defaults to "
+                              "0.95, matching identify_flood_events.py's own default percentile "
+                              "threshold -- a coherent, matched comparison.")
+    parser.add_argument("--flag-quantile-overrides", type=str, default=None,
+                         help="Per-horizon overrides, format 'h1=q1,h2=q2,...', e.g. "
+                              "'1=0.9,2=0.9,3=0.9,4=0.9,5=0.9'. Real, measured evidence in this "
+                              "project shows the right operating point genuinely differs by horizon: "
+                              "at short horizons (1-5 days) here, a real predicted quantile is a real "
+                              "VALUE compared against a fixed real threshold -- since higher quantiles "
+                              "are, by the model's own monotonicity guarantee, always larger numbers, "
+                              "a HIGHER quantile makes the threshold EASIER to exceed, not harder (the "
+                              "opposite of what \"more confidence required\" might suggest). Lowering "
+                              "toward 0.9 measurably improved precision at short horizons in real "
+                              "testing (e.g. day 1: 63.8%% -> 67.9%%, day 5: 9.5%% -> 42.4%%) but "
+                              "collapsed recall to near-zero at longer horizons (day 30 recall hit "
+                              "0%% at 0.9, back when 30 was still a real predicted horizon -- HORIZONS "
+                              "has since been narrowed to max out at 21 days, but the real underlying "
+                              "finding stands) -- there's real evidence against one global value being "
+                              "right for every horizon. Horizons not listed here fall back to "
+                              "--flag-quantile.")
+    parser.add_argument("--check-fp-precipitation", action="store_true",
+                         help="Diagnostic: compares real recent precipitation (summed over the last "
+                              "ROUTING_HORIZON_COUNT real days of each example's own input window) "
+                              "across false positives vs. true negatives. Checked a real, specific "
+                              "hypothesis -- that water_balance_loss, with ET hardcoded to 0.0 and no "
+                              "storage term, has no way to represent real infiltration/storage "
+                              "absorbing part of a rain event, and may be pushing the model toward "
+                              "over-predicting discharge whenever real precipitation is high. Real "
+                              "result from actual testing: the difference was real but tiny (8.80mm "
+                              "vs 8.67mm mean, identical medians) -- too small to explain the real "
+                              "precision problem, and fp counts don't track precipitation the way "
+                              "they'd need to for this to be the main driver. Kept as a real, useful "
+                              "check for future runs, but this specific hypothesis is not well "
+                              "supported by the evidence so far -- see --check-quantile-spread for the "
+                              "hypothesis that superseded it.")
+    parser.add_argument("--check-quantile-spread", action="store_true",
+                         help="Diagnostic: reports the real, un-standardized gap between the model's "
+                              "predicted 0.95 and 0.5 (median) discharge quantiles, per horizon. Real "
+                              "result from actual clean testing (single global --flag-quantile, no "
+                              "per-horizon overrides -- an earlier run with overrides active was "
+                              "confounded, since switching the flagging quantile itself at the same "
+                              "horizon boundary being examined can't be cleanly separated from a real "
+                              "model-behavior effect): the spread grows smoothly and continuously with "
+                              "horizon (~1.3-1.5x per step throughout), but real false positives jump "
+                              "sharply at one specific point (day 4->5: 74->314 in one real run) that "
+                              "the smooth spread growth does NOT explain (day 4->5 spread only grew "
+                              "~1.3x, same as every other step) -- this specific hypothesis is NOT well "
+                              "supported by the real evidence. The real day 4->5 jump instead lines up "
+                              "with day 5 being one of the few horizons with real ECMWF forecast "
+                              "coverage while day 4 has none -- see --check-forecast-fp-correlation for "
+                              "the hypothesis that superseded this one.")
+    parser.add_argument("--check-forecast-fp-correlation", action="store_true",
+                         help="Diagnostic: for horizons with real ECMWF forecast coverage (currently "
+                              "[1,2,3,5,7], from FORECAST_LEAD_TIMES), reports what fraction of real "
+                              "false positives at that horizon had real (non-missing) forecast "
+                              "precipitation available, vs. the real base rate of forecast availability "
+                              "across every real example at that horizon. Real result from actual "
+                              "testing: a real but weak correlation (ratios 1.06-1.15x, all below the "
+                              "1.5x flag threshold) that does NOT single out day 5 specifically (day 1-3 "
+                              "showed similar ratios) -- this specific hypothesis is NOT well supported "
+                              "either. See --dump-fp-details for direct inspection of the real false "
+                              "positives themselves, which superseded this and the two hypotheses "
+                              "before it (--check-fp-precipitation, --check-quantile-spread).")
+    parser.add_argument("--dump-fp-details", type=int, default=None,
+                         help="Exploratory, not hypothesis-testing: dumps every real false positive at "
+                              "the given horizon (station, date, predicted value, real threshold, "
+                              "margin, days to the nearest real event) to a CSV, plus a quick printed "
+                              "summary -- for direct inspection after three real, specific mechanisms "
+                              "(precipitation, quantile-spread, forecast-availability) were each tested "
+                              "and none explained the sharp real fp jump at day 5. Pass the horizon to "
+                              "dump, e.g. '--dump-fp-details 5'.")
+    parser.add_argument("--dump-fp-output", type=Path, default=None,
+                         help="Defaults to <data-root>/fp_details_horizon_<h>.csv")
+    parser.add_argument("--plot-single-trace", type=str, default=None,
+                         help="Exploratory: plots one real (anchor, station) example's predicted "
+                              "discharge quantiles across all real horizons, with the station's real "
+                              "threshold and ROUTING_HORIZON_COUNT's boundary both marked -- a genuinely "
+                              "different check than the aggregate statistics tried so far (precipitation "
+                              "correlation, quantile-spread growth, forecast availability, forecast date "
+                              "alignment; none fully explained the real day-5 false-positive pattern). A "
+                              "visual discontinuity right at the physics-loss boundary would be "
+                              "immediately obvious here in a way an aggregate number isn't. Format: "
+                              "'station_code=anchor_date', e.g. 'H605641201=2026-01-01'.")
+    parser.add_argument("--plot-stations", type=str, default=None,
+                         help="Comma-separated real station codes, e.g. 'H605641201,H404021101' -- for "
+                              "each, plots real observed discharge, the model's real predicted median + "
+                              "0.95 quantile, and a real per-station naive baseline (that station's own "
+                              "training-period empirical median/0.95, not the global naive baseline used "
+                              "for the overall skill comparison -- a station-specific comparison is more "
+                              "meaningful here), all against real test-period dates, at one fixed "
+                              "horizon (--plot-stations-horizon).")
+    parser.add_argument("--plot-stations-horizon", type=int, default=1,
+                         help="Which real horizon to plot station time series at -- defaults to 1 (the "
+                              "horizon with the strongest real, established skill in this project).")
+    args = parser.parse_args()
+
+    model_path = args.model_path or (args.data_root / "spatiotemporal_gnn" / "model.pt")
+    events_path = args.events_path or (args.data_root / "flood_events_discharge.csv")
+
+    events_df = pd.read_csv(events_path)
+    if events_df.empty:
+        print(f"{events_path} has no real events -- run identify_flood_events.py first.")
+        return
+    event_lookup = build_event_lookup(events_df)
+    station_thresholds = build_station_thresholds(events_df)
+    print(f"Loaded {len(events_df)} real event(s) across {events_df['station_code'].nunique()} station(s)")
+
+    # Rebuilding the exact same real data pipeline the model was
+    # trained on -- same subgraph, same node ordering, same
+    # standardization statistics. The saved weights are only meaningful
+    # against these exact conditions.
+    max_nodes_per_basin = args.max_nodes // len(BASIN_FILE_NAMES)
+    basin_data = []
+    for basin_id, file_key in BASIN_FILE_NAMES.items():
+        nodes_df, edges_df = load_basin_graph(args.data_root, file_key)
+        nodes_df, edges_df = build_collapsed_subgraph(nodes_df, edges_df, max_nodes=max_nodes_per_basin)
+        basin_data.append((nodes_df, edges_df, basin_id))
+
+    # Must match train_spatiotemporal_gnn.py's own shared_static_cols/
+    # gauge_static_cols exactly -- the saved checkpoint's input layer
+    # shape is fixed to whatever these were at training time. A mismatch
+    # here isn't cosmetic; it's the same real shape-mismatch bug class
+    # already caught twice before in this file (estimated_discharge,
+    # dt_tensors).
+    shared_static_cols = ["elevation_m", "catchment_area_km2", "idpr_value",
+                          "avg_groundwater_level_m", "distance_to_nearest_cavity_km", "n_cavities_within_20km"]
+    gauge_static_cols: List[str] = []
+    combined = combine_basins(basin_data, shared_static_cols, gauge_static_cols)
+    station_codes = combined["station_codes"]
+
+    dynamic_tensors, target_tensor, waterlevel_target_tensor, dates = build_combined_dynamic_tensors(
+        combined, basin_data, args.data_root, ("2013-01-01", args.test_end)
+    )
+
+    # Mirrors train_spatiotemporal_gnn.py's main() exactly -- confirmed
+    # as a real, necessary fix, not an optional refinement: the saved
+    # checkpoint was trained with this channel present (added to
+    # main() several turns ago), and without replicating it here, the
+    # reconstructed model has 2 fewer input channels than the real
+    # checkpoint, causing a genuine shape-mismatch error on load. Same
+    # real reasoning as train_spatiotemporal_gnn.py's own version --
+    # see that file for the full explanation.
+    catchment_area_km2 = extract_catchment_area_km2(basin_data, combined)
+    n_real_catchment = int((~np.isnan(catchment_area_km2)).sum())
+    if "precipitation" in dynamic_tensors and n_real_catchment > 0:
+        try:
+            rolling_precip_sum = compute_rolling_precip_sum(dynamic_tensors["precipitation"], window_days=args.lookback_days)
+            specific_discharge_k = fit_specific_discharge_coefficient(
+                target_tensor, rolling_precip_sum, catchment_area_km2, dates, args.train_end,
+            )
+            estimated_discharge = estimate_discharge_from_precip(rolling_precip_sum, catchment_area_km2, specific_discharge_k)
+            dynamic_tensors["estimated_discharge"] = estimated_discharge
+        except ValueError:
+            pass  # matches train_spatiotemporal_gnn.py's own graceful skip
+
+    dynamic_tensors, target_tensor, waterlevel_target_tensor, standardization_stats = standardize_dynamic_tensors(
+        dynamic_tensors, target_tensor, waterlevel_target_tensor, dates, args.train_end,
+        optional_vars=["precipitation", "estimated_discharge"],
+    )
+    discharge_mean, discharge_std = standardization_stats["discharge"]
+
+    # Mirrors train_spatiotemporal_gnn.py's own dt_tensors construction
+    # exactly -- the real checkpoint was trained with this channel
+    # present, so reconstructing the model without it here would cause
+    # the same real shape-mismatch error found once already for
+    # estimated_discharge.
+    dt_tensors = {
+        var: compress_days_since_last_real(compute_days_since_last_real(tensor))
+        for var, tensor in dynamic_tensors.items()
+    }
+
+    # For the real precipitation/false-positive correlation check
+    # (--check-fp-precipitation): the real channel index and real
+    # un-standardization stats, captured here since var_names'
+    # insertion order (and channels_per_var=3, matching the real dt
+    # channel this project added) has to match prepare_graph_training_
+    # windows' own real channel layout exactly, or this would silently
+    # read the wrong channel entirely.
+    var_names_for_channels = list(dynamic_tensors.keys())
+    has_real_precip = "precipitation" in var_names_for_channels
+    if has_real_precip:
+        precip_value_idx, _ = get_dynamic_channel_index(var_names_for_channels, "precipitation", channels_per_var=3)
+        precip_mean, precip_std = standardization_stats["precipitation"]
+
+    X, Y, Y_mask, anchor_dates = prepare_graph_training_windows(
+        combined["x_shared_static"], dynamic_tensors, target_tensor, dates, args.lookback_days, HORIZONS,
+        dt_tensors=dt_tensors,
+    )
+
+    # Held-out test split only -- evaluating against data the model saw
+    # during training would overstate real skill, same principle as
+    # every other evaluation in this project.
+    anchor_dates_arr = pd.DatetimeIndex(anchor_dates)
+    test_mask = anchor_dates_arr > pd.Timestamp(args.val_end)
+    X_test, Y_test, anchor_dates_test = X[test_mask], Y[test_mask], [d for d, keep in zip(anchor_dates, test_mask) if keep]
+    print(f"Evaluating on {len(X_test)} real held-out test example(s)")
+
+    # Real forecasted precipitation for the test examples -- mirrors
+    # train_spatiotemporal_gnn.py's own wiring exactly, so this
+    # evaluation reflects the same inputs the model was actually
+    # trained with, not a stripped-down version of them.
+    forecast_csv_path = args.data_root / "previous_runs_forecast.csv"
+    if forecast_csv_path.exists():
+        nodes_df_combined = pd.DataFrame({"station_code": station_codes})
+        forecast_precip_test, forecast_missing_test = build_forecast_tensor(
+            nodes_df_combined, forecast_csv_path, anchor_dates_test, HORIZONS,
+        )
+        n_real_forecast = int((forecast_missing_test == 0.0).sum())
+        print(f"Real forecast precipitation available for {n_real_forecast} test (example, node, horizon) value(s)")
+    else:
+        forecast_precip_test = np.zeros((len(X_test), combined["n_nodes"], len(HORIZONS)), dtype=np.float32)
+        forecast_missing_test = np.ones((len(X_test), combined["n_nodes"], len(HORIZONS)), dtype=np.float32)
+        print("No real forecast archive found -- evaluating without forecast precipitation")
+
+    x_shared_static_std, _, shared_static_flagged = standardize_static_features(
+        combined["x_shared_static"], shared_static_cols,
+    )
+    x_gauge_static_std, _, gauge_static_flagged = standardize_static_features(
+        combined["x_gauge_static"], gauge_static_cols,
+    )
+    print(f"Static feature standardization: shared missingness flags for {shared_static_flagged or 'none'}, "
+          f"gauge missingness flags for {gauge_static_flagged or 'none'}")
+    x_shared_static_t = torch.tensor(x_shared_static_std, dtype=torch.float32)
+    x_gauge_static_t = torch.tensor(x_gauge_static_std, dtype=torch.float32)
+    is_gauged_t = torch.tensor(combined["is_gauged"], dtype=torch.bool)
+    edge_index_t = torch.tensor(combined["edge_index"], dtype=torch.long)
+    edge_attr_t = torch.tensor(combined["edge_attr"], dtype=torch.float32)
+    basin_id_t = torch.tensor(combined["basin_id"], dtype=torch.long)
+    horizons_t = torch.tensor(HORIZONS, dtype=torch.float32)
+
+    model = SpatiotemporalGNN(
+        shared_static_dim=x_shared_static_t.shape[1], gauge_static_dim=x_gauge_static_t.shape[1],
+        gauge_dynamic_dim=X.shape[-1], edge_dim=edge_attr_t.shape[1],
+        n_basins=len(BASIN_FILE_NAMES), n_targets=2, quantiles=QUANTILES,
+    )
+    model.load_state_dict(torch.load(model_path, map_location="cpu"))
+    model.eval()
+    print(f"Loaded trained model from {model_path}")
+
+    if args.flag_quantile not in QUANTILES:
+        print(f"--flag-quantile {args.flag_quantile} isn't one of the model's real predicted quantiles "
+              f"{QUANTILES} -- pick one of those.")
+        return
+    default_quantile_idx = QUANTILES.index(args.flag_quantile)
+
+    # Per-horizon quantile_idx map -- every horizon defaults to
+    # --flag-quantile's index, then real per-horizon overrides replace
+    # specific entries. Built as an explicit {horizon: idx} dict rather
+    # than a single shared value, since real testing in this project
+    # showed the right operating point genuinely differs by horizon
+    # (see --flag-quantile-overrides' own help text for the real numbers).
+    quantile_idx_by_horizon = {h: default_quantile_idx for h in HORIZONS}
+    if args.flag_quantile_overrides:
+        for pair in args.flag_quantile_overrides.split(","):
+            pair = pair.strip()
+            if not pair:
+                continue
+            try:
+                h_str, q_str = pair.split("=")
+                h_override, q_override = int(h_str), float(q_str)
+            except ValueError:
+                print(f"Couldn't parse override '{pair}' -- expected format 'horizon=quantile', e.g. '5=0.9'.")
+                return
+            if h_override not in HORIZONS:
+                print(f"Override horizon {h_override} isn't one of this model's real horizons {HORIZONS}.")
+                return
+            if q_override not in QUANTILES:
+                print(f"Override quantile {q_override} (for horizon {h_override}) isn't one of the "
+                      f"model's real predicted quantiles {QUANTILES} -- pick one of those.")
+                return
+            quantile_idx_by_horizon[h_override] = QUANTILES.index(q_override)
+
+    print(f"Flagging a real event when the model's predicted quantile exceeds that station's real "
+          f"threshold -- not the median, since flood risk is a tail question. Per-horizon quantile: "
+          f"{ {h: QUANTILES[idx] for h, idx in quantile_idx_by_horizon.items()} }")
+
+    # Confusion matrix per horizon: {horizon: {"tp":.., "fp":.., "fn":.., "tn":..}}
+    confusion = {h: {"tp": 0, "fp": 0, "fn": 0, "tn": 0} for h in HORIZONS}
+    fp_precip_values: List[float] = []
+    tn_precip_values: List[float] = []
+    # Real (0.95 - median) discharge spread, per horizon, across every
+    # real example and node regardless of tp/fp/fn/tn classification --
+    # unlike the precipitation check, this doesn't depend on the
+    # flagging outcome, so every real prediction contributes.
+    spread_by_horizon: Dict[int, List[float]] = {h: [] for h in HORIZONS}
+    if args.check_quantile_spread:
+        if 0.5 not in QUANTILES or 0.95 not in QUANTILES:
+            print("--check-quantile-spread needs both 0.5 and 0.95 in this model's real predicted "
+                  f"quantiles {QUANTILES} -- neither is missing normally, but checked defensively.")
+            args.check_quantile_spread = False
+        else:
+            median_idx, q95_idx = QUANTILES.index(0.5), QUANTILES.index(0.95)
+
+    requested_stations: List[str] = []
+    station_timeseries_data: Dict[str, Dict[str, list]] = {}
+    if args.plot_stations:
+        if 0.5 not in QUANTILES or 0.95 not in QUANTILES:
+            print("--plot-stations needs both 0.5 and 0.95 in this model's real predicted quantiles "
+                  f"{QUANTILES} -- neither is missing normally, but checked defensively.")
+        elif args.plot_stations_horizon not in HORIZONS:
+            print(f"--plot-stations-horizon {args.plot_stations_horizon} isn't one of this model's "
+                  f"real horizons {HORIZONS}.")
+        else:
+            requested_stations = [s.strip() for s in args.plot_stations.split(",") if s.strip()]
+            unknown = [s for s in requested_stations if s not in station_codes]
+            if unknown:
+                print(f"Station(s) {unknown} aren't real station codes in this run -- dropping them.")
+                requested_stations = [s for s in requested_stations if s in station_codes]
+            median_idx_ts, q95_idx_ts = QUANTILES.index(0.5), QUANTILES.index(0.95)
+            plot_horizon_idx = HORIZONS.index(args.plot_stations_horizon)
+            station_timeseries_data = {
+                code: {"dates": [], "observed": [], "median": [], "q95": []} for code in requested_stations
+            }
+
+    # {horizon: {"fp_with_forecast": n, "fp_without_forecast": n,
+    #            "all_with_forecast": n, "all_without_forecast": n}} --
+    # only meaningful for horizons in FORECAST_LEAD_TIMES, which is
+    # itself a real, direct subset of HORIZONS this project actually
+    # has real forecast coverage for.
+    forecast_fp_stats: Dict[int, Dict[str, int]] = {
+        h: {"fp_with_forecast": 0, "fp_without_forecast": 0, "all_with_forecast": 0, "all_without_forecast": 0}
+        for h in HORIZONS if h in FORECAST_LEAD_TIMES
+    }
+    fp_details: List[dict] = []
+    if args.dump_fp_details is not None and args.dump_fp_details not in HORIZONS:
+        print(f"--dump-fp-details {args.dump_fp_details} isn't one of this model's real horizons {HORIZONS}.")
+        return
+
+    with torch.no_grad():
+        for i in range(len(X_test)):
+            x_dynamic_seq = torch.tensor(X_test[i], dtype=torch.float32)
+            anchor = anchor_dates_test[i]
+            forecast_precip_i = torch.tensor(forecast_precip_test[i], dtype=torch.float32)
+            forecast_missing_i = torch.tensor(forecast_missing_test[i], dtype=torch.float32)
+            pred = model(x_shared_static_t, x_gauge_static_t, x_dynamic_seq, is_gauged_t,
+                         edge_index_t, edge_attr_t, basin_id_t, horizons_t,
+                         forecast_precip_i, forecast_missing_i)
+            # [n_nodes, n_horizons, n_quantiles] -- every predicted
+            # quantile, not just one: which specific quantile counts as
+            # "the flood flag" now genuinely varies by horizon (see
+            # quantile_idx_by_horizon), so the selection has to happen
+            # per-horizon below, not once for the whole tensor.
+            Q_pred_all_quantiles_standardized = pred[:, :, 0, :].numpy()
+            Q_pred_all_quantiles_real = Q_pred_all_quantiles_standardized * discharge_std + discharge_mean
+
+            if requested_stations:
+                # Real observed value at this specific (station, target
+                # date) -- Y_test is standardized the same way discharge
+                # predictions are, so the same real mean/std un-
+                # standardizes it correctly. NaN where no real
+                # observation exists, which plot_station_timeseries
+                # renders as a genuine gap, not a fabricated value.
+                target_date_ts = anchor + pd.Timedelta(days=args.plot_stations_horizon - 1)
+                Y_real_this_horizon = Y_test[i][:, plot_horizon_idx] * discharge_std + discharge_mean
+                for code in requested_stations:
+                    node_idx_ts = station_codes.index(code)
+                    station_timeseries_data[code]["dates"].append(target_date_ts)
+                    station_timeseries_data[code]["observed"].append(float(Y_real_this_horizon[node_idx_ts]))
+                    station_timeseries_data[code]["median"].append(
+                        float(Q_pred_all_quantiles_real[node_idx_ts, plot_horizon_idx, median_idx_ts]))
+                    station_timeseries_data[code]["q95"].append(
+                        float(Q_pred_all_quantiles_real[node_idx_ts, plot_horizon_idx, q95_idx_ts]))
+
+            if args.check_quantile_spread:
+                # Real, un-standardized spread -- computed once per
+                # example here (all horizons, all nodes), not inside the
+                # per-horizon flagging loop below, since this doesn't
+                # depend on any station threshold or event label at all.
+                spread_real = Q_pred_all_quantiles_real[:, :, q95_idx] - Q_pred_all_quantiles_real[:, :, median_idx]
+                for h_idx, h in enumerate(HORIZONS):
+                    spread_by_horizon[h].extend(spread_real[:, h_idx].tolist())
+
+            if args.check_fp_precipitation and has_real_precip:
+                # Real recent precipitation, per node, for THIS example's
+                # own input window -- one value per node, shared across
+                # every horizon below (the input window itself doesn't
+                # change with horizon, only the target date does), same
+                # ROUTING_HORIZON_COUNT-day real window water_balance_loss
+                # itself uses during training, not an arbitrarily chosen one.
+                recent_window = X_test[i][-ROUTING_HORIZON_COUNT:, :, precip_value_idx]  # [days, n_nodes], standardized
+                # Missing days were filled with 0.0 (standardized) at
+                # window-build time -- treating that as a real 0mm
+                # reading would be wrong (0 standardized un-standardizes
+                # to precip_mean, not to a real zero), but for a
+                # diagnostic sum specifically, filled-missing days
+                # contribute precip_mean each, a real, if imperfect,
+                # neutral fill rather than silently skewing the sum -- an
+                # acceptable simplification for a diagnostic, not
+                # something that would be acceptable inside the loss
+                # itself.
+                recent_precip_sum_real_per_node = recent_window.sum(axis=0) * precip_std + ROUTING_HORIZON_COUNT * precip_mean
+
+            for h_idx, h in enumerate(HORIZONS):
+                target_date = anchor + pd.Timedelta(days=h - 1)
+                quantile_idx = quantile_idx_by_horizon[h]
+                Q_pred_real_this_horizon = Q_pred_all_quantiles_real[:, h_idx, quantile_idx]
+                track_forecast_fp = args.check_forecast_fp_correlation and h in FORECAST_LEAD_TIMES
+                for node_idx, station_code in enumerate(station_codes):
+                    if station_code not in station_thresholds:
+                        continue  # no real threshold for this station at all -- nothing to evaluate
+
+                    threshold = station_thresholds[station_code]
+                    predicted_flag = Q_pred_real_this_horizon[node_idx] >= threshold
+                    is_event = is_real_event_day(station_code, target_date, event_lookup) is not None
+                    if track_forecast_fp:
+                        has_real_forecast = forecast_missing_test[i][node_idx, h_idx] == 0.0
+
+                    if is_event and predicted_flag:
+                        confusion[h]["tp"] += 1
+                    elif is_event and not predicted_flag:
+                        confusion[h]["fn"] += 1
+                    elif not is_event and predicted_flag:
+                        confusion[h]["fp"] += 1
+                        if args.check_fp_precipitation and has_real_precip:
+                            fp_precip_values.append(float(recent_precip_sum_real_per_node[node_idx]))
+                        if track_forecast_fp:
+                            key = "fp_with_forecast" if has_real_forecast else "fp_without_forecast"
+                            forecast_fp_stats[h][key] += 1
+                        if args.dump_fp_details == h:
+                            fp_details.append({
+                                "station_code": station_code,
+                                "target_date": target_date.date().isoformat(),
+                                "predicted_value": float(Q_pred_real_this_horizon[node_idx]),
+                                "threshold": float(threshold),
+                                "margin": float(Q_pred_real_this_horizon[node_idx] - threshold),
+                                "days_to_nearest_real_event": days_to_nearest_real_event(
+                                    station_code, target_date, event_lookup,
+                                ),
+                            })
+                    else:
+                        confusion[h]["tn"] += 1
+                        if args.check_fp_precipitation and has_real_precip:
+                            tn_precip_values.append(float(recent_precip_sum_real_per_node[node_idx]))
+
+                    if track_forecast_fp:
+                        key = "all_with_forecast" if has_real_forecast else "all_without_forecast"
+                        forecast_fp_stats[h][key] += 1
+
+    if requested_stations:
+        train_end_ts_ts = pd.Timestamp(args.train_end)
+        train_date_mask_ts = np.array([d <= train_end_ts_ts for d in dates])
+        print("\n" + "=" * 70)
+        print(f"Real station time-series plots, horizon={args.plot_stations_horizon}d")
+        print("=" * 70)
+        for code in requested_stations:
+            node_idx_ts = station_codes.index(code)
+            # Real, per-station naive baseline -- that station's own
+            # training-period empirical median/0.95 (real, un-
+            # standardized L/s), not the single global naive baseline
+            # used elsewhere for the overall skill percentage -- see
+            # plot_station_timeseries's own docstring for why a station-
+            # specific value is the more meaningful comparison here.
+            real_train_values = (target_tensor[node_idx_ts, train_date_mask_ts] * discharge_std
+                                  + discharge_mean)
+            real_train_values = real_train_values[~np.isnan(real_train_values)]
+            if len(real_train_values) == 0:
+                print(f"Station {code}: no real training-period observations at all -- skipping.")
+                continue
+            naive_median = float(np.quantile(real_train_values, 0.5))
+            naive_q95 = float(np.quantile(real_train_values, 0.95))
+            threshold = station_thresholds.get(code, float("nan"))
+
+            plot_path = args.data_root / f"station_timeseries_{code}_h{args.plot_stations_horizon}.png"
+            plot_station_timeseries(
+                station_timeseries_data[code]["dates"], station_timeseries_data[code]["observed"],
+                station_timeseries_data[code]["median"], station_timeseries_data[code]["q95"],
+                naive_median, naive_q95, threshold, code, args.plot_stations_horizon, plot_path,
+            )
+            print(f"Station {code}: saved to {plot_path} (naive median={naive_median:.1f}, "
+                  f"naive 0.95={naive_q95:.1f}, real threshold={threshold:.1f})")
+
+    if args.check_quantile_spread:
+        print("\n" + "=" * 70)
+        print("Real (0.95 - median) discharge quantile spread by horizon (real L/s)")
+        print("=" * 70)
+        fp_counts_by_horizon = {h: confusion[h]["fp"] for h in HORIZONS}
+        for h in HORIZONS:
+            values = spread_by_horizon[h]
+            if not values:
+                continue
+            arr = np.array(values)
+            print(f"horizon={h:>3}d: mean spread={arr.mean():>10.2f}, median spread={np.median(arr):>10.2f}, "
+                  f"real fp count={fp_counts_by_horizon[h]:>5}")
+        # A real, direct check of the actual hypothesis: does the
+        # spread's own growth track where false positives explode
+        # (day 5 -> day 10 in the real run that motivated this check),
+        # rather than just eyeballing two printed columns.
+        short_horizons = [h for h in HORIZONS if h <= 5 and spread_by_horizon[h]]
+        long_horizons = [h for h in HORIZONS if h > 5 and spread_by_horizon[h]]
+        if short_horizons and long_horizons:
+            short_mean_spread = np.mean([np.mean(spread_by_horizon[h]) for h in short_horizons])
+            long_mean_spread = np.mean([np.mean(spread_by_horizon[h]) for h in long_horizons])
+            ratio = long_mean_spread / short_mean_spread if short_mean_spread > 0 else float("inf")
+            print(f"\nMean spread, horizons <=5d: {short_mean_spread:.2f}; horizons >5d: {long_mean_spread:.2f} "
+                  f"(ratio: {ratio:.2f}x)")
+            if ratio > 2.0:
+                print(f"The real quantile spread grows substantially ({ratio:.2f}x) beyond day 5 -- "
+                      f"consistent with (not proof of) genuine hedging/calibration widening being the "
+                      f"real driver of the false-positive explosion at longer horizons, rather than a "
+                      f"precipitation-specific mechanism.")
+            else:
+                print(f"The real quantile spread does NOT grow substantially beyond day 5 ({ratio:.2f}x) "
+                      f"-- this specific hypothesis isn't well supported either; the real explanation "
+                      f"for the false-positive jump likely needs further investigation.")
+
+    if args.plot_single_trace:
+        try:
+            station_code_req, anchor_str = args.plot_single_trace.split("=")
+        except ValueError:
+            print(f"--plot-single-trace '{args.plot_single_trace}' isn't in the expected "
+                  f"'station_code=anchor_date' format.")
+            return
+        if station_code_req not in station_codes:
+            print(f"Station {station_code_req} isn't one of this run's real station codes.")
+            return
+        node_idx_req = station_codes.index(station_code_req)
+        anchor_req = pd.Timestamp(anchor_str)
+        matches = [i for i, a in enumerate(anchor_dates_test) if pd.Timestamp(a) == anchor_req]
+        if not matches:
+            print(f"Anchor date {anchor_str} isn't one of this run's real test anchor dates.")
+            return
+        i = matches[0]
+
+        with torch.no_grad():
+            x_dynamic_seq = torch.tensor(X_test[i], dtype=torch.float32)
+            forecast_precip_i = torch.tensor(forecast_precip_test[i], dtype=torch.float32)
+            forecast_missing_i = torch.tensor(forecast_missing_test[i], dtype=torch.float32)
+            pred = model(x_shared_static_t, x_gauge_static_t, x_dynamic_seq, is_gauged_t,
+                         edge_index_t, edge_attr_t, basin_id_t, horizons_t,
+                         forecast_precip_i, forecast_missing_i)
+            quantile_values_standardized = pred[node_idx_req, :, 0, :].numpy()  # [n_horizons, n_quantiles]
+            quantile_values_real = quantile_values_standardized * discharge_std + discharge_mean
+
+        threshold = station_thresholds.get(station_code_req, float("nan"))
+        trace_plot_path = args.data_root / f"single_trace_{station_code_req}_{anchor_str}.png"
+        plot_single_trace(HORIZONS, QUANTILES, quantile_values_real, threshold,
+                          ROUTING_HORIZON_COUNT, station_code_req, anchor_str, trace_plot_path)
+        print(f"\nSaved single-trace plot to {trace_plot_path}")
+        print(f"Real predicted values (real L/s), station={station_code_req}, anchor={anchor_str}:")
+        for h_idx, h in enumerate(HORIZONS):
+            row = ", ".join(f"q{q}={quantile_values_real[h_idx, q_idx]:.1f}" for q_idx, q in enumerate(QUANTILES))
+            print(f"  horizon={h:>3}d: {row}")
+
+    if args.dump_fp_details is not None:
+        h = args.dump_fp_details
+        print("\n" + "=" * 70)
+        print(f"Real false positive details at horizon={h}d (n={len(fp_details)})")
+        print("=" * 70)
+        if not fp_details:
+            print("No real false positives at this horizon -- nothing to dump.")
+        else:
+            fp_df = pd.DataFrame(fp_details)
+            output_path = args.dump_fp_output or (args.data_root / f"fp_details_horizon_{h}.csv")
+            fp_df.to_csv(output_path, index=False)
+            print(f"Saved to {output_path}")
+
+            print("\nReal false positive count by station:")
+            print(fp_df["station_code"].value_counts().to_string())
+
+            n_near_miss = int((fp_df["days_to_nearest_real_event"] <= 3).sum())
+            n_no_event_at_all = int(np.isinf(fp_df["days_to_nearest_real_event"]).sum())
+            print(f"\n{n_near_miss}/{len(fp_df)} real false positives are within 3 real days of an actual "
+                  f"real event (near-misses, not random noise); {n_no_event_at_all}/{len(fp_df)} are at "
+                  f"stations with no real event anywhere in the real record at all.")
+            print(f"\nReal date range of these false positives: "
+                  f"{fp_df['target_date'].min()} to {fp_df['target_date'].max()}")
+            print(f"Real margin (predicted - threshold) stats: mean={fp_df['margin'].mean():.2f}, "
+                  f"median={fp_df['margin'].median():.2f}, max={fp_df['margin'].max():.2f}")
+
+    if args.check_forecast_fp_correlation:
+        print("\n" + "=" * 70)
+        print("Real forecast availability: false positives vs. the real base rate, by horizon")
+        print("=" * 70)
+        if not forecast_fp_stats:
+            print(f"No requested horizons fall in FORECAST_LEAD_TIMES {FORECAST_LEAD_TIMES} -- nothing to check.")
+        for h, stats in forecast_fp_stats.items():
+            n_fp = stats["fp_with_forecast"] + stats["fp_without_forecast"]
+            n_all = stats["all_with_forecast"] + stats["all_without_forecast"]
+            if n_fp == 0 or n_all == 0:
+                print(f"horizon={h:>2}d: no real false positives or no real examples at all -- nothing to compare.")
+                continue
+            fp_forecast_rate = stats["fp_with_forecast"] / n_fp
+            base_forecast_rate = stats["all_with_forecast"] / n_all
+            print(f"horizon={h:>2}d: {fp_forecast_rate*100:.1f}% of real false positives had real forecast "
+                  f"data available, vs. {base_forecast_rate*100:.1f}% base rate across all real examples "
+                  f"(n_fp={n_fp}, n_all={n_all})")
+        # A real, direct verdict, not just printed numbers to eyeball --
+        # flags horizons where false positives are genuinely
+        # disproportionately drawn from forecast-available examples,
+        # not just nominally different by a small amount.
+        flagged_horizons = []
+        for h, stats in forecast_fp_stats.items():
+            n_fp = stats["fp_with_forecast"] + stats["fp_without_forecast"]
+            n_all = stats["all_with_forecast"] + stats["all_without_forecast"]
+            if n_fp == 0 or n_all == 0:
+                continue
+            fp_rate = stats["fp_with_forecast"] / n_fp
+            base_rate = stats["all_with_forecast"] / n_all
+            if base_rate > 0 and fp_rate / base_rate > 1.5:
+                flagged_horizons.append(h)
+        if flagged_horizons:
+            print(f"\nReal false positives are disproportionately drawn from forecast-available examples "
+                  f"at horizon(s) {flagged_horizons} -- real, direct evidence the forecast-conditioning "
+                  f"pathway itself is contributing to false positives there, not generic horizon-driven "
+                  f"hedging alone.")
+        else:
+            print(f"\nNo real horizon shows false positives disproportionately drawn from forecast-"
+                  f"available examples -- this specific hypothesis isn't well supported by this "
+                  f"real evidence either.")
+
+    if args.check_fp_precipitation:
+        if not has_real_precip:
+            print("\n--check-fp-precipitation requested, but no real precipitation channel is present "
+                  "in this run -- nothing to check.")
+        elif not fp_precip_values or not tn_precip_values:
+            print("\n--check-fp-precipitation requested, but there were no real false positives or no "
+                  "real true negatives to compare -- nothing to check.")
+        else:
+            fp_arr, tn_arr = np.array(fp_precip_values), np.array(tn_precip_values)
+            print("\n" + "=" * 70)
+            print(f"Real recent precipitation (mm, summed over the last {ROUTING_HORIZON_COUNT} real "
+                  f"days), false positives vs. true negatives")
+            print("=" * 70)
+            print(f"False positives (n={len(fp_arr)}): mean={fp_arr.mean():.2f}mm, median={np.median(fp_arr):.2f}mm")
+            print(f"True negatives  (n={len(tn_arr)}): mean={tn_arr.mean():.2f}mm, median={np.median(tn_arr):.2f}mm")
+            if fp_arr.mean() > tn_arr.mean():
+                print(f"False positives show real, higher recent precipitation on average "
+                      f"({fp_arr.mean():.2f}mm vs {tn_arr.mean():.2f}mm) -- consistent with (not proof "
+                      f"of) water_balance_loss's ET=0/no-storage gap pushing the model to over-predict "
+                      f"discharge whenever real precipitation is high.")
+            else:
+                print(f"False positives do NOT show higher recent precipitation than true negatives -- "
+                      f"this specific hypothesis isn't supported by this real evidence; the real "
+                      f"explanation for weak precision likely lies elsewhere.")
+
+    print("\n" + "=" * 70)
+    print("Flood-detection confusion matrix by lead time (real held-out test data)")
+    print("=" * 70)
+    rows = []
+    for h in HORIZONS:
+        c = confusion[h]
+        precision = c["tp"] / (c["tp"] + c["fp"]) if (c["tp"] + c["fp"]) > 0 else float("nan")
+        recall = c["tp"] / (c["tp"] + c["fn"]) if (c["tp"] + c["fn"]) > 0 else float("nan")
+        rows.append({"horizon_days": h, "tp": c["tp"], "fp": c["fp"], "fn": c["fn"], "tn": c["tn"],
+                     "precision": precision, "recall": recall})
+    result_df = pd.DataFrame(rows)
+    print(result_df.to_string(index=False))
+
+    output_path = args.data_root / "flood_detection_evaluation.csv"
+    result_df.to_csv(output_path, index=False)
+    print(f"\nSaved to {output_path}")
+
+    try:
+        confusion_plot_path = args.data_root / "flood_detection_confusion_matrices.png"
+        plot_confusion_matrices_by_horizon(confusion, HORIZONS, confusion_plot_path)
+        print(f"Saved confusion matrix grid to {confusion_plot_path}")
+
+        pr_plot_path = args.data_root / "flood_detection_precision_recall.png"
+        plot_precision_recall_by_horizon(result_df, pr_plot_path)
+        print(f"Saved precision/recall-vs-horizon plot to {pr_plot_path}")
+    except Exception as e:
+        print(f"  [warning] failed to save evaluation plots: {e}")
+
+
+if __name__ == "__main__":
+    main()

scripts/evaluation/identify_flood_events.py

@@ -0,0 +1,151 @@
+"""
+Identifies real historical high-flow events from discharge and
+water-level records, station by station. This is the ground truth
+against which any flood-prediction claim eventually has to be checked
+-- "beats a naive mean-baseline" and "would have flagged the real
+floods that actually happened" are different questions, and only the
+second one matters for this project's actual purpose.
+
+Threshold: each station's own historical 95th/99th percentile, not a
+shared absolute value across stations. These rivers have very
+different scales (median discharge ranges from under 1,000 to over
+9,000 L/s across real stations in this project), so a fixed absolute
+threshold would flag "high flow" at a small tributary while missing
+real extremes at a larger one. A station-relative threshold puts every
+station's real flood-scale events on the same footing.
+
+Events, not days: a real flood spans several consecutive days above
+threshold, and counting each day as a separate "event" would both
+inflate the count and obscure how long real high-flow periods actually
+last -- duration matters for anything downstream (evacuation windows,
+infrastructure impact), not just peak magnitude.
+
+Usage:
+    python -m scripts.identify_flood_events --data-root datasets
+"""
+import argparse
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+try:
+    from src.graph.dynamic_features import build_discharge_timeseries, build_waterlevel_timeseries
+except ImportError:
+    import sys
+    sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+    from src.graph.dynamic_features import build_discharge_timeseries, build_waterlevel_timeseries
+
+
+def find_events(series: pd.Series, threshold: float, min_duration_days: int = 1) -> pd.DataFrame:
+    """
+    Groups consecutive above-threshold days into discrete events for a
+    single station's real time series.
+
+    A gap of even one day below threshold ends the current event --
+    real recession rarely means the flow dropped and immediately rose
+    again, so treating a brief dip as "still the same event" would
+    understate how variable real hydrographs actually are.
+
+    Returns one row per event: start date, end date, duration, peak
+    value, peak date. Events shorter than min_duration_days are
+    dropped -- a single anomalous reading (a possible data error, or a
+    genuinely brief spike) is a different thing from a sustained high-
+    flow event, and conflating them would dilute what "event" means for
+    later evaluation.
+    """
+    above = series >= threshold
+    if not above.any():
+        return pd.DataFrame(columns=["start_date", "end_date", "duration_days", "peak_value", "peak_date"])
+
+    # Assign a group id that increments each time the series drops
+    # below threshold -- consecutive True values share a group.
+    group_id = (~above).cumsum()
+    events = []
+    for gid, group in series[above].groupby(group_id[above]):
+        duration = len(group)
+        if duration < min_duration_days:
+            continue
+        events.append({
+            "start_date": group.index.min(),
+            "end_date": group.index.max(),
+            "duration_days": duration,
+            "peak_value": group.max(),
+            "peak_date": group.idxmax(),
+        })
+    return pd.DataFrame(events)
+
+
+def identify_station_events(
+    wide: pd.DataFrame, percentile: float = 95.0, min_duration_days: int = 1,
+) -> pd.DataFrame:
+    """
+    Runs find_events for every station in a [date x station_code] wide
+    table, using each station's own real historical percentile as its
+    threshold. Stations with too little real data to compute a
+    meaningful percentile (fewer than 30 real observations, an
+    arbitrary but reasonable floor -- a percentile from a handful of
+    readings isn't a real threshold) are skipped, not given a
+    threshold computed from noise.
+    """
+    all_events = []
+    for station_code in wide.columns:
+        series = wide[station_code].dropna()
+        if len(series) < 30:
+            continue
+        threshold = np.percentile(series, percentile)
+        station_events = find_events(series, threshold, min_duration_days)
+        if station_events.empty:
+            continue
+        station_events["station_code"] = station_code
+        station_events["threshold"] = threshold
+        station_events["threshold_percentile"] = percentile
+        all_events.append(station_events)
+
+    if not all_events:
+        return pd.DataFrame(columns=["station_code", "start_date", "end_date", "duration_days",
+                                      "peak_value", "peak_date", "threshold", "threshold_percentile"])
+    return pd.concat(all_events, ignore_index=True).sort_values(["station_code", "start_date"])
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Identify real historical high-flow events")
+    parser.add_argument("--data-root", type=Path, default=Path("datasets"))
+    parser.add_argument("--stations-path", type=Path, default=None)
+    parser.add_argument("--start-date", type=str, default="2013-01-01")
+    parser.add_argument("--end-date", type=str, default="2026-12-31")
+    parser.add_argument("--percentile", type=float, default=95.0,
+                         help="Station-relative percentile defining the threshold for a high-flow day.")
+    parser.add_argument("--min-duration-days", type=int, default=1)
+    parser.add_argument("--output-dir", type=Path, default=None)
+    args = parser.parse_args()
+
+    stations_path = args.stations_path or (args.data_root / "station_elevations.csv")
+    nodes_df = pd.read_csv(stations_path)
+
+    date_range = (args.start_date, args.end_date)
+    output_dir = args.output_dir or args.data_root
+
+    discharge_wide = build_discharge_timeseries(nodes_df, args.data_root / "hydrometric", date_range)
+    discharge_events = identify_station_events(discharge_wide, args.percentile, args.min_duration_days)
+    print(f"Discharge: {len(discharge_events)} real event(s) across "
+          f"{discharge_events['station_code'].nunique() if not discharge_events.empty else 0} station(s)")
+    if not discharge_events.empty:
+        print(discharge_events.to_string(index=False))
+    discharge_out = output_dir / "flood_events_discharge.csv"
+    discharge_events.to_csv(discharge_out, index=False)
+    print(f"Saved to {discharge_out}\n")
+
+    waterlevel_wide = build_waterlevel_timeseries(nodes_df, args.data_root / "hydrometric", date_range)
+    waterlevel_events = identify_station_events(waterlevel_wide, args.percentile, args.min_duration_days)
+    print(f"Water level: {len(waterlevel_events)} real event(s) across "
+          f"{waterlevel_events['station_code'].nunique() if not waterlevel_events.empty else 0} station(s)")
+    if not waterlevel_events.empty:
+        print(waterlevel_events.to_string(index=False))
+    waterlevel_out = output_dir / "flood_events_waterlevel.csv"
+    waterlevel_events.to_csv(waterlevel_out, index=False)
+    print(f"Saved to {waterlevel_out}")
+
+
+if __name__ == "__main__":
+    main()

scripts/graph_building/build_dynamic_tensors.py

@@ -0,0 +1,117 @@
+"""
+Builds genuine [n_nodes, T] dynamic tensors (discharge, groundwater,
+climate) for a basin's reach graph and feeds them directly into
+physics_losses.py's routing_consistency_loss -- the actual integration
+point dynamic_features.py exists for. Without this script, that
+function has real inputs it could consume but nothing actually
+producing them.
+
+Usage:
+    python -m scripts.build_dynamic_tensors --data-root datasets --basin risle
+"""
+import argparse
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+try:
+    from src.graph.dynamic_features import (
+        build_discharge_timeseries, build_groundwater_timeseries,
+        build_climate_timeseries, assemble_dynamic_tensor,
+    )
+    from src.graph.physics_losses import build_routing_index, routing_consistency_loss
+except ImportError:
+    import sys
+    sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+    from src.graph.dynamic_features import (
+        build_discharge_timeseries, build_groundwater_timeseries,
+        build_climate_timeseries, assemble_dynamic_tensor,
+    )
+    from src.graph.physics_losses import build_routing_index, routing_consistency_loss
+
+BASIN_FILE_NAMES = {0: "eure", 1: "risle"}
+
+
+def run_for_basin(data_root: Path, basin_id: int, file_key: str, date_range, skip_climate: bool) -> None:
+    graph_dir = data_root / "reach_graph"
+    nodes_path = graph_dir / f"{file_key}_nodes_enriched.csv"
+    edges_path = graph_dir / f"{file_key}_edges.csv"
+    if not nodes_path.exists() or not edges_path.exists():
+        print(f"{file_key}: missing enriched nodes/edges -- run build_reach_graphs.py + "
+              f"enrich_reach_graph.py first. Skipping.")
+        return
+
+    nodes_df = pd.read_csv(nodes_path)
+    edges_df = pd.read_csv(edges_path)
+    print(f"--- {file_key}: {len(nodes_df)} nodes, {len(edges_df)} edges ---")
+
+    discharge_wide = build_discharge_timeseries(nodes_df, data_root / "hydrometric", date_range)
+    Q, dates = assemble_dynamic_tensor(nodes_df, discharge_wide)
+    n_real = int((~np.isnan(Q)).sum())
+    print(f"discharge tensor: {Q.shape}, {n_real}/{Q.size} real (non-NaN) values "
+          f"({100*n_real/Q.size:.3f}% coverage -- expect this to be tiny, only real "
+          f"gauges with real observations ever have a value here)")
+
+    level_wide, depth_wide = build_groundwater_timeseries(nodes_df, data_root / "ades", date_range)
+    level_tensor, _ = assemble_dynamic_tensor(nodes_df, level_wide)
+    depth_tensor, _ = assemble_dynamic_tensor(nodes_df, depth_wide)
+    print(f"groundwater level tensor: {level_tensor.shape}, "
+          f"{int((~np.isnan(level_tensor)).sum())} real values")
+
+    climate_tensors = {}
+    if not skip_climate and (data_root / "safran").exists():
+        try:
+            climate_dict = build_climate_timeseries(nodes_df, data_root / "safran", date_range)
+            for var, wide in climate_dict.items():
+                tensor, _ = assemble_dynamic_tensor(nodes_df, wide)
+                climate_tensors[var] = tensor
+            print(f"climate variables: {list(climate_tensors.keys())}")
+        except Exception as e:
+            print(f"climate skipped (error: {e})")
+
+    out_dir = graph_dir / "dynamic"
+    out_dir.mkdir(exist_ok=True)
+    save_kwargs = {
+        "discharge": Q, "groundwater_level": level_tensor, "groundwater_depth": depth_tensor,
+        "dates": np.array([str(d) for d in dates]), "station_codes": nodes_df["station_code"].values,
+    }
+    save_kwargs.update({f"climate_{k}": v for k, v in climate_tensors.items()})
+    out_path = out_dir / f"{file_key}_dynamic.npz"
+    np.savez(out_path, **save_kwargs)
+    print(f"saved to {out_path}")
+
+    # The actual integration: routing_consistency_loss needs Q + routing_index together.
+    routing_index = build_routing_index(nodes_df, edges_df, timestep_hours=24.0)
+    print(f"routing_index: {len(routing_index)} edge(s) with a usable lag at this timestep")
+
+    loss = routing_consistency_loss(Q, routing_index)
+    print(f"routing_consistency_loss on the REAL discharge tensor: {loss}")
+    if np.isnan(loss):
+        print("  ^ NaN. This is exactly the thing worth checking before assuming this loss "
+              "is usable: real Q is almost entirely NaN (only real gauges with real "
+              "observations have values), and if routing_consistency_loss doesn't mask "
+              "NaN out of its residuals before averaging, one missing value anywhere "
+              "poisons the entire loss to NaN. See whether this fired.")
+    print()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Build dynamic tensors and wire into physics_losses.py")
+    parser.add_argument("--data-root", type=Path, default=Path("datasets"))
+    parser.add_argument("--basin", choices=["eure", "risle", "both"], default="both")
+    parser.add_argument("--start-date", type=str, default="2013-01-01")
+    parser.add_argument("--end-date", type=str, default="2026-12-31")
+    parser.add_argument("--skip-climate", action="store_true")
+    args = parser.parse_args()
+
+    date_range = (args.start_date, args.end_date)
+    basins = BASIN_FILE_NAMES.items() if args.basin == "both" else \
+        [(k, v) for k, v in BASIN_FILE_NAMES.items() if v == args.basin]
+
+    for basin_id, file_key in basins:
+        run_for_basin(args.data_root, basin_id, file_key, date_range, args.skip_climate)
+
+
+if __name__ == "__main__":
+    main()

scripts/graph_building/build_reach_graphs.py

@@ -0,0 +1,188 @@
+"""
+Build the reach-based river network graph for both basins from real BD TOPO
+data, and report on every step so problems are visible immediately instead
+of surfacing later as a silent wrong answer downstream.
+
+Usage:
+    python -m scripts.build_reach_graphs --data-root datasets
+"""
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import pandas as pd
+
+try:
+    from src.graph.build_reach_graph import (
+        check_flow_direction_coverage, load_troncons_for_basin, build_node_link_digraph,
+        best_component_for_stations, snap_gauges_to_reach_graph, insert_virtual_nodes,
+        build_reach_graph_tables, summarize_confluences_by_tributary, TRIBUTARY_NAMES, normalize_toponym,
+    )
+    from src.data.loaders.station_elevations import StationElevationsLoader
+    from src.data.river_graph import assign_basin_id
+except ImportError:
+    sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+    from src.graph.build_reach_graph import (
+        check_flow_direction_coverage, load_troncons_for_basin, build_node_link_digraph,
+        best_component_for_stations, snap_gauges_to_reach_graph, insert_virtual_nodes,
+        build_reach_graph_tables, summarize_confluences_by_tributary, TRIBUTARY_NAMES, normalize_toponym,
+    )
+    from src.data.loaders.station_elevations import StationElevationsLoader
+    from src.data.river_graph import assign_basin_id
+
+BASIN_NAMES = {0: "La Eure", 1: "La Risle"}
+
+
+def run_for_basin(
+    troncon_geojson: dict,
+    stations_df: pd.DataFrame,
+    basin_id: int,
+    virtual_node_spacing_km: float,
+    anchor_radius_km: float,
+    component_search_radius_km: float,
+) -> "tuple[pd.DataFrame, pd.DataFrame] | None":
+    name = BASIN_NAMES[basin_id]
+    print("=" * 70)
+    print(f"{name}")
+    print("=" * 70)
+
+    basin_stations = stations_df[stations_df["basin_id"] == basin_id].copy()
+
+    matched = load_troncons_for_basin(
+        troncon_geojson, basin_id=basin_id,
+        anchor_stations=basin_stations, max_distance_from_anchor_km=anchor_radius_km,
+    )
+    print(f"Matched {len(matched)} tronçons by name AND within {anchor_radius_km} km of a "
+          f"real gauge (name-only matching pulled in geographically unrelated tronçons "
+          f"in earlier runs -- see build_reach_graph.py's load_troncons_for_basin docstring)")
+    if not matched:
+        print("  Nothing matched -- try a larger --anchor-radius-km, or check "
+              "TRIBUTARY_NAMES against this file's actual toponym values.")
+        return None
+
+    print()
+    print("Flow direction field coverage (sens_de_l_ecoulement), all matched tronçons:")
+    coverage = check_flow_direction_coverage(matched)
+    for value, count in sorted(coverage.items(), key=lambda x: -x[1]):
+        print(f"  {value!r}: {count}")
+    print("  If this doesn't show recognizable direction values, "
+          "build_node_link_digraph's sens_downstream_values/sens_upstream_values "
+          "need updating before its elevation fallback is the only thing working.")
+
+    print()
+    G, report = build_node_link_digraph(matched)
+    print(report)
+
+    n_known_tributaries = len(TRIBUTARY_NAMES.get(basin_id, [])) - 1  # exclude the main river itself
+    print(f"  ({n_known_tributaries} known named tributaries for this basin -- confluence count "
+          f"should be in this neighborhood, not far beyond it, if a tributary joins the main "
+          f"river roughly once)")
+    tributary_summary = summarize_confluences_by_tributary(G)
+    if not tributary_summary.empty:
+        counts = tributary_summary["joining_river"].value_counts()
+        print(f"  Confluences by joining river (post name-normalization): {dict(counts)}")
+        if len(counts) > n_known_tributaries + 3:  # some slack for real sub-tributary branching
+            print(f"  NOTE: more distinct joining-river names ({len(counts)}) than known "
+                  f"tributaries ({n_known_tributaries}) -- worth checking whether some of "
+                  f"these are actually the same river under yet another name variant "
+                  f"normalize_toponym doesn't catch, or genuinely unlisted tributaries.")
+
+    if report.disconnected_components > 1:
+        print(f"  {report.disconnected_components} component(s) found. Selecting by which "
+              f"one actually contains our real gauges, not by raw size -- the two aren't "
+              f"guaranteed to agree, and in earlier runs they didn't.")
+    G, gauge_counts = best_component_for_stations(G, basin_stations, search_radius_km=component_search_radius_km)
+    if len(gauge_counts) > 1:
+        sorted_counts = sorted(gauge_counts.values(), reverse=True)
+        print(f"  Gauges captured per component: {sorted_counts[:5]}{'...' if len(sorted_counts) > 5 else ''}")
+        if sorted_counts[0] < len(basin_stations):
+            print(f"  WARNING: the winning component only captures {sorted_counts[0]} of "
+                  f"{len(basin_stations)} gauges -- this basin's real network may still be "
+                  f"fragmented across more than one component even after the anchor filter.")
+
+    print()
+    print(f"Snapping {len(basin_stations)} real gauge(s) onto the reach graph...")
+    snapped = snap_gauges_to_reach_graph(G, basin_stations)
+    print(snapped[["station_code", "reach_u", "reach_v", "reach_fraction", "snap_distance_km"]]
+          .sort_values("snap_distance_km", ascending=False).to_string(index=False))
+    unsnapped = snapped["reach_u"].isna().sum()
+    if unsnapped:
+        print(f"  WARNING: {unsnapped} station(s) got no nearest edge at all -- "
+              f"they're likely outside this basin's matched tronçon set.")
+    large_snap = (snapped["snap_distance_km"] > 2.0).sum()
+    if large_snap:
+        print(f"  NOTE: {large_snap} station(s) snapped more than 2 km from any "
+              f"reach -- worth checking those aren't actually on an unmatched tributary.")
+
+    print()
+    G_virtual, n_inserted = insert_virtual_nodes(G, spacing_km=virtual_node_spacing_km)
+    print(f"Inserted {n_inserted} virtual node(s) at ~{virtual_node_spacing_km} km spacing "
+          f"({G.number_of_nodes()} real nodes -> {G_virtual.number_of_nodes()} total)")
+
+    print()
+    nodes_df, edges_df = build_reach_graph_tables(G_virtual, snapped, basin_id=basin_id)
+    n_confluences = int(nodes_df["is_confluence"].sum())
+    print(f"Final table: {len(nodes_df)} nodes ({nodes_df['is_gauged'].sum()} gauged, "
+          f"{n_confluences} confluences, {len(nodes_df) - nodes_df['is_gauged'].sum() - n_confluences} "
+          f"virtual/other), {len(edges_df)} edges")
+
+    return nodes_df, edges_df
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Build reach-based river network graphs")
+    parser.add_argument("--data-root", type=Path, default=Path("datasets"))
+    parser.add_argument("--virtual-node-spacing-km", type=float, default=5.0)
+    parser.add_argument("--anchor-radius-km", type=float, default=20.0,
+                         help="Max distance from a real gauge for a name-matched tronçon to be kept")
+    parser.add_argument("--component-search-radius-km", type=float, default=5.0,
+                         help="How close a gauge must be to a component to count as 'in' it")
+    parser.add_argument("--output-dir", type=Path, default=None,
+                         help="Defaults to <data-root>/reach_graph")
+    args = parser.parse_args()
+
+    troncon_path = args.data_root / "bdtopo_hydro" / "troncon_hydrographique.geojson"
+    if not troncon_path.exists():
+        print(f"Missing {troncon_path} -- run scripts/download_bdtopo_hydro.py first.")
+        sys.exit(1)
+    troncon_geojson = json.loads(troncon_path.read_text())
+
+    stations_df = StationElevationsLoader(data_path=args.data_root / "station_elevations.csv").load()
+    stations_df["basin_id"] = stations_df["station_code"].apply(assign_basin_id)
+    unmatched = stations_df["basin_id"].isna().sum()
+    if unmatched:
+        print(f"NOTE: {unmatched} station(s) matched no basin prefix and are excluded entirely.\n")
+    stations_df = stations_df.dropna(subset=["basin_id"])
+    stations_df["basin_id"] = stations_df["basin_id"].astype(int)
+
+    output_dir = args.output_dir or (args.data_root / "reach_graph")
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    all_nodes, all_edges = [], []
+    for basin_id, file_key in [(0, "eure"), (1, "risle")]:
+        result = run_for_basin(troncon_geojson, stations_df, basin_id, args.virtual_node_spacing_km,
+                                args.anchor_radius_km, args.component_search_radius_km)
+        print()
+        if result is None:
+            continue
+        nodes_df, edges_df = result
+        nodes_df.to_csv(output_dir / f"{file_key}_nodes.csv", index=False)
+        edges_df.to_csv(output_dir / f"{file_key}_edges.csv", index=False)
+        print(f"Saved {file_key}_nodes.csv / {file_key}_edges.csv to {output_dir}")
+        print()
+        all_nodes.append(nodes_df)
+        all_edges.append(edges_df)
+
+    if all_nodes:
+        print("=" * 70)
+        print("SUMMARY")
+        print("=" * 70)
+        combined_nodes = pd.concat(all_nodes, ignore_index=True)
+        combined_edges = pd.concat(all_edges, ignore_index=True)
+        print(f"Total: {len(combined_nodes)} nodes, {len(combined_edges)} edges across both basins")
+        print(f"Gauged: {combined_nodes['is_gauged'].sum()}")
+
+
+if __name__ == "__main__":
+    main()

scripts/graph_building/compute_cumulative_catchment.py

@@ -0,0 +1,208 @@
+"""
+Fills catchment_area_km2 for every reach graph node (confluences,
+splits, rejoins, virtual infill -- not just the ~8 real gauges Hub'Eau
+publishes it for), using BD TOPO's incremental catchment polygons
+(bassin_versant_topographique.geojson).
+
+ALGORITHM:
+  1. Spatially assign each incremental polygon to the edges it contains
+     (an edge's midpoint falling inside a polygon means that edge's
+     reach is the one that polygon's incremental drainage feeds).
+  2. For any node, cumulative catchment area = sum of the AREAS OF
+     DISTINCT POLYGONS among every edge upstream of it (walked via the
+     real directed graph, unbounded -- unlike the split/rejoin check's
+     15km search radius, catchment area needs the true full upstream
+     drainage, however far that extends). "Distinct" matters: many
+     edges (and the virtual nodes on them) share the same polygon, since
+     BD TOPO's confluence-to-confluence stretches are far coarser than
+     our node resolution -- summing per-edge would massively overcount.
+
+CAVEAT: the polygon assignment step needs geopandas, which isn't
+available in the environment this was developed in (no network access
+to install it). The graph-traversal/area-summation logic (the actual
+novel part) is tested with synthetic polygon assignments standing in
+for a real spatial join -- but the spatial join itself has not been run
+against real data. Please verify the polygon assignment step
+specifically (e.g. spot-check a few edges against the map) before
+trusting the final areas.
+
+Usage:
+    python -m scripts.compute_cumulative_catchment --data-root datasets
+"""
+import argparse
+import sys
+from pathlib import Path
+
+import networkx as nx
+import pandas as pd
+
+
+def assign_edges_to_polygons(edges_df: pd.DataFrame, nodes_df: pd.DataFrame, polygons_path: Path) -> pd.Series:
+    """
+    Spatial join: for each edge, which incremental catchment polygon
+    contains its midpoint. Returns a Series indexed like edges_df, with
+    the polygon's unique identifier (or NaN if no polygon contains it --
+    can happen near basin edges or bbox boundaries).
+
+    NEEDS geopandas -- not verified in the environment this was written
+    in, see module docstring.
+    """
+    import geopandas as gpd
+    from shapely.geometry import Point
+
+    polygons = gpd.read_file(polygons_path)
+    if "cleabs" in polygons.columns:
+        poly_id_col = "cleabs"
+    else:
+        polygons = polygons.reset_index().rename(columns={"index": "_poly_idx"})
+        poly_id_col = "_poly_idx"
+
+    coord = nodes_df.set_index("station_code")[["latitude", "longitude"]]
+    midpoints = []
+    for _, e in edges_df.iterrows():
+        try:
+            src, tgt = coord.loc[e["source"]], coord.loc[e["target"]]
+        except KeyError:
+            midpoints.append(None)
+            continue
+        midpoints.append(Point((src["longitude"] + tgt["longitude"]) / 2,
+                                (src["latitude"] + tgt["latitude"]) / 2))
+
+    edge_points = gpd.GeoDataFrame({"edge_idx": range(len(edges_df))}, geometry=midpoints, crs=polygons.crs)
+    joined = gpd.sjoin(edge_points.dropna(subset=["geometry"]), polygons[[poly_id_col, "geometry"]],
+                        how="left", predicate="within")
+    joined = joined.drop_duplicates("edge_idx")  # a midpoint exactly on a shared boundary could match >1 polygon
+
+    result = pd.Series(index=range(len(edges_df)), dtype=object)
+    result.loc[joined["edge_idx"]] = joined[poly_id_col].values
+    return result
+
+
+def compute_cumulative_catchment(
+    nodes_df: pd.DataFrame,
+    edges_df: pd.DataFrame,
+    edge_polygon_id: pd.Series,
+    polygon_areas: dict,
+) -> pd.Series:
+    """
+    For every node, sum the areas of distinct polygons among all edges
+    upstream of it (inclusive of the edge(s) arriving at the node
+    itself). Pure graph-traversal + arithmetic -- no geospatial
+    dependency, fully testable without geopandas (see the test in this
+    script's accompanying verification, or run this module's functions
+    directly against synthetic data).
+
+    Args:
+        nodes_df: reach graph nodes [station_code, ...]
+        edges_df: reach graph edges [source, target, ...], same row
+            order/index as edge_polygon_id.
+        edge_polygon_id: from assign_edges_to_polygons (or an equivalent
+            manually-built mapping for testing) -- polygon ID per edge,
+            aligned to edges_df's index.
+        polygon_areas: {polygon_id: area_km2}
+
+    Returns:
+        Series indexed like nodes_df, cumulative catchment area in km2
+        (NaN for a node with no upstream edges assigned to any polygon
+        at all -- a true headwater with no BD TOPO catchment coverage,
+        distinct from zero).
+    """
+    G = nx.DiGraph()
+    G.add_nodes_from(nodes_df["station_code"])
+    edge_to_poly = {}
+    for i, e in edges_df.iterrows():
+        G.add_edge(e["source"], e["target"])
+        poly = edge_polygon_id.get(i)
+        if pd.notna(poly):
+            edge_to_poly[(e["source"], e["target"])] = poly
+
+    results = {}
+    for node in nodes_df["station_code"]:
+        ancestors = nx.ancestors(G, node) | {node}
+        # every edge whose TARGET is in this node's ancestor-or-self set
+        # is an edge that feeds into this node's upstream drainage
+        polys_here = set()
+        for (u, v), poly in edge_to_poly.items():
+            if v in ancestors:
+                polys_here.add(poly)
+        if not polys_here:
+            results[node] = float("nan")
+        else:
+            results[node] = sum(polygon_areas.get(p, 0.0) for p in polys_here)
+
+    return pd.Series(results).reindex(nodes_df["station_code"])
+
+
+def run_for_basin(data_root: Path, basin_id: int, file_key: str) -> None:
+    graph_dir = data_root / "reach_graph"
+    enriched_path = graph_dir / f"{file_key}_nodes_enriched.csv"
+    edges_path = graph_dir / f"{file_key}_edges.csv"
+    polygons_path = data_root / "bdtopo_hydro" / "bassin_versant_topographique.geojson"
+
+    if not enriched_path.exists() or not edges_path.exists():
+        print(f"{file_key}: missing enriched nodes/edges, run build_reach_graphs.py + "
+              f"enrich_reach_graph.py first. Skipping.")
+        return
+    if not polygons_path.exists():
+        print(f"{file_key}: no {polygons_path} found -- run download_bdtopo_hydro.py first. Skipping.")
+        return
+
+    nodes_df = pd.read_csv(enriched_path)
+    edges_df = pd.read_csv(edges_path)
+    print(f"{file_key}: {len(nodes_df)} nodes, {len(edges_df)} edges")
+
+    try:
+        import geopandas as gpd
+    except ImportError:
+        print(f"{file_key}: geopandas not installed -- cannot do the spatial join. Skipping.")
+        return
+
+    polygons = gpd.read_file(polygons_path)
+    poly_id_col = "cleabs" if "cleabs" in polygons.columns else "_poly_idx"
+    if poly_id_col == "_poly_idx":
+        polygons = polygons.reset_index().rename(columns={"index": poly_id_col})
+    polygons_metric = polygons.to_crs(epsg=2154)
+    polygon_areas = dict(zip(polygons[poly_id_col], polygons_metric.geometry.area / 1e6))
+
+    edge_polygon_id = assign_edges_to_polygons(edges_df, nodes_df, polygons_path)
+    n_assigned = edge_polygon_id.notna().sum()
+    print(f"  {n_assigned}/{len(edges_df)} edges assigned to a polygon "
+          f"({len(edges_df) - n_assigned} unassigned -- near bbox/basin edges, expected)")
+
+    cumulative = compute_cumulative_catchment(nodes_df, edges_df, edge_polygon_id, polygon_areas)
+    nodes_df["cumulative_catchment_area_km2"] = cumulative.values
+
+    n_covered = nodes_df["cumulative_catchment_area_km2"].notna().sum()
+    print(f"  cumulative_catchment_area_km2 coverage: {n_covered}/{len(nodes_df)} nodes "
+          f"(vs. {nodes_df['catchment_area_km2'].notna().sum()} from Hub'Eau's own reported values)")
+
+    # Cross-check against Hub'Eau's real values where both exist, as a
+    # sanity check on the whole pipeline -- they measure different things
+    # (Hub'Eau: official gauge catchment; this: BD TOPO polygon sum) so
+    # exact agreement isn't expected, but they should be in the same
+    # ballpark for a real gauge, not off by an order of magnitude.
+    both = nodes_df.dropna(subset=["catchment_area_km2", "cumulative_catchment_area_km2"])
+    if not both.empty:
+        both = both.copy()
+        both["ratio"] = both["cumulative_catchment_area_km2"] / both["catchment_area_km2"]
+        print(f"  Cross-check vs Hub'Eau (real gauges only): ratio mean={both['ratio'].mean():.2f}, "
+              f"range=[{both['ratio'].min():.2f}, {both['ratio'].max():.2f}]")
+        print(both[["station_code", "catchment_area_km2", "cumulative_catchment_area_km2", "ratio"]]
+              .to_string(index=False))
+
+    nodes_df.to_csv(enriched_path, index=False)
+    print(f"  updated {enriched_path}")
+    print()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Compute cumulative catchment area from BD TOPO polygons")
+    parser.add_argument("--data-root", type=Path, default=Path("datasets"))
+    args = parser.parse_args()
+
+    for basin_id, file_key in [(0, "eure"), (1, "risle")]:
+        run_for_basin(args.data_root, basin_id, file_key)
+
+
+if __name__ == "__main__":
+    main()

scripts/graph_building/compute_edge_width.py

@@ -0,0 +1,109 @@
+"""
+Derives approximate channel width per real tronçon (river reach
+segment) from BD TOPO data already downloaded in this project --
+surface_hydrographique.geojson (real water-surface polygons) and
+troncon_hydrographique.geojson (real centerline geometry) -- no new
+data source needed.
+
+width_m = surface_polygon_area_m2 / troncon_length_m
+
+This is real, derivable channel geometry, not a full cross-sectional
+profile -- true cross-section (a real depth profile across the
+channel) needs bathymetric/LIDAR survey data, which hasn't been
+sourced or verified for this project. Width alone is still a
+physically meaningful hydraulic signal: it's the dominant term in
+Manning's-equation-style conveyance estimates, and the reason a wide
+shallow reach and a narrow deep one carry very different discharge for
+the same water level -- exactly the kind of physics a plain
+distance/elevation-drop edge attribute can't express on its own.
+
+Spatial join: each tronçon is matched to whichever real surface
+polygon its centerline geometry falls within (or, failing that, the
+nearest one within a small tolerance) -- a tronçon with no matching
+surface polygon at all gets width_m = NaN, not a fabricated default,
+since "no real surface polygon found" is meaningfully different from
+"the channel is zero-width."
+
+Usage:
+    python -m scripts.compute_edge_width --data-root datasets
+"""
+import argparse
+from pathlib import Path
+
+import geopandas as gpd
+import pandas as pd
+
+
+def compute_widths(troncons: gpd.GeoDataFrame, surfaces: gpd.GeoDataFrame) -> pd.DataFrame:
+    """
+    Real spatial join: for each tronçon, find the surface polygon(s) it
+    intersects, sum their real area (a tronçon can legitimately span
+    more than one mapped surface polygon), divide by real tronçon
+    length. Returns one row per tronçon with a real cleabs identifier
+    and width_m (NaN where no real surface polygon matched).
+    """
+    troncons = troncons.copy()
+    troncons["length_m"] = troncons.geometry.length
+
+    joined = gpd.sjoin(troncons[["cleabs", "length_m", "geometry"]], surfaces[["geometry"]],
+                        how="left", predicate="intersects")
+
+    area_by_troncon = surfaces.geometry.area
+    joined["surface_area_m2"] = joined["index_right"].map(
+        lambda idx: area_by_troncon.loc[idx] if pd.notna(idx) and idx in area_by_troncon.index else float("nan")
+    )
+
+    result = joined.groupby("cleabs").agg(
+        length_m=("length_m", "first"),
+        total_surface_area_m2=("surface_area_m2", lambda x: x.sum() if x.notna().any() else float("nan")),
+    ).reset_index()
+
+    result["width_m"] = result["total_surface_area_m2"] / result["length_m"]
+    n_matched = result["width_m"].notna().sum()
+    print(f"{n_matched}/{len(result)} real tronçon(s) matched to a real surface polygon "
+          f"({len(result) - n_matched} have no real surface data -- width_m will be NaN for those, not fabricated)")
+
+    return result[["cleabs", "length_m", "width_m"]]
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Derive real channel width from BD TOPO surface polygons")
+    parser.add_argument("--data-root", type=Path, default=Path("datasets"))
+    parser.add_argument("--output", type=Path, default=None)
+    args = parser.parse_args()
+
+    bdtopo_dir = args.data_root / "bdtopo_hydro"
+    troncons_path = bdtopo_dir / "troncon_hydrographique.geojson"
+    surfaces_path = bdtopo_dir / "surface_hydrographique.geojson"
+
+    if not troncons_path.exists() or not surfaces_path.exists():
+        print(f"Missing {troncons_path} or {surfaces_path} -- run download_bdtopo_hydro.py first.")
+        return
+
+    print(f"Loading real tronçons from {troncons_path}...")
+    troncons = gpd.read_file(troncons_path)
+    print(f"Loading real surface polygons from {surfaces_path}...")
+    surfaces = gpd.read_file(surfaces_path)
+    print(f"{len(troncons)} real tronçon(s), {len(surfaces)} real surface polygon(s)")
+
+    if troncons.crs != surfaces.crs:
+        print(f"CRS mismatch ({troncons.crs} vs {surfaces.crs}) -- reprojecting surfaces to match tronçons")
+        surfaces = surfaces.to_crs(troncons.crs)
+
+    widths = compute_widths(troncons, surfaces)
+
+    real_widths = widths["width_m"].dropna()
+    if len(real_widths) > 0:
+        print(f"\nReal width distribution: min={real_widths.min():.1f}m, median={real_widths.median():.1f}m, "
+              f"max={real_widths.max():.1f}m")
+        print("Sanity-check these against what you know of the real rivers before trusting them -- "
+              "an implausible max (e.g. hundreds of meters) usually means a tronçon matched an "
+              "unrelated, much larger surface polygon nearby, not a real channel width.")
+
+    output_path = args.output or (args.data_root / "edge_widths.csv")
+    widths.to_csv(output_path, index=False)
+    print(f"\nSaved to {output_path}")
+
+
+if __name__ == "__main__":
+    main()

scripts/graph_building/diagnose_confluences.py

@@ -0,0 +1,135 @@
+"""
+Diagnose the confluence count in a saved reach graph: real tributary
+junctions, or a data artifact (e.g. the same physical reach digitized
+twice, or a tile-boundary duplication in BD TOPO).
+
+Works two ways:
+  1. Against your EXISTING risle_nodes.csv/risle_edges.csv (no rerun
+     needed) -- checks whether each flagged confluence's incoming edges
+     have suspiciously similar distance_km/elevation_drop_m, which is
+     the signature of two near-identical tronçons rather than two
+     genuinely different ones.
+  2. Conclusively, once you rerun scripts/build_reach_graphs.py with the
+     cleabs fix -- if two incoming edges at the same node share the same
+     cleabs (tronçon ID), that's definitive: same tronçon counted twice,
+     not two different ones.
+
+Usage:
+    python -m scripts.diagnose_confluences --data-root datasets --basin risle
+"""
+import argparse
+from pathlib import Path
+
+import pandas as pd
+
+
+def diagnose(nodes_path: Path, edges_path: Path, n_samples: int = 10) -> None:
+    nodes_df = pd.read_csv(nodes_path)
+    edges_df = pd.read_csv(edges_path)
+
+    has_is_confluence = "is_confluence" in nodes_df.columns
+    has_toponym = "toponym" in edges_df.columns
+    has_cleabs = "cleabs" in edges_df.columns
+
+    if has_is_confluence:
+        confluence_codes = set(nodes_df[nodes_df["is_confluence"]]["station_code"])
+        confluences = edges_df[edges_df["target"].isin(confluence_codes)]["target"].value_counts()
+        raw_in_degree = edges_df["target"].value_counts()
+        raw_confluences = raw_in_degree[raw_in_degree >= 2]
+        print(f"{len(confluence_codes)} REAL confluence(s) -- different named river, independent "
+              f"upstream source, not a split that rejoins downstream -- out of "
+              f"{len(raw_confluences)} node(s) with raw in-degree >= 2 "
+              f"({len(nodes_df)} total nodes, {len(edges_df)} edges)")
+        print(f"  The gap ({len(raw_confluences) - len(confluence_codes)} nodes) is same-river "
+              f"segmentation and/or braided channels that split and rejoin -- both excluded "
+              f"from the count above, using the authoritative is_confluence column computed "
+              f"with full graph topology (this script can't re-derive the split-rejoin check "
+              f"from the flat CSV alone, which is exactly why that column exists).")
+    elif has_toponym:
+        name_counts = edges_df.dropna(subset=["toponym"]).groupby("target")["toponym"].nunique()
+        confluences = name_counts[name_counts > 1]
+        raw_in_degree = edges_df["target"].value_counts()
+        raw_confluences = raw_in_degree[raw_in_degree >= 2]
+        print(f"{len(confluences)} REAL confluence(s) (different named river actually joining), "
+              f"out of {len(raw_confluences)} node(s) with raw in-degree >= 2 "
+              f"({len(nodes_df)} total nodes, {len(edges_df)} edges)")
+        print(f"  The gap ({len(raw_confluences) - len(confluences)} nodes) is same-river fine "
+              f"tronçon segmentation, not real branching -- this is now excluded from the count.")
+        print("  NOTE: this file predates the split-rejoin fix (no is_confluence column) -- a "
+              "braided channel with differently-named branches that rejoin downstream would "
+              "still be miscounted here as a real confluence. Re-run "
+              "scripts/build_reach_graphs.py for the corrected count.")
+    else:
+        in_degree = edges_df["target"].value_counts()
+        confluences = in_degree[in_degree >= 2]
+        print(f"{len(confluences)} node(s) with in-degree >= 2, out of {len(nodes_df)} total nodes "
+              f"and {len(edges_df)} edges")
+        print()
+        print("NOTE: this edges.csv doesn't have a 'toponym' column -- it was generated before "
+              "the name-based confluence fix. Every number above uses the old, less reliable "
+              "in-degree >= 2 rule. Re-run scripts/build_reach_graphs.py for a corrected count "
+              "and for this script to give a definitive per-node answer instead of a proxy.")
+    print()
+
+    sample = confluences.head(n_samples)
+    n_confirmed_duplicate = 0
+    n_suspicious = 0
+
+    for node in sample.index:
+        incoming = edges_df[edges_df["target"] == node]
+        cols = ["source", "target", "distance_km", "elevation_drop_m"]
+        cols += [c for c in ("toponym", "cleabs") if c in incoming.columns]
+        print(f"Node {node}: {len(incoming)} incoming edge(s)")
+        print(incoming[cols].to_string(index=False))
+
+        if has_toponym:
+            n_names = incoming["toponym"].nunique()
+            if n_names > 1:
+                print(f"  -> REAL: {n_names} distinct named river(s) join here.")
+            else:
+                print(f"  -> Same toponym on every incoming edge -- not counted as a real "
+                      f"confluence (this shouldn't appear in the sample above; if it does, "
+                      f"something's inconsistent between this script and build_reach_graph.py).")
+        elif has_cleabs and incoming["cleabs"].notna().all():
+            if incoming["cleabs"].nunique() < len(incoming):
+                print("  -> CONFIRMED DUPLICATE: two+ incoming edges share the same cleabs "
+                      "(same physical tronçon counted more than once).")
+                n_confirmed_duplicate += 1
+        else:
+            dists = incoming["distance_km"].dropna()
+            if len(dists) >= 2 and (dists.max() - dists.min()) < 0.05:
+                print("  -> SUSPICIOUS: incoming edges have near-identical distance_km "
+                      "(within 50m) -- consistent with the same reach being counted twice, "
+                      "not two distinct tributaries joining.")
+                n_suspicious += 1
+        print()
+
+    print("=" * 60)
+    if has_toponym:
+        print(f"All {len(sample)} sampled nodes have >1 distinct named river joining -- "
+              f"that's the definition being used, so this should always be 100%. If any "
+              f"printed 'Same toponym' above, report it as a bug.")
+    elif has_cleabs:
+        print(f"Of {len(sample)} sampled confluences: {n_confirmed_duplicate} confirmed "
+              f"duplicate-tronçon artifacts, {len(sample) - n_confirmed_duplicate} have "
+              f"genuinely distinct incoming tronçons (real confluence candidates).")
+    else:
+        print(f"Of {len(sample)} sampled confluences: {n_suspicious} look suspicious "
+              f"(near-identical incoming edge distances). Re-run scripts/build_reach_graphs.py "
+              f"for a conclusive, name-based answer instead of this proxy signal.")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Diagnose reach-graph confluence counts")
+    parser.add_argument("--data-root", type=Path, default=Path("datasets"))
+    parser.add_argument("--basin", choices=["eure", "risle"], required=True)
+    parser.add_argument("--n-samples", type=int, default=10)
+    args = parser.parse_args()
+
+    graph_dir = args.data_root / "reach_graph"
+    diagnose(graph_dir / f"{args.basin}_nodes.csv", graph_dir / f"{args.basin}_edges.csv",
+              n_samples=args.n_samples)
+
+
+if __name__ == "__main__":
+    main()

scripts/graph_building/diagnose_persistence_baseline.py

@@ -0,0 +1,124 @@
+"""
+Diagnostic: adds a naive persistence baseline (tomorrow's anomaly =
+today's real anomaly, no model at all) to the climatology comparison,
+computed directly from real anomaly data -- no trained model needed.
+
+This exists specifically to distinguish two very different explanations
+for the anomaly model losing to climatology at short horizons:
+  (a) there's genuinely no learnable short-term signal beyond
+      climatology for that variable, or
+  (b) the model/training setup has a real problem, and even the
+      simplest possible non-climatology guess (yesterday's value)
+      would have beaten climatology if given the chance.
+
+If persistence beats climatology at h=1 but the trained model doesn't,
+that's a training/architecture issue, not a genuine predictability
+limit -- a very different, much more actionable finding.
+
+Usage:
+    python -m scripts.diagnose_persistence_baseline --data-root datasets \
+        --train-end 2023-12-31 --test-end 2026-12-31
+"""
+import argparse
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+try:
+    from src.graph.dynamic_features import build_climate_grid_timeseries
+    from src.graph.climate_climatology import fit_harmonic_climatology, compute_anomalies
+except ImportError:
+    import sys
+    sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+    from src.graph.dynamic_features import build_climate_grid_timeseries
+    from src.graph.climate_climatology import fit_harmonic_climatology, compute_anomalies
+
+DEFAULT_HORIZONS = [1, 5, 10, 30, 60, 90, 180]
+
+
+def evaluate_persistence(anomalies: pd.DataFrame, horizons: list) -> pd.DataFrame:
+    """
+    For every real (date, cell) anomaly value, compares:
+      - persistence_rmse: predicting that SAME day's anomaly repeated
+        forward h days (i.e. "nothing has changed since today")
+      - climatology_only_rmse: predicting zero anomaly (pure climatology)
+    against the REAL anomaly that actually occurred h days later.
+    Both computed only where the real target h days ahead exists.
+    """
+    values = anomalies.values
+    n_dates, n_cells = values.shape
+    rows = []
+
+    for h in horizons:
+        if h >= n_dates:
+            continue
+        today = values[:n_dates - h, :]
+        future = values[h:, :]
+        valid = ~np.isnan(today) & ~np.isnan(future)
+        if not valid.any():
+            continue
+        persistence_pred = today[valid]  # "tomorrow = today"
+        actual = future[valid]
+        persistence_rmse = np.sqrt(np.mean((persistence_pred - actual) ** 2))
+        climatology_rmse = np.sqrt(np.mean(actual ** 2))  # predicting anomaly = 0
+        rows.append({
+            "horizon_days": h, "n_pairs": int(valid.sum()),
+            "persistence_rmse": persistence_rmse, "climatology_only_rmse": climatology_rmse,
+            "persistence_beats_climatology": persistence_rmse < climatology_rmse,
+        })
+    return pd.DataFrame(rows)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Persistence-vs-climatology diagnostic")
+    parser.add_argument("--data-root", type=Path, default=Path("datasets"))
+    parser.add_argument("--stations-path", type=Path, default=None)
+    parser.add_argument("--bbox-margin-deg", type=float, default=0.3)
+    parser.add_argument("--train-start", type=str, default="2013-01-01")
+    parser.add_argument("--train-end", type=str, default="2023-12-31")
+    parser.add_argument("--test-end", type=str, default="2026-12-31")
+    parser.add_argument("--horizons", type=int, nargs="+", default=DEFAULT_HORIZONS)
+    parser.add_argument("--n-harmonics", type=int, default=2)
+    parser.add_argument("--min-months-covered", type=int, default=8)
+    args = parser.parse_args()
+
+    stations_path = args.stations_path or (args.data_root / "station_elevations.csv")
+    nodes_df = pd.read_csv(stations_path)
+    m = args.bbox_margin_deg
+    bbox = (nodes_df["longitude"].min() - m, nodes_df["latitude"].min() - m,
+            nodes_df["longitude"].max() + m, nodes_df["latitude"].max() + m)
+
+    print("Loading real ERA5 grid data...")
+    climate_dict, grid_coords = build_climate_grid_timeseries(
+        args.data_root / "safran", bbox, (args.train_start, args.test_end)
+    )
+    print(f"Loaded {len(climate_dict)} real variable(s) across {len(grid_coords)} real grid cell(s)\n")
+
+    train_start, train_end, test_end = (
+        pd.Timestamp(args.train_start), pd.Timestamp(args.train_end), pd.Timestamp(args.test_end)
+    )
+
+    print("=" * 80)
+    print(f"{'Variable':<15}{'Horizon':>8}  {'Persistence RMSE':>17}  {'Climatology RMSE':>17}  {'Persistence wins?':>18}")
+    print("=" * 80)
+
+    for var, wide in climate_dict.items():
+        train_wide = wide[(wide.index >= train_start) & (wide.index <= train_end)]
+        test_wide = wide[(wide.index > train_end) & (wide.index <= test_end)]
+
+        coeffs = fit_harmonic_climatology(train_wide, n_harmonics=args.n_harmonics,
+                                           min_months_covered=args.min_months_covered)
+        if not coeffs:
+            continue
+        test_anomalies = compute_anomalies(test_wide, coeffs, args.n_harmonics)
+        result = evaluate_persistence(test_anomalies, args.horizons)
+
+        for _, row in result.iterrows():
+            print(f"{var:<15}{int(row['horizon_days']):>8}  {row['persistence_rmse']:>17.4f}  "
+                  f"{row['climatology_only_rmse']:>17.4f}  {str(row['persistence_beats_climatology']):>18}")
+        print()
+
+
+if __name__ == "__main__":
+    main()

scripts/graph_building/enrich_reach_graph.py

@@ -0,0 +1,126 @@
+"""
+Enriches the reach graph's node tables (from scripts/build_reach_graphs.py)
+with every available feature loader, via node_features.py's base_nodes_df
+path -- closing the gap where the reach graph and the feature pipeline
+existed separately but nothing actually connected them.
+
+Usage:
+    python -m scripts.enrich_reach_graph --data-root datasets
+"""
+import argparse
+import sys
+from pathlib import Path
+
+import pandas as pd
+
+try:
+    from src.graph.node_features import build_node_features
+except ImportError:
+    sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+    from src.graph.node_features import build_node_features
+
+BASIN_FILE_NAMES = {0: "eure", 1: "risle"}
+
+
+def enrich_basin(
+    data_root: Path, basin_id: int, skip_climate: bool = False,
+    date_range: "tuple[str, str] | None" = None,
+) -> None:
+    file_key = BASIN_FILE_NAMES[basin_id]
+    graph_dir = data_root / "reach_graph"
+    nodes_path = graph_dir / f"{file_key}_nodes.csv"
+
+    if not nodes_path.exists():
+        print(f"{file_key}: no {nodes_path} found -- run scripts/build_reach_graphs.py first. Skipping.")
+        return
+
+    base_nodes = pd.read_csv(nodes_path)
+    print(f"{file_key}: {len(base_nodes)} nodes loaded from {nodes_path}")
+
+    enriched, report = build_node_features(
+        base_nodes_df=base_nodes,
+        idpr_path=data_root / "idpr.csv",
+        ades_path=data_root / "ades",
+        safran_path=None if skip_climate else data_root / "safran",
+        # --skip-climate exists specifically because add_safran_features has
+        # not been verified at reach-graph scale (~2,900 nodes) and is the
+        # prime suspect for a real hang there, unlike everything else in
+        # this pipeline which has been checked at this scale already (see
+        # add_groundwater_features's rewrite, which hit exactly this class
+        # of bug once before). Use this flag to get unblocked on everything
+        # else while that gets diagnosed with the real source.
+        catchment_path=data_root / "catchment_area.csv",
+        hydrometric_path=data_root / "hydrometric",
+        bdcavites_path=data_root / "bdcavites" / "cavite_localisee.geojson",
+        # Real, confirmed bug fix: this was never passed at all before,
+        # despite add_cavites_features and its real KD-tree/haversine
+        # logic being fully built and already generic over base_nodes_df
+        # -- the reach graph's ~4,500 nodes never got a real cavity
+        # feature purely because this one call site never wired it in,
+        # not because of any real gauge-only restriction in the feature
+        # code itself. Defaults to the "naturelle"-only filter inside
+        # add_cavites_features -- confirmed via scripts/analysis/
+        # check_cavity_proximity.py as the real, defensible choice
+        # (an unfiltered check found 24/27 real gauges within 1km of
+        # *some* cavity, dominated by quarries/civil structures with no
+        # hydrological meaning; "naturelle" is what actually indicates
+        # real karst connectivity).
+        date_range=date_range,
+        # Safe to include here, unlike an earlier version of this script
+        # assumed: target_* attaches via a left-merge on station_code,
+        # and real gauge codes ("H...") can never collide with BD TOPO
+        # hydrographic node IDs ("NOEUDHYD...") or virtual infill node
+        # IDs ("VIRTUAL::..."), confirmed against the real station code
+        # namespace -- so only real gauge rows ever get a real target
+        # value; every confluence/virtual node correctly gets NaN, not
+        # a mislabeled one.
+    )
+    print(report)
+
+    n_climate = enriched["climate_precip_mm"].notna().sum() if "climate_precip_mm" in enriched.columns else 0
+    n_catchment = enriched["catchment_area_km2"].notna().sum() if "catchment_area_km2" in enriched.columns else 0
+    n_targets = enriched["target_discharge_m3s_mean"].notna().sum() if "target_discharge_m3s_mean" in enriched.columns else 0
+    n_cavites = enriched["distance_to_nearest_cavity_km"].notna().sum() if "distance_to_nearest_cavity_km" in enriched.columns else 0
+    print(f"  climate coverage: {n_climate}/{len(enriched)} nodes")
+    print(f"  target (discharge) coverage: {n_targets}/{len(enriched)} nodes "
+          f"(expected: only real gauges -- {int(base_nodes['is_gauged'].sum())} in this basin)")
+    print(f"  catchment_area coverage: {n_catchment}/{len(enriched)} nodes "
+          f"(expected: only real gauges have one -- see node_features.py's "
+          f"add_catchment_features docstring; this is what water_balance_loss "
+          f"can actually use right now, everything else needs a cumulative "
+          f"catchment estimate this script doesn't build)")
+    print(f"  cavity proximity coverage: {n_cavites}/{len(enriched)} nodes "
+          f"(graph-wide, naturelle-only filter -- see add_cavites_features)")
+
+    out_path = graph_dir / f"{file_key}_nodes_enriched.csv"
+    enriched.to_csv(out_path, index=False)
+    print(f"  saved to {out_path}")
+    print()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Enrich reach graph nodes with feature loaders")
+    parser.add_argument("--data-root", type=Path, default=Path("datasets"))
+    parser.add_argument("--skip-climate", action="store_true",
+                         help="Skip SAFRAN/ERA5 climate features -- use if that step hangs at reach-graph scale")
+    parser.add_argument("--start-date", type=str, default="2013-01-01",
+                         help="Start of the training period (inclusive). Default 2013-01-01: the window "
+                              "maximizing discharge-gauge coverage (6/8 stations, 13,084 observations) -- "
+                              "see the date-range analysis this default came from before changing it.")
+    parser.add_argument("--end-date", type=str, default="2026-12-31",
+                         help="End of the training period (inclusive).")
+    parser.add_argument("--no-date-filter", action="store_true",
+                         help="Disable date filtering entirely -- each source uses its own full history")
+    args = parser.parse_args()
+
+    date_range = None if args.no_date_filter else (args.start_date, args.end_date)
+    if date_range:
+        print(f"Using date range: {date_range[0]} to {date_range[1]}")
+        print()
+
+    for basin_id in BASIN_FILE_NAMES:
+        enrich_basin(args.data_root, basin_id, skip_climate=args.skip_climate, date_range=date_range)
+
+
+if __name__ == "__main__":
+    main()