Upload folder using huggingface_hub

.gitattributes

@@ -213,3 +213,5 @@ datasets/bdcharm50/dept_061/GEO050K_HARM_061_P_STRUCT_2154.dbf filter=lfs diff=l
 datasets/bdcharm50/dept_061/GEO050K_HARM_061_S_FGEOL_2154.dbf filter=lfs diff=lfs merge=lfs -text
 datasets/bdcharm50/dept_061/GEO050K_HARM_061_S_FGEOL_2154.lyr filter=lfs diff=lfs merge=lfs -text
 datasets/bdcharm50/dept_061/GEO050K_HARM_061_S_FGEOL_2154.shp filter=lfs diff=lfs merge=lfs -text
+docs/images/eure_reach_graph.png filter=lfs diff=lfs merge=lfs -text
+docs/images/explore_view.png filter=lfs diff=lfs merge=lfs -text

README.md

@@ -72,9 +72,9 @@ PoC_v1/
 │   ├── enrich_reach_graph.py        # runs node_features.py against the reach graph
 │   ├── compute_cumulative_catchment.py  # graph-wide catchment area from BD TOPO polygons
 │   ├── diagnose_confluences.py      # verify real vs. artifact confluences
+│   ├── build_dynamic_tensors.py     # genuine [n_nodes, T] tensors, wired into physics_losses.py
 │   ├── download_bdcavites.py        # Géorisques BDCavités (sinkhole/cavity inventory)
 │   ├── download_bdcharm.py          # BRGM BD Charm-50 harmonized geology, per department
-│   ├── fetch_idpr_brgm.py           # (unused — see §3.5) live IDPR re-fetch attempt
 │   ├── fetch_landcover.py           # ESA WorldCover landcover class, real gauges
 │   └── fetch_worldcover_ndvi.py     # ESA WorldCover NDVI percentile composite
 │
@@ -103,8 +103,9 @@ PoC_v1/
 │   └── graph/
 │       ├── build_graph.py           # PyG conversion: x_static/x_dynamic split, structural columns
 │       ├── build_reach_graph.py     # real reach topology: confluences, splits/rejoins, MultiDiGraph
-│       ├── node_features.py         # pulls every loader into one feature table
-│       └── physics_losses.py        # confluence/split-rejoin/routing/water-balance loss terms
+│       ├── node_features.py         # pulls every loader into one feature table (static, one row/node)
+│       ├── dynamic_features.py      # genuine [n_nodes, T] series: discharge, groundwater, climate
+│       └── physics_losses.py        # confluence/split-rejoin/routing/water-balance loss terms, NaN-masked
 │
 ├── datasets/                    # not checked in; populated by the scripts above
 │   ├── station_list.csv             # raw station roster (X, Y, names, INSEE, etc.)
@@ -263,24 +264,55 @@ real gauge rows (verified: gauge codes, BD TOPO hydrographic node IDs, and
 virtual-node marker strings occupy structurally distinct namespaces, so a
 left-merge on `station_code` can never mislabel a confluence or virtual node).
 
-### 2.3 Static vs. dynamic features
+### 2.3 Static vs. dynamic features — and a real temporal pipeline
 
-`build_pyg_graph` also splits every feature by physical temporal nature:
+`build_pyg_graph` splits every feature by physical temporal nature:
 
 - **`data.x_static`** / **`data.static_feature_names`** — genuinely
-  time-invariant: elevation, IDPR, catchment area, landcover, coordinates.
+  time-invariant: elevation, IDPR, catchment area, landcover, geology,
+  cavité proximity, coordinates.
 - **`data.x_dynamic`** / **`data.dynamic_feature_names`** — physically
-  time-varying quantities: climate, groundwater level/depth, NDVI.
-
-`data.x` remains the full combined tensor unchanged; the split is additional,
-not a replacement. **Important limitation, stated plainly**: "dynamic" here
-still means *one period-aggregated number per node* (mean/sum over the whole
-date range, or a single well reading), not a real `[n_nodes, T]` time series.
-The split makes the physical distinction explicit and gives a clean seam for
-a future temporal pipeline to slot into, but building that pipeline — genuine
-daily/whatever-resolution series per node, aligned across sources — is
-separate, larger, unbuilt work. `physics_losses.py`'s `routing_consistency_loss`
-specifically needs that real time dimension and has nothing to consume yet.
+  time-varying quantities, still as a single period-aggregated number here
+  (mean/sum over the whole date range, or a latest well reading) — this
+  tensor is a *static snapshot* of dynamic-natured quantities, not a real
+  series. `data.x` remains the full combined tensor unchanged; the split is
+  additional, not a replacement.
+
+**A genuine `[n_nodes, T]` series exists separately**, in
+`src/graph/dynamic_features.py` — `build_discharge_timeseries`,
+`build_groundwater_timeseries`, `build_climate_timeseries` — built
+specifically because `physics_losses.py`'s `routing_consistency_loss` needs a
+real time dimension and had nothing to consume before this existed. Same
+loaders as everywhere else, no re-fetching; the only difference is that these
+functions pivot to wide `[date x station_code]` form instead of collapsing to
+one aggregate the way `node_features.py`'s `add_*_features` do.
+
+Two real challenges, not incidental engineering:
+
+- **Groundwater** reports on wildly irregular schedules (confirmed: 13
+  different "latest dates" among 18 real wells within 20 km of one station).
+  Each well is resampled to a common daily grid via forward-fill (a water
+  table changes slowly — carrying the last known reading forward is standard
+  practice, not an invented shortcut) *before* spatial averaging, not after —
+  averaging raw irregular readings per exact calendar date is exactly what
+  made the static version undercount real coverage by 5–10x before that was
+  fixed (§3.3). The spatial neighbor-set per node is computed once, reused
+  across every date — verified fast at real reach-graph scale (21.6s for
+  2,900 nodes × 14 years daily, real 272k-row ADES data).
+- **Discharge** deliberately does *not* get forward-filled the way
+  groundwater does — a missing daily reading stays missing, since discharge
+  genuinely changes day to day and papering over a gap with yesterday's
+  value would misrepresent it.
+
+`scripts/build_dynamic_tensors.py` is the actual wiring: builds these tensors
+for a basin, saves them, and feeds discharge directly into
+`routing_consistency_loss` alongside `build_routing_index` — the real
+integration point, not just parallel unconnected pieces.
+
+**Climate is untested against real data** — no real ERA5/`safran_path` files
+were available to validate `build_climate_timeseries` against in this
+project's development environment; the logic mirrors the already-tested
+discharge pivot directly, but verify the real output before trusting it.
 
 ### 2.4 Date-range filtering
 
@@ -312,7 +344,7 @@ Four constraints, each tied to real graph structure, not generic:
 |---|---|---|
 | `confluence_mass_balance_loss` | `Q_confluence ≈ sum(Q_upstream_branches)` — new mass genuinely enters | `is_confluence` nodes |
 | `split_rejoin_conservation_loss` | `Q_split ≈ Q_rejoin` — same water, no new mass | paired `braid_id` nodes |
-| `routing_consistency_loss` | `Q_downstream[t] ≈ Q_upstream[t - lag]`, lag from real `distance_km`/slope | every edge (needs `[n_nodes, T]` — see §2.3) |
+| `routing_consistency_loss` | `Q_downstream[t] ≈ Q_upstream[t - lag]`, lag from real `distance_km`/slope | every edge, real `[n_nodes, T]` via `dynamic_features.py` (§2.3) |
 | `water_balance_loss` | `P - ET - Q - ΔS ≈ 0` in volume terms | nodes with `cumulative_catchment_area_km2` |
 
 Confluence and split/rejoin are deliberately different constraints, not one
@@ -326,6 +358,27 @@ zero, a named steady-state approximation — this project has no direct
 basin-wide storage measurement, only sparse well *levels*, which aren't the
 same thing.
 
+**All four are NaN-masked, not just tolerant of complete data.** Real ground-
+truth Q is ~93.5% `NaN` by construction (only real gauges with real
+observations ever have a value — confirmed against the real discharge
+tensor) — that's the normal shape of the data, not a rare edge case. The
+shared `_mse` helper every loss function uses previously computed a plain
+mean, so a single `NaN` anywhere in a residual silently poisoned the *entire*
+loss to `NaN` — confirmed as a real, not hypothetical, failure: calling
+`routing_consistency_loss` directly on the real discharge tensor returned
+`NaN` before this was fixed. `_mse` now masks `NaN` out before averaging
+(returning `NaN` only if truly nothing usable exists at all, which is a
+real "no data" signal worth keeping, not silently averaging to a misleading
+`0`) — verified with the exact real scenario that first exposed the bug:
+`routing_consistency_loss` on the real discharge tensor now returns a real
+number instead of `NaN`.
+
+This also means these functions are directly usable as a diagnostic against
+real historical data alone, independent of any trained model — e.g.
+"does real observed discharge at two connected gauges actually satisfy the
+routing physics" — a genuine, model-free sanity check on both the physics
+math and the graph topology, not just a training-time loss term.
+
 ### 2.6 Two graphs, not one
 
 `build_pyg_graphs_per_basin()` returns `{0: eure_graph, 1: risle_graph}`,
@@ -346,6 +399,14 @@ count (verified fast at real scale: 0.29s to build a figure for ~2,900
 edges) — specifically for visually confirming the topology looks like a real
 river network before trusting it as model input.
 
+![La Risle reach graph — network validation view, real confluences as diamonds, gauges elevation-colored](docs/images/risle_reach_graph.png)
+
+
+![La Eure reach graph, same view](docs/images/eure_reach_graph.png)
+
+
+![Explore view: clicking along the river resolves to the nearest gauge and shows its real discharge/water-level/rating-curve plots](docs/images/explore_view.png)
+
 ---
 
 ## 3. Datasets
@@ -382,10 +443,7 @@ about:
 - Everything else with no data is unexplained from the name alone and worth a
   direct check on Hub'Eau's site before assuming it's just a gap.
 
-Of the 8 stations with any `QmnJ` discharge data at all, only **6 have real
-observations within the project's 2013–2026 date window** (§2.4) — worth
-knowing before assuming "8 gauged stations" translates directly into training
-examples.
+ 
 
 ### 3.2 Hydrometric data (`hydrometric/`, via `scripts/download_hubeau.py`)
 
@@ -467,24 +525,19 @@ call per file instead.
 
 BRGM's *Indice de Développement et de Persistance des Réseaux* — an
 infiltration-vs-runoff tendency index, and the closest thing this project has
-to a real soil/drainage covariate (see §3.9 for why it's standing in for soil
-data specifically, not just conveniently similar). The file used here is
-already one row per station (`station_id` matching `station_code` exactly,
-verified 1:1 against all 27 stations), so `node_features.py` does a direct ID
-join when possible rather than nearest-neighbor search, falling back to
-spatial nearest-neighbor for any station code that isn't an exact match
-(which is every non-gauge reach-graph node, and — a real, minor precision
-trade-off worth knowing — every gauge too, once the table also contains
-non-gauge codes, since the exact-match path requires the *entire* table to
-match IDPR's station list).
-
-A live re-fetch from BRGM's own geoservice (`scripts/fetch_idpr_brgm.py`,
-`geoservices.brgm.fr/geologie`, `GetFeatureInfo` point queries against the
-`IDPR_50M` raster layer) was attempted, to get fresher values and eventually
-cover the full reach graph rather than just the 27 gauges. **It failed** in
-testing and the project is currently using the original, already-uploaded
-`idpr.csv` instead — not resolved further, since the existing file already
-gives real, usable IDPR coverage for every gauge.
+to a real soil/drainage covariate. It's an *integrated hydrological behavior*
+indicator (infiltration tendency), not raw soil texture data, but arguably
+more directly useful for a streamflow model than a texture map would be on
+its own — paired with BD Charm-50 geology (§3.9) for the broader hydrological
+context soil data would otherwise provide. The file used here is already one
+row per station (`station_id` matching `station_code` exactly, verified 1:1
+against all 27 stations), so `node_features.py` does a direct ID join when
+possible rather than nearest-neighbor search, falling back to spatial
+nearest-neighbor for any station code that isn't an exact match (every
+non-gauge reach-graph node, and — a real, minor precision trade-off worth
+knowing — every gauge too, once the table also contains non-gauge codes,
+since the exact-match path requires the *entire* table to match IDPR's
+station list).
 
 ### 3.6 Catchment area — two independent sources
 
@@ -600,50 +653,24 @@ InfoTerre path.
 ### 3.10 Landcover and NDVI (`scripts/fetch_landcover.py`, `scripts/fetch_worldcover_ndvi.py`)
 
 ESA WorldCover, sampled at real gauge points from the public AWS S3 Cloud-
-Optimized GeoTIFFs — **not** the Terrascope WMS, which a source dated within
-the last month of this project's active development reported actively resets
-connections from non-browser HTTP clients (TLS fingerprinting, confirmed
-across multiple tools and User-Agents, not a coding problem to work around),
-and separately was slated for full phase-out already past by the time this
-was checked.
+Optimized GeoTIFFs.
 
 Landcover classification uses the product's 3°×3° tile grid; every real
 station coordinate falls inside exactly one tile (`N48E000`), verified
 directly against all 27 real coordinates. NDVI uses the *annual composites'*
 1°×1° tile grid instead — genuinely different from the classification grid,
 looked up per-station via VITO's own authoritative tile-index grid file
-(`esa_worldcover_grid_composites.fgb`) rather than a second hand-guessed S3
-key pattern. Both need `AWS_NO_SIGN_REQUEST=YES` for `s3://`-scheme tile URLs
+(`esa_worldcover_grid_composites.fgb`) rather than a hand-guessed S3 key
+pattern. Both need `AWS_NO_SIGN_REQUEST=YES` for `s3://`-scheme tile URLs
 specifically — a plain HTTPS URL to the same public bucket needs no signing
-at all, which is why the landcover script (HTTPS) worked without this while
-the NDVI grid's returned URLs (`s3://`) initially failed on AWS credential
-errors despite the bucket being fully public.
+at all.
 
 Both currently cover only the 27 real gauges (exact `station_code` match),
 same limitation as Hub'Eau's `catchment_area_km2` before the cumulative-BD-
 TOPO fix (§3.6) — extending either script to the full reach graph is
 unstarted work, not a design decision.
 
-### 3.11 What was tried and didn't work
-
-**SoilGrids (ISRIC)** — confirmed non-functional directly, not from a stale
-search result: even a bare `lon`/`lat` query to the live REST API returned
-`422` consistently, consistent with ISRIC's own currently-posted "temporarily
-paused" service notice.
-
-**INRAE's national soil survey (RRP/BDGSF)** — not a uniformly-accessible
-source at all. Access is explicitly described as depending on regional/
-departmental "référents" (varies by department, sometimes needs a formal
-agreement with the regional chamber of agriculture), and INRAE's own
-documentation states outright that the more detailed scale "n'est pas encore
-en accès libre." IDPR (§3.5) and BD Charm-50 geology (§3.9) are this
-project's actual substitutes for the hydrologically-relevant part of what
-soil data would otherwise provide — not literal soil texture data, but IDPR
-specifically is an *integrated hydrological behavior* indicator (infiltration
-tendency), arguably more directly useful for a streamflow model than a raw
-soil property map would be on its own.
-
-### 3.12 Centerline generation
+### 3.11 Centerline generation
 
 **Only relevant to the older single-chain pipeline** (`build_surface_edges`,
 still available for direct comparison/debugging) — the reach graph (§2)
@@ -751,7 +778,32 @@ pre-commit or CI gate if that's ever set up.
 
 ---
 
-## 6. Running things
+## 6. Known limitations and open questions
+
+- **`cumulative_catchment_area_km2` underestimates the largest catchments**
+  by up to ~25%, traced to the BD TOPO pull's original bounding box having an
+  insufficient southern margin. The bbox has been widened in
+  `download_bdtopo_hydro.py`; the full re-pull-and-rebuild chain needs
+  re-running for this to actually resolve. Treat the largest catchments'
+  values as approximate until then.
+- **Climate's genuine time series (`build_climate_timeseries`) is untested
+  against real data** — discharge and groundwater's equivalents are; verify
+  climate's real output before relying on it.
+- **Landcover and NDVI only cover the 27 real gauges**, not the full reach
+  graph — same scope `catchment_area_km2` had before its cumulative-BD-TOPO
+  extension.
+- **No model exists yet.** This repo builds the graph and the physics-loss
+  substrate a model would train against; there is no architecture, forward
+  pass, or training loop here.
+- **The karst losing-reach flag rests on naming evidence and a BDCavités
+  cross-check** (§3.7–3.8), not a fully confirmed BD TOPO classification.
+- **The groundwater-well BDLISA aquifer-unit field is unused.** First place
+  to look if a subsurface connectivity edge is ever justified with real
+  evidence rather than proximity.
+
+---
+
+## 7. Running things
 
 Data acquisition (from repo root, in roughly dependency order):
 
@@ -778,6 +830,13 @@ python -m scripts.diagnose_confluences --data-root datasets --basin eure
 python -m scripts.diagnose_confluences --data-root datasets --basin risle
 ```
 
+Build genuine `[n_nodes, T]` dynamic tensors and verify the physics-loss wiring:
+
+```bash
+python -m scripts.build_dynamic_tensors --data-root datasets --basin risle
+python -m scripts.build_dynamic_tensors --data-root datasets --basin eure
+```
+
 Landcover / NDVI, real gauges only (needs `rasterio`, and `geopandas` for NDVI's
 tile lookup):
 

datasets/README.md

@@ -0,0 +1,320 @@
+# Datasets Documentation
+
+**Project:** Physics-Informed KARST-Aware GNN for Streamflow Prediction
+**Study Area:** La Risle and La Eure River Systems, Seine Basin, France
+**Period:** 1960-2026 (historical data)
+
+## Directory Structure
+
+```
+datasets/
+├── station_list.csv                    # 27 stations metadata (coordinates, names)
+├── selected_stations.csv               # 27 selected station codes
+├── IDPR_values.csv                     # BRGM infiltration/runoff index (27 stations)
+├── ADES/                               # Groundwater data (KARST connectivity)
+│   ├── groundwater_stations.csv        # 114 groundwater monitoring wells
+│   ├── groundwater_levels_watershed.csv# 272,379 groundwater level measurements
+│   ├── stations_metadata.csv          # 10,001 stations (full ADES database)
+│   └── ADES_data_fetching.py          # Data collection script
+├── Watersehd_risle/                    # La Risle watershed boundary
+│   └── Watershed_Risle.shp            # Shapefile (EPSG:2154)
+├── Watershed_Eure/                     # La Eure watershed boundary
+│   └── Watershed_Eure.shp             # Shapefile (EPSG:2154)
+├── Risle_Eure_watershed/              # Merged watershed boundary
+│   └── Risle_Eure_Watershed.shp       # Combined shapefile (EPSG:2154)
+└── River Images/                       # Reference maps
+    ├── Carte-de-la_Seine-390x305.png
+    ├── Eure_(rivière).png
+    └── Risle.png
+```
+
+## Available Data
+
+### 1. Hydrometric Stations (`station_list.csv`)
+
+**File:** `station_list.csv`
+**Rows:** 27 stations
+**Columns:**
+- `X`, `Y` - Lambert 93 coordinates (EPSG:2154)
+- `station_code` - Unique station identifier (e.g., H602021010)
+- `region_name` - NORMANDIE
+- `departament_name` - ORNE or EURE
+- `station_name` - Full station name
+- `municipality` - Municipality name
+- `INSEE` - INSEE code
+- `id_root` - Root identifier
+- `lon`, `lat` - WGS84 coordinates
+- `lon-lat-ID` - Combined identifier
+
+**Basin Distribution:**
+- **La Risle:** 12 stations (e.g., La Risle à Rai, La Risle à Brionne, etc.)
+- **La Eure:** 13 stations (e.g., L'Eure à Chartres, L'Eure à Louviers, etc.)
+- **Tributary:** 1 station (Le bras de l'Eure à Lormaye)
+
+**Sample Stations:**
+```
+H602021010 - La Risle à Rai (48.749°N, 0.582°E)
+H605641401 - La Risle à Barquet (49.034°N, 0.808°E)
+H620021010 - La Risle à Brionne
+H4202010  - L'Eure à Chartres
+H4522010  - L'Eure à Louviers
+```
+
+### 2. Selected Stations (`selected_stations.csv`)
+
+**File:** `selected_stations.csv`
+**Rows:** 27 stations
+**Content:** List of selected station codes for analysis
+
+### 3. IDPR Data (`IDPR_values.csv`)
+
+**File:** `IDPR_values.csv`
+**Source:** BRGM (Bureau de Recherches Géologiques et Minières)
+**Rows:** 27 stations
+**Purpose:** Infiltration vs runoff tendency (KARST indicator)
+
+**Columns:**
+- `fid` - Feature ID
+- `X`, `Y` - Original coordinates
+- `X_lambert`, `Y_lambert` - Lambert 93 coordinates
+- `station_id` - Station identifier
+- `basin_name` - "La Risle" or "La Eure"
+- `latitude`, `longitude` - WGS84 coordinates
+- `IDPR` - **Infiltration Dominance vs Precipitation Runoff index**
+  - Higher values → More infiltration (karst behavior)
+  - Lower values → More surface runoff
+
+**IDPR Range in Dataset:**
+- La Risle: 885 - 2000
+- Indicates varying karst influence across the basin
+
+### 4. ADES Groundwater Data
+
+**Source:** ADES (Accès aux Données sur les Eaux Souterraines)
+**Purpose:** Karst groundwater connectivity, subsurface flow pathways
+
+#### 4.1 Groundwater Stations (`ADES/groundwater_stations.csv`)
+
+**Rows:** 114 groundwater monitoring wells in watershed
+**Columns:**
+- `code_bss` - BSS code (unique well identifier)
+- `urn_bss` - URN identifier
+- `date_debut_mesure`, `date_fin_mesure` - Measurement period
+- `code_commune_insee`, `nom_commune` - Municipality
+- `x`, `y` - Coordinates
+- `bss_id` - Short BSS ID
+- `altitude_station` - Well altitude (m)
+- `nb_mesures_piezo` - Number of piezometric measurements
+- `code_departement`, `nom_departement` - Department (61=Orne, 27=Eure)
+- `profondeur_investigation` - Investigation depth (m)
+
+**Sample Wells:**
+- BSS000TTRG (Le Mage, Orne) - 137 measurements, depth 38m, altitude 231m
+- BSS000TTRB (Longny les Villages) - 9 measurements, depth 55m, altitude 235m
+
+#### 4.2 Groundwater Levels (`ADES/groundwater_levels_watershed.csv`)
+
+**Rows:** 272,379 piezometric measurements
+**Period:** Various (e.g., 2013-present for some wells)
+**Columns:**
+- `code_bss`, `bss_id`, `urn_bss` - Well identifiers
+- `date_mesure` - Measurement date
+- `timestamp_mesure` - Unix timestamp
+- `niveau_nappe_eau` - Groundwater level (m above reference)
+- `profondeur_nappe` - Depth to water table (m below surface)
+- `mode_obtention` - Measurement method
+- `statut` - Data status ("Donnée contrôlée niveau 2")
+- `qualification` - Data quality ("Correcte", etc.)
+- `code_producteur`, `nom_producteur` - Data producer
+
+**Note:** This is time series data for groundwater levels, crucial for understanding subsurface karst connectivity.
+
+#### 4.3 ADES Metadata (`ADES/stations_metadata.csv`)
+
+**Rows:** 10,001 stations (full ADES database, not filtered)
+**Purpose:** Reference metadata for all groundwater stations in France
+
+### 5. Watershed Shapefiles
+
+#### 5.1 La Risle Watershed (`Watersehd_risle/Watershed_Risle.shp`)
+
+**CRS:** EPSG:2154 (Lambert 93 - French national projection)
+**Features:** 1 multipolygon
+**Attributes:**
+- `ID_INTERNE` - Internal ID (e.g., Sav21_226)
+- `ID_FONCTIO` - Functional ID
+- `NOM` - Watershed name
+- `SITUATION_` - Situation/status
+
+#### 5.2 La Eure Watershed (`Watershed_Eure/Watershed_Eure.shp`)
+
+**CRS:** EPSG:2154 (Lambert 93)
+**Features:** 1 multipolygon
+**Attributes:** Same as La Risle
+
+#### 5.3 Merged Watershed (`Risle_Eure_watershed/Risle_Eure_Watershed.shp`)
+
+**CRS:** EPSG:2154 (Lambert 93)
+**Features:** 1 multipolygon (merged boundary)
+**Attributes:**
+- `FID` - Feature ID
+- `geometry` - Geometry
+
+**Note:** This merged shapefile covers both La Risle and La Eure basins for basin-wide analysis.
+
+### Hydrometric Data (Hub'Eau API)
+
+**Status:** Downloaded and available datasets/hydrometric
+**Expected:** JSON and CSV files for 27 stations (1960-2026)
+
+**Historical Statistics (Daily/Monthly):**
+- `QmnJ` / `QmM` - Mean discharge (m³/s)
+- `QIXnJ` / `QIXM` - Maximum instantaneous discharge (m³/s)
+- `QINnJ` / `QINM` - Minimum instantaneous discharge (m³/s)
+- `HIXnJ` / `HIXM` - Maximum water level (m)
+
+**Real-Time Observations (5-min interval, ~1 month):**
+- `H` - Water level (m)
+- `Q` - River discharge (m³/s)
+
+### Meteorological Data (SAFRAN Reanalysis)
+
+**Status:** datasets/safran
+**Expected:** JSON and CSV files for 27 stations (1960-2026)
+
+**Variables (12):**
+- `DLI_Q` - Atmospheric radiation (W/m²)
+- `DRAINC_Q` - Drainage (mm)
+- `ETP_Q` - Potential evapotranspiration (mm)
+- `FF_Q` - Wind speed (m/s)
+- `HU_Q` - Relative humidity (%)
+- `PRELIQ_Q` - Liquid precipitation (mm)
+- `PRENEI_Q` - Solid precipitation (mm)
+- `RESR_NEIGE_Q` - Snowpack water equivalent (mm)
+- `RUNC_Q` - Runoff (mm)
+- `SSI_Q` - Visible radiation (W/m²)
+- `SWI_Q` - Soil moisture index
+- `T_Q` - Average air temperature (°C)
+
+### DEM and Topographic Data
+
+**Status:** datasets/station_elevations.csv
+**Required for:**
+- Elevation statistics (mean, min, max)
+- Basin slope calculation
+- Drainage density
+- Topographic Wetness Index (TWI)
+- River network topology extraction (QGIS hydrology tools)
+
+**Recommended Source:**
+- IGN RGE ALTI (French national DEM, 1m or 5m resolution)
+- EU-DEM (25m resolution)
+
+### River Network Topology
+
+**Status:** ❌ Not yet in repository
+**Required:** `station_edges.csv` for graph construction
+
+**Expected Format:**
+```csv
+source,target,distance,elevation_gradient,basin_id
+H602021010,H605641401,15.2,10.0,0
+H605641401,H620021010,12.5,-5.0,0
+...
+```
+
+**Generation Method:**
+- Use QGIS DEM hydrology processing tools
+- Extract upstream-downstream relationships
+- Calculate river distances and elevation gradients
+- Ensure no cross-basin edges (La Risle ≠ La Eure)
+
+### Basin Attributes (To Be Extracted)
+
+**Status:** ❌ Not yet extracted from shapefiles/DEM
+
+**Topological:**
+- Elevation, slope, drainage density, TWI, basin area
+
+**Soil Properties:**
+- Soil type, texture, hydraulic conductivity, porosity, depth
+
+**Land Use:**
+- Forest/agricultural/urban cover %, NDVI
+
+**Geological/KARST:**
+- Aquifer characteristics, lithology, permeability, sinkhole density
+
+## Data Processing Notes
+
+### Basin Assignment
+
+Based on station names in `station_list.csv`:
+
+**La Risle Stations (basin_id = 0):**
+- 12 stations with names starting with "La Risle"
+- Station codes: H60*, H62*
+
+**La Eure Stations (basin_id = 1):**
+- 13 stations with names starting with "L'Eure"
+- Station codes: H42*, H45*, H46*, H47*
+- Includes tributary: "Le bras de l'Eure"
+
+### Coordinate Systems
+
+**All geospatial data uses:**
+- **Projected:** EPSG:2154 (Lambert 93) for distances/areas
+- **Geographic:** EPSG:4326 (WGS84) for lat/lon
+
+**Conversion needed for:**
+- Station coordinates (already in both systems in `station_list.csv`)
+- Shapefiles (already in EPSG:2154)
+
+### Data Size Summary
+
+| File | Rows | Size | Notes |
+|------|------|------|-------|
+| `station_list.csv` | 27 | 4.1 KB | Station metadata |
+| `selected_stations.csv` | 27 | 338 B | Station codes only |
+| `IDPR_values.csv` | 27 | 2.6 KB | KARST infiltration index |
+| `ADES/groundwater_stations.csv` | 114 | ~50 KB | Groundwater wells |
+| `ADES/groundwater_levels_watershed.csv` | 272,379 | ~50 MB | **Large!** Time series |
+| `ADES/stations_metadata.csv` | 10,001 | ~2 MB | Full ADES database |
+
+**⚠️ Note:** `groundwater_levels_watershed.csv` is the largest file (272K rows). Use efficient processing (chunking, filtering by date range).
+
+## Next Steps
+
+1. **Collect Hydrometric Data**
+   - Use Hub'Eau API to download discharge/water level data
+   - Store in `datasets/hydrometric/` (JSON and CSV)
+
+2. **Collect SAFRAN Data**
+   - Download meteorological reanalysis for 27 station coordinates
+   - Store in `datasets/safran/` (JSON and CSV)
+
+3. **Acquire DEM**
+   - Download IGN RGE ALTI or EU-DEM for study area
+   - Store in `datasets/DEM/`
+
+4. **Extract River Topology**
+   - Use QGIS DEM hydrology tools
+   - Generate `datasets/station_edges.csv`
+
+5. **Extract Basin Attributes**
+   - Use DEM to calculate topological features
+   - Use soil/land use databases for additional features
+   - Store in `datasets/basin_features/`
+
+6. **Process Data Through Pipeline**
+   - Run `example_pipeline.py` once all data is available
+   - Generate fused datasets, graphs, and tensors
+
+## Data Sources & References
+
+- **Hub'Eau API:** https://hubeau.eaufrance.fr/
+- **SAFRAN Reanalysis:** Météo-France
+- **ADES:** https://ades.eaufrance.fr/ (groundwater data)
+- **BRGM IDPR:** Bureau de Recherches Géologiques et Minières
+- **IGN:** https://geoservices.ign.fr/ (DEM, elevation data)
+- **Watersheds:** Digitized from official French hydrographic boundaries