Upload folder using huggingface_hub

README.md

@@ -5,7 +5,7 @@ colorFrom: indigo
 colorTo: indigo
 sdk: gradio
 sdk_version: 5.47.0
-app_file: src/app.py
+app_file: src/gradio_app.py
 pinned: true
 ---
 

src/gradio_app.py

@@ -0,0 +1,477 @@
+import argparse
+import sys
+from pathlib import Path
+
+import gradio as gr
+import matplotlib.pyplot as plt
+import pandas as pd
+import plotly.graph_objects as go
+
+try:
+    from .data.loaders.station_elevations import StationElevationsLoader
+    from .data.loaders.ades import ADESLoader
+    from .data.loaders.hydrometric import HydrometricLoader
+    from .data.river_graph import build_basin_graph, _PALETTE
+    from .data.river_line import interpolate_along_chain, groundwater_at_point, RiverPoint
+    from .data.river_centerline import (
+        load_centerline, snap_gauges_to_centerline, cumulative_distance_km,
+        interpolate_by_fraction, elevation_at_km, resample_centerline_for_clicks,
+    )
+except ImportError:
+    sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+    from src.data.loaders.station_elevations import StationElevationsLoader
+    from src.data.loaders.ades import ADESLoader
+    from src.data.loaders.hydrometric import HydrometricLoader
+    from src.data.river_graph import build_basin_graph, _PALETTE
+    from src.data.river_line import interpolate_along_chain, groundwater_at_point, RiverPoint
+    from src.data.river_centerline import (
+        load_centerline, snap_gauges_to_centerline, cumulative_distance_km,
+        interpolate_by_fraction, elevation_at_km, resample_centerline_for_clicks,
+    )
+
+BASIN_NAMES = {0: "La Eure", 1: "La Risle"}
+BASIN_FILE_NAMES = {0: "eure", 1: "risle"}
+N_CLICK_TARGETS = 300
+
+
+def parse_data_root() -> Path:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--data-root", type=Path, default=Path("datasets"))
+    args, _ = parser.parse_known_args()
+    return args.data_root
+
+
+DATA_ROOT = parse_data_root()
+
+
+# --- Data Loaders (Cached via simple dictionaries/memoization) ---
+_cache = {}
+
+def get_graph(data_root: Path):
+    if "graph" not in _cache:
+        elev_df = StationElevationsLoader(data_path=data_root / "station_elevations.csv").load()
+        _cache["graph"] = build_basin_graph(elev_df)
+    return _cache["graph"]
+
+
+def get_centerlines(data_root: Path, nodes: pd.DataFrame):
+    key = "centerlines"
+    if key not in _cache:
+        result = {}
+        centerline_dir = data_root / "centerlines"
+        for basin_id, file_key in BASIN_FILE_NAMES.items():
+            csv_path = centerline_dir / f"{file_key}_centerline.csv"
+            if not csv_path.exists():
+                continue
+            cl = load_centerline(csv_path)
+            b_nodes = nodes[nodes["basin_id"] == basin_id]
+            gauges = snap_gauges_to_centerline(cl, b_nodes)
+            result[basin_id] = {
+                "centerline": cl,
+                "gauges": gauges,
+                "total_km": float(cumulative_distance_km(cl)[-1]),
+                "click_targets": resample_centerline_for_clicks(cl, gauges, n_points=N_CLICK_TARGETS),
+            }
+        _cache[key] = result
+    return _cache[key]
+
+
+def get_groundwater(data_root: Path):
+    key = "groundwater"
+    if key not in _cache:
+        ades_dir = data_root / "ades"
+        df = None
+        if ades_dir.exists():
+            try:
+                loaded_df = ADESLoader(data_path=ades_dir).load()
+                if {"lat", "lon", "groundwater_level_m"}.issubset(loaded_df.columns):
+                    df = loaded_df.sort_values("date").drop_duplicates("code_bss", keep="last")
+            except Exception:
+                pass
+        _cache[key] = df
+    return _cache[key]
+
+
+def get_hydrometric(data_root: Path):
+    key = "hydrometric"
+    if key not in _cache:
+        hydro_dir = data_root / "hydrometric"
+        res = None
+        if hydro_dir.exists():
+            try:
+                loader = HydrometricLoader(data_path=hydro_dir)
+                df = loader.load()
+                res = (loader, df)
+            except Exception:
+                pass
+        _cache[key] = res
+    return _cache[key]
+
+
+def schematic_click_targets(_nodes, _edges, basin_id: int, n_points: int = N_CLICK_TARGETS):
+    rows = []
+    for i in range(n_points):
+        frac = i / (n_points - 1)
+        p = interpolate_along_chain(_nodes, _edges, basin_id, frac)
+        rows.append({
+            "longitude": p.longitude, "latitude": p.latitude,
+            "elevation_m": p.elevation_m, "fraction": frac,
+            "upstream_station": p.upstream_station, "downstream_station": p.downstream_station,
+        })
+    return pd.DataFrame(rows)
+
+
+def load_reach_graph(data_root: Path, basin_id: int):
+    file_key = BASIN_FILE_NAMES[basin_id]
+    graph_dir = data_root / "reach_graph"
+    nodes_path = graph_dir / f"{file_key}_nodes.csv"
+    edges_path = graph_dir / f"{file_key}_edges.csv"
+    if not nodes_path.exists() or not edges_path.exists():
+        return None
+    return pd.read_csv(nodes_path), pd.read_csv(edges_path)
+
+
+# --- Plot Builders ---
+def build_figure_reach_graph(nodes_df: pd.DataFrame, edges_df: pd.DataFrame, basin_name: str, color: str) -> go.Figure:
+    lon_edges, lat_edges = [], []
+    node_lookup = nodes_df.set_index("station_code")[["latitude", "longitude"]]
+    for _, e in edges_df.iterrows():
+        try:
+            src, tgt = node_lookup.loc[e["source"]], node_lookup.loc[e["target"]]
+        except KeyError:
+            continue
+        lon_edges += [src["longitude"], tgt["longitude"], None]
+        lat_edges += [src["latitude"], tgt["latitude"], None]
+
+    if "is_confluence" in nodes_df.columns:
+        confluences = nodes_df[nodes_df["is_confluence"]]
+    elif "toponym" in edges_df.columns:
+        name_counts = edges_df.dropna(subset=["toponym"]).groupby("target")["toponym"].nunique()
+        confluence_codes = name_counts[name_counts > 1].index
+        confluences = nodes_df[nodes_df["station_code"].isin(confluence_codes)]
+    else:
+        confluence_codes = edges_df["target"].value_counts()
+        confluence_codes = confluence_codes[confluence_codes >= 2].index
+        confluences = nodes_df[nodes_df["station_code"].isin(confluence_codes)]
+    gauges = nodes_df[nodes_df["is_gauged"]]
+
+    fig = go.Figure()
+    fig.add_trace(go.Scatter(
+        x=lon_edges, y=lat_edges, mode="lines",
+        line=dict(color=color, width=1), hoverinfo="skip", showlegend=False,
+    ))
+    fig.add_trace(go.Scatter(
+        x=confluences["longitude"], y=confluences["latitude"], mode="markers",
+        marker=dict(symbol="diamond", size=7, color="#8A8F87", line=dict(width=0.5, color="#5B6B63")),
+        customdata=confluences["station_code"],
+        hovertemplate="confluence %{customdata}<extra></extra>",
+        name=f"confluences (n={len(confluences)})", showlegend=True,
+    ))
+    fig.add_trace(go.Scatter(
+        x=gauges["longitude"], y=gauges["latitude"], mode="markers+text",
+        marker=dict(symbol="circle", size=11, color=gauges["elevation_m"], colorscale="earth",
+                    line=dict(width=1, color="black"), showscale=True, colorbar=dict(title="Elev (m)", thickness=12)),
+        text=gauges["station_code"], textposition="top right", textfont=dict(size=8),
+        customdata=gauges["station_code"],
+        hovertemplate="%{customdata}<extra></extra>",
+        name=f"gauges (n={len(gauges)})", showlegend=True,
+    ))
+    fig.update_layout(
+        title=f"{basin_name} — reach graph ({len(nodes_df)} nodes, {len(edges_df)} edges)",
+        xaxis_title="Longitude", yaxis_title="Latitude",
+        yaxis=dict(scaleanchor="x", scaleratio=1),
+        height=650, margin=dict(l=10, r=10, t=40, b=10),
+        legend=dict(orientation="h", y=-0.08),
+    )
+    return fig
+
+
+def build_figure_real(info, basin_name: str, color: str, wells_df=None, marker_lon=None, marker_lat=None) -> go.Figure:
+    cl, gauges, targets = info["centerline"], info["gauges"], info["click_targets"]
+    fig = go.Figure()
+    fig.add_trace(go.Scatter(
+        x=cl["longitude"], y=cl["latitude"], mode="lines",
+        line=dict(color=color, width=3), hoverinfo="skip", showlegend=False,
+    ))
+    fig.add_trace(go.Scatter(
+        x=targets["longitude"], y=targets["latitude"], mode="markers",
+        marker=dict(size=10, color=color, opacity=0.01),
+        customdata=targets[["distance_from_mouth_km", "elevation_m"]].values,
+        hovertemplate="%{customdata[0]:.1f} km from mouth<br>elev %{customdata[1]:.0f} m<extra></extra>",
+        showlegend=False, name="river",
+    ))
+    if wells_df is not None and not wells_df.empty:
+        fig.add_trace(go.Scatter(
+            x=wells_df["lon"], y=wells_df["lat"], mode="markers",
+            marker=dict(size=6, color="#8A8F87", opacity=0.55, line=dict(width=0.5, color="#5B6B63")),
+            customdata=wells_df[["code_bss", "groundwater_level_m"]].values,
+            hovertemplate="well %{customdata[0]}<br>%{customdata[1]:.1f} m<extra></extra>",
+            showlegend=True, name=f"ADES wells (n={len(wells_df)})",
+        ))
+    fig.add_trace(go.Scatter(
+        x=gauges["centerline_lon"], y=gauges["centerline_lat"], mode="markers+text",
+        marker=dict(size=12, color=gauges["elevation_m"], colorscale="earth",
+                    line=dict(width=1, color="black"), showscale=True, colorbar=dict(title="Elev (m)", thickness=12)),
+        text=gauges["station_code"], textposition="top right", textfont=dict(size=9),
+        customdata=gauges[["centerline_km", "elevation_m"]].values,
+        hovertemplate="%{text}<br>%{customdata[0]:.1f} km<br>elev %{customdata[1]:.0f} m<extra></extra>",
+        showlegend=False, name="gauges",
+    ))
+    if marker_lon is not None:
+        fig.add_trace(go.Scatter(
+            x=[marker_lon], y=[marker_lat], mode="markers",
+            marker=dict(size=16, color="#C98A28", line=dict(width=2, color="white")),
+            hoverinfo="skip", showlegend=False,
+        ))
+    fig.update_layout(
+        title=f"{basin_name} — click the line",
+        xaxis_title="Longitude", yaxis_title="Latitude",
+        yaxis=dict(scaleanchor="x", scaleratio=1),
+        height=520, margin=dict(l=10, r=10, t=40, b=10),
+        legend=dict(orientation="h", y=-0.12),
+    )
+    return fig
+
+
+def build_figure_schematic(targets, basin_name: str, color: str, marker_x=None, marker_y=None) -> go.Figure:
+    fig = go.Figure()
+    fig.add_trace(go.Scatter(
+        x=list(range(len(targets))), y=targets["elevation_m"], mode="lines",
+        line=dict(color=color, width=3), hoverinfo="skip", showlegend=False,
+    ))
+    fig.add_trace(go.Scatter(
+        x=list(range(len(targets))), y=targets["elevation_m"], mode="markers",
+        marker=dict(size=10, color=color, opacity=0.01),
+        customdata=targets[["fraction", "elevation_m"]].values,
+        hovertemplate="%{customdata[1]:.0f} m elevation<extra></extra>",
+        showlegend=False,
+    ))
+    if marker_x is not None:
+        fig.add_trace(go.Scatter(
+            x=[marker_x], y=[marker_y], mode="markers",
+            marker=dict(size=16, color="#C98A28", line=dict(width=2, color="white")),
+            hoverinfo="skip", showlegend=False,
+        ))
+    fig.update_layout(
+        title=f"{basin_name} — click the line (schematic, no digitized centerline)",
+        xaxis_title="Position along river (upstream → downstream)", yaxis_title="Elevation (m)",
+        xaxis=dict(showticklabels=False), height=340,
+        margin=dict(l=10, r=10, t=40, b=10),
+    )
+    return fig
+
+
+# --- Main Gradio UI Block ---
+with gr.Blocks(title="River Network Explorer") as demo:
+    gr.Markdown("# River Network Explorer")
+
+    with gr.Row():
+        view_radio = gr.Radio(options=["Explore", "Network validation"], value="Explore", label="View", interactive=True)
+        basin_radio = gr.Radio(choices=list(BASIN_NAMES.keys()), value=0, label="River", interactive=True,
+                               type="index")
+        # Update labels nicely for radio buttons
+        basin_radio.choices = [(name, idx) for idx, name in BASIN_NAMES.items()]
+
+    # Dynamic containers
+    explore_group = gr.Group()
+    with explore_group:
+        status_md = gr.Markdown("Loading datasets...")
+        plot_output = gr.Plot(label="River Map")
+        slider = gr.Slider(minimum=0, maximum=100, value=50, step=1, label="Position along river (%)")
+        
+        with gr.Row():
+            metric_elev = gr.Number(label="Elevation (m)")
+            metric_dist = gr.Textbox(label="Distance")
+            metric_gw = gr.Textbox(label="Est. groundwater level")
+        coords_md = gr.Markdown("Coordinates: —")
+        
+        gr.Markdown("### Station Time Series Plots")
+        with gr.Tabs():
+            with gr.TabItem("Water Level"):
+                plot_waterlevel = gr.Plot()
+            with gr.TabItem("Discharge"):
+                plot_discharge = gr.Plot()
+            with gr.TabItem("Rating Curve"):
+                plot_rating = gr.Plot()
+
+    validation_group = gr.Group(visible=False)
+    with validation_group:
+        val_metrics_row = gr.Row()
+        with val_metrics_row:
+            m_nodes = gr.Number(label="Nodes")
+            m_edges = gr.Number(label="Edges")
+            m_confl = gr.Number(label="Confluences")
+            m_gauges = gr.Number(label="Gauges")
+        val_caption = gr.Markdown("")
+        val_plot_output = gr.Plot(label="Reach Graph Validation")
+        val_snap_caption = gr.Markdown("")
+
+    # --- Event Handlers & Logic ---
+    def update_view(view_val, basin_id):
+        basin_name = BASIN_NAMES[basin_id]
+        color = _PALETTE[basin_id % len(_PALETTE)]
+        
+        try:
+            nodes, edges = get_graph(DATA_ROOT)
+        except Exception:
+            return {
+                explore_group: gr.update(visible=True),
+                validation_group: gr.update(visible=False),
+                status_md: gr.update(value="❌ Could not find station_elevations.csv under data root.")
+            }
+
+        if view_val == "Network validation":
+            reach = load_reach_graph(DATA_ROOT, basin_id)
+            if reach is None:
+                return {
+                    explore_group: gr.update(visible=False),
+                    validation_group: gr.update(visible=True),
+                    val_caption: gr.update(value=f"No reach graph found for {basin_name}. Run `python -m scripts.build_reach_graphs` first.")
+                }
+            reach_nodes, reach_edges = reach
+            n_confluences = int(reach_nodes["is_confluence"].sum()) if "is_confluence" in reach_nodes.columns else 0
+            n_gauged = int(reach_nodes["is_gauged"].sum())
+            
+            fig = build_figure_reach_graph(reach_nodes, reach_edges, basin_name, color)
+            return {
+                explore_group: gr.update(visible=False),
+                validation_group: gr.update(visible=True),
+                m_nodes: len(reach_nodes),
+                m_edges: len(reach_edges),
+                m_confl: n_confluences,
+                m_gauges: n_gauged,
+                val_plot_output: fig,
+                val_caption: gr.update(value="Confirm visually: confluences (◆) should sit where a tributary joins."),
+                val_snap_caption: gr.update(value="")
+            }
+        else:
+            centerlines = get_centerlines(DATA_ROOT, nodes)
+            gw_df = get_groundwater(DATA_ROOT)
+            has_centerline = basin_id in centerlines
+            
+            status_text = f"Loaded {gw_df['code_bss'].nunique()} groundwater wells (ADES)." if gw_df is not None else "No groundwater well data found."
+            
+            if has_centerline:
+                info = centerlines[basin_id]
+                fig = build_figure_real(info, basin_name, color, wells_df=gw_df)
+            else:
+                targets = schematic_click_targets(nodes, edges, basin_id)
+                fig = build_figure_schematic(targets, basin_name, color)
+                
+            return {
+                explore_group: gr.update(visible=True),
+                validation_group: gr.update(visible=False),
+                status_md: gr.update(value=status_text),
+                plot_output: fig,
+                slider: 50
+            }
+
+    # Bind view and basin switcher
+    view_radio.change(update_view, inputs=[view_radio, basin_radio], outputs=[explore_group, validation_group, status_md, plot_output, slider])
+    basin_radio.change(update_view, inputs=[view_radio, basin_radio], outputs=[explore_group, validation_group, status_md, plot_output, slider])
+
+    # Handle slider or map clicks
+    def compute_position(basin_id, percent):
+        fraction = percent / 100.0
+        basin_name = BASIN_NAMES[basin_id]
+        color = _PALETTE[basin_id % len(_PALETTE)]
+        
+        try:
+            nodes, edges = get_graph(DATA_ROOT)
+        except Exception:
+            return None
+
+        centerlines = get_centerlines(DATA_ROOT, nodes)
+        gw_df = get_groundwater(DATA_ROOT)
+        has_centerline = basin_id in centerlines
+
+        fig2 = None
+        elev, lat, lon, dist_label, dist_sub = None, 0, 0, "", ""
+        nearest_station, nearest_station_km = "", 0
+
+        if has_centerline:
+            info = centerlines[basin_id]
+            cp = interpolate_by_fraction(info["centerline"], fraction)
+            elev = elevation_at_km(info["gauges"], cp.distance_from_mouth_km)
+            lat, lon = cp.latitude, cp.longitude
+            dist_label = f"{cp.distance_from_mouth_km:.2f} km"
+            dist_sub = f"from mouth, of {cp.total_length_km:.0f} km total"
+            nearest_station, nearest_station_km = info["gauges"].iloc[(info["gauges"]["centerline_km"] - cp.distance_from_mouth_km).abs().idxmin()]["station_code"], float((info["gauges"]["centerline_km"] - cp.distance_from_mouth_km).abs().min())
+            fig2 = build_figure_real(info, basin_name, color, wells_df=gw_df, marker_lon=lon, marker_lat=lat)
+        else:
+            targets = schematic_click_targets(nodes, edges, basin_id)
+            point = interpolate_along_chain(nodes, edges, basin_id, fraction)
+            elev = point.elevation_m
+            lat, lon = point.latitude, point.longitude
+            dist_label = f"{point.distance_from_upstream_km:.2f} km"
+            dist_sub = f"of {point.edge_length_km:.2f} km segment"
+            nearest_station, nearest_station_km = point.upstream_station, fraction * point.edge_length_km
+            x_pos = fraction * (len(targets) - 1)
+            fig2 = build_figure_schematic(targets, basin_name, color, marker_x=x_pos, marker_y=elev)
+
+        gwl, nearest_well_km = None, None
+        if gw_df is not None:
+            pseudo_point = RiverPoint(basin_id=basin_id, upstream_station="", downstream_station="",
+                                       fraction=0, latitude=lat, longitude=lon, elevation_m=elev or 0,
+                                       distance_from_upstream_km=0, edge_length_km=0)
+            gwl, nearest_well_km = groundwater_at_point(pseudo_point, gw_df)
+
+        gw_text = f"{gwl:.1f} m" if gwl is not None else (f"No well (nearest {nearest_well_km:.0f}km away)" if nearest_well_km else "No data")
+
+        # Hydrometric plots
+        hydro = get_hydrometric(DATA_ROOT)
+        fig_wl, fig_disc, fig_rc = None, None, None
+        if hydro is not None:
+            loader, hydro_df = hydro
+            station_df = hydro_df[hydro_df["station_code"] == nearest_station]
+            if not station_df.empty:
+                try:
+                    fig_wl = loader.plot_waterlevel(df=station_df, stations=[nearest_station]).figure
+                except Exception:
+                    pass
+                try:
+                    fig_disc = loader.plot_discharge(df=station_df, stations=[nearest_station]).figure
+                except Exception:
+                    pass
+                try:
+                    fig_rc = loader.plot_rating_curve(nearest_station, df=station_df).figure
+                except Exception:
+                    pass
+
+        return (
+            fig2, elev, dist_label, gw_text, f"Coordinates: {lat:.4f}, {lon:.4f}",
+            fig_wl, fig_disc, fig_rc
+        )
+
+    slider.change(compute_position, inputs=[basin_radio, slider], outputs=[plot_output, metric_elev, metric_dist, metric_gw, coords_md, plot_waterlevel, plot_discharge, plot_rating])
+
+    def on_plot_select(basin_id, select_data: gr.SelectData):
+        if not select_data or select_data.index is None:
+            return gr.skip()
+        # Customdata carries distance or fraction
+        try:
+            point_idx = select_data.index
+            nodes, edges = get_graph(DATA_ROOT)
+            centerlines = get_centerlines(DATA_ROOT, nodes)
+            if basin_id in centerlines:
+                targets = centerlines[basin_id]["click_targets"]
+                if point_idx < len(targets):
+                    km = targets.iloc[point_idx]["distance_from_mouth_km"]
+                    pct = int(round(100 * float(km) / centerlines[basin_id]["total_km"]))
+                    return pct
+            else:
+                targets = schematic_click_targets(nodes, edges, basin_id)
+                if point_idx < len(targets):
+                    frac = targets.iloc[point_idx]["fraction"]
+                    return int(round(100 * float(frac)))
+        except Exception:
+            pass
+        return gr.skip()
+
+    plot_output.select(on_plot_select, inputs=[basin_radio], outputs=[slider])
+
+    # Initial load trigger
+    demo.load(update_view, inputs=[view_radio, basin_radio], outputs=[explore_group, validation_group, status_md, plot_output, slider])
+
+if __name__ == "__main__":
+    demo.launch()