import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
from matplotlib.lines import Line2D
from matplotlib.legend_handler import HandlerBase
import seaborn as sns
import matplotlib.patches as mpatches
import matplotlib.colors as mcolors
from scipy.stats import linregress, t
from pathlib import Path
import warnings
from shapely.geometry import Polygon
import geopandas as gpd

warnings.filterwarnings("ignore")

# ==============================================================================
# GLOBAL FONT & STYLE SETTINGS
# ==============================================================================
# Centralized font control for all manuscript figures.
# Increase these values slightly if the exported TIFFs are still too small
# after journal/composite-figure resizing.
FONT_FAMILY = "Arial"
FONT_BASE = 14
FONT_AXIS_LABEL = 13
FONT_TICK = 13
FONT_TITLE = 16
FONT_PANEL = 17
FONT_LEGEND = 12
FONT_REGRESSION_LEGEND = 13
# Smaller regression-statistics legend only for Fig. 4.
FIG4_REGRESSION_LEGEND = 10.5
FONT_LEGEND_TITLE = 13
FONT_NOTE = 13
FONT_SYMBOL = 10

# Larger fonts used only for Fig. S2-S3.
# These figures contain dense scatter panels and regression-statistics boxes.
S23_FONT_AXIS_LABEL = 18
S23_FONT_TICK = 16
S23_FONT_PANEL = 20
S23_REGRESSION_LEGEND = 15

# Larger fonts used only for plot_dumbbell() outputs: Fig6 and FigS6-S8.
DUMBBELL_FONT_AXIS_LABEL = 18
DUMBBELL_FONT_TICK = 16
DUMBBELL_FONT_PANEL = 18
DUMBBELL_FONT_LEGEND = 14
DUMBBELL_FONT_LEGEND_TITLE = 16
DUMBBELL_FONT_SYMBOL = 13

sns.set_theme(
    style="ticks",
    context="notebook",
    rc={
        "font.family": FONT_FAMILY,
        "font.size": FONT_BASE,
        "axes.titlesize": FONT_TITLE,
        "axes.labelsize": FONT_AXIS_LABEL,
        "xtick.labelsize": FONT_TICK,
        "ytick.labelsize": FONT_TICK,
        "legend.fontsize": FONT_LEGEND,
        "legend.title_fontsize": FONT_LEGEND_TITLE,
        "figure.titlesize": FONT_TITLE,
    }
)

plt.rcParams.update({
    "font.family": FONT_FAMILY,
    "font.size": FONT_BASE,
    "axes.titlesize": FONT_TITLE,
    "axes.labelsize": FONT_AXIS_LABEL,
    "xtick.labelsize": FONT_TICK,
    "ytick.labelsize": FONT_TICK,
    "legend.fontsize": FONT_LEGEND,
    "legend.title_fontsize": FONT_LEGEND_TITLE,
    "figure.titlesize": FONT_TITLE,
    "axes.linewidth": 1.0,
    "xtick.major.width": 1.0,
    "ytick.major.width": 1.0,
    "xtick.major.size": 4,
    "ytick.major.size": 4,
})

SUB_W = 5.8
SUB_H = 3.5

# ==============================================================================
# GLOBAL CONFIGURATION
# ==============================================================================

BASE_DIR = Path("./")

INPUT_FOLDER = BASE_DIR / 'Initial_output_SSA'
SHP_FOLDER = BASE_DIR / "Catchments_info_SSA"
METADATA_FILE = BASE_DIR / "Catchments_info_SSA" / "Catchments.xlsx"
OUTPUT_FOLDER = BASE_DIR / 'Comparison_Figures_SSA'

DATASET_STYLE = {
    "Obs-GC": {"color": "#1f77b4", "marker": "^", "label": "Obs-GC", "mec": "black"},
    "GLDAS":  {"color": "#666000", "marker": "o", "label": "GLDAS", "mec": "black"},
    "ERA5":   {"color": "#ff66b2", "marker": "D", "label": "ERA5", "mec": "black"},
}

VARS_MAP = {
    "T":   {"label":  "Temperature",           "unit": "°C"},
    "P":   {"label":  "Precipitation",         "unit": "mm/year"},
    "R":   {"label":  "Runoff",                "unit": "mm/year"},
    "ET":  {"label":  "Evapotranspiration",    "unit": "mm/year"},
    "DS":  {"label":  "Storage Change",        "unit": "mm/year"},
    "DSM": {"label":  "Soil Moisture Change",  "unit": "mm/mm.year"}
}

# ==============================================================================
# UTILITY FUNCTIONS
# ==============================================================================

def tint_color(base_color, factor):
    """
    factor > 1  -> darker
    factor < 1  -> lighter
    """
    c = np.array(mcolors.to_rgb(base_color))
    c = np.clip(c * factor, 0, 1)
    return tuple(c)

def format_lat_label(lat):
    if lat > 0: return f"{lat:.0f}°N"
    elif lat < 0: return f"{abs(lat):.0f}°S"
    return "0°"

def compute_weighted_stats(df, val_col, weight_col="Weight"):
    def w_stats(g):
        if val_col not in g.columns:
            return pd.Series({'mean': np.nan})
        valid = g[[val_col, weight_col]].dropna()
        if valid.empty or valid[weight_col].sum() == 0:
            return pd.Series({'mean': np.nan})
        w, v = valid[weight_col].values, valid[val_col].values
        return pd.Series({'mean': np.average(v, weights=w)})
    
    return df.groupby("Year").apply(w_stats).dropna()


def add_axis_headroom(ax, top_frac=0.20, bottom_frac=0.02):
    """
    Add blank vertical space inside an axis.

    This is useful when a legend or regression-statistics box is kept inside
    the subplot, because it creates a reserved upper band and avoids covering
    the plotted data.
    """
    ymin, ymax = ax.get_ylim()
    if not np.isfinite(ymin) or not np.isfinite(ymax):
        return

    yrange = ymax - ymin
    if yrange == 0:
        yrange = abs(ymax) if ymax != 0 else 1.0

    ax.set_ylim(
        ymin - bottom_frac * yrange,
        ymax + top_frac * yrange
    )



def format_lat_axis_label(lat, is_first=False, is_last=False):
    """Format Figure 2 latitude ticks as: °S 32 28 ... 0 4 8 °N."""
    lat_abs = abs(int(round(lat)))
    if lat < 0:
        return f"°S {lat_abs}" if is_first else f"{lat_abs}"
    if lat > 0:
        return f"{lat_abs} °N" if is_last else f"{lat_abs}"
    return "0"


def format_r2_for_math(r2, decimals=2, bold=False):
    """Return an r² label fragment, using <0.01 instead of rounded zero."""
    if not np.isfinite(r2):
        return "nan"

    if r2 < 0.01:
        return r"< \mathbf{0.01}" if bold else "< 0.01"

    return rf"= \mathbf{{{r2:.{decimals}f}}}" if bold else f"= {r2:.{decimals}f}"


def _iter_legend_handles(legend):
    """Compatible access to legend handles across Matplotlib versions."""
    return getattr(legend, "legend_handles", getattr(legend, "legendHandles", []))


def bolden_legend_handles(legend, line_width=2.8, patch_width=2.2, marker_scale=1.10):
    """Make legend lines and symbols visually stronger without changing the plotted data."""
    if legend is None:
        return

    for handle in _iter_legend_handles(legend):
        if isinstance(handle, Line2D):
            # Only thicken actual line handles. Keep marker-only legends, such as
            # the dumbbell period symbols, without connecting lines.
            if (
                handle.get_linestyle() not in ["", " ", "None", "none"]
                and handle.get_linewidth() > 0
            ):
                handle.set_linewidth(max(handle.get_linewidth(), line_width))
            if handle.get_marker() not in ["", " ", "None", "none", None]:
                handle.set_markersize(max(handle.get_markersize() * marker_scale, handle.get_markersize()))
                handle.set_markeredgewidth(max(handle.get_markeredgewidth(), 1.1))
        elif hasattr(handle, "set_linewidth"):
            try:
                handle.set_linewidth(max(handle.get_linewidth(), patch_width))
            except Exception:
                pass


def enforce_panel_label_style(fig):
    """Bold all single-letter panel labels (a, b, c, ...), using Arial."""
    for ax in fig.axes:
        for txt in ax.texts:
            label = txt.get_text().strip()
            if len(label) == 1 and label.isalpha() and label.upper() == label:
                txt.set_fontweight("bold")
                txt.set_fontfamily(FONT_FAMILY)


def ensure_budyko_xaxis_has_one(ax, x_max):
    """Ensure the Budyko aridity index threshold PET/P = 1 is explicitly ticked."""
    ticks = [float(t) for t in ax.get_xticks() if 0 <= t <= x_max]
    if not any(np.isclose(t, 1.0) for t in ticks):
        ticks.append(1.0)

    ticks = sorted(set(np.round(ticks, 6)))
    tick_labels = ["1" if np.isclose(t, 1.0) else f"{t:g}" for t in ticks]
    ax.set_xticks(ticks)
    ax.set_xticklabels(tick_labels)


class ChangeTypeLegendSymbol:
    """Proxy object for custom dumbbell change-type legend symbols."""

    def __init__(self, shape, facecolor, symbol):
        self.shape = shape
        self.facecolor = facecolor
        self.symbol = symbol


class HandlerChangeTypeLegendSymbol(HandlerBase):
    """Draw a black +/- symbol inside the same colored marker used in dumbbell plots."""

    def create_artists(self, legend, orig_handle, xdescent, ydescent,
                       width, height, fontsize, trans):
        cx = xdescent + width * 0.50
        cy = ydescent + height * 0.50

        bbox_style = (
            "square,pad=0.13"
            if orig_handle.shape == "square"
            else "circle,pad=0.13"
        )

        symbol = plt.Text(
            cx,
            cy,
            orig_handle.symbol,
            color="black",
            ha="center",
            va="center",
            fontsize=fontsize * 0.85,
            fontweight="bold",
            transform=trans,
            bbox=dict(
                boxstyle=bbox_style,
                facecolor=orig_handle.facecolor,
                edgecolor="none"
            )
        )

        return [symbol]


def apply_axis_fontsize(ax, regression_legend_size=None):
    """
    Enforce consistent readable fonts on axes, tick labels, titles,
    axis labels, and axes-level legends.
    """
    ax.tick_params(axis="both", which="major", labelsize=FONT_TICK)
    ax.tick_params(axis="both", which="minor", labelsize=FONT_TICK - 1)

    ax.xaxis.label.set_size(FONT_AXIS_LABEL)
    ax.yaxis.label.set_size(FONT_AXIS_LABEL)
    ax.title.set_size(FONT_TITLE)

    leg = ax.get_legend()
    if leg is not None:
        legend_texts = [txt.get_text() for txt in leg.get_texts()]
        legend_size = (
            regression_legend_size
            if regression_legend_size is not None and any(("y =" in t or "r^2" in t) for t in legend_texts)
            else FONT_REGRESSION_LEGEND if any(("y =" in t or "r^2" in t) for t in legend_texts)
            else FONT_LEGEND
        )
        for txt in leg.get_texts():
            txt.set_fontsize(legend_size)
        leg.get_title().set_fontsize(FONT_LEGEND_TITLE)
        bolden_legend_handles(leg)


def apply_figure_fontsize(fig, regression_legend_size=None):
    """
    Apply font sizes to all axes and figure-level legends before saving.
    """
    for ax in fig.axes:
        apply_axis_fontsize(ax, regression_legend_size=regression_legend_size)

    for leg in fig.legends:
        for txt in leg.get_texts():
            txt.set_fontsize(FONT_LEGEND)
        leg.get_title().set_fontsize(FONT_LEGEND_TITLE)
        bolden_legend_handles(leg)

    enforce_panel_label_style(fig)


def apply_s23_fontsize(fig):
    """Apply larger fonts only to Fig. S2 and Fig. S3."""
    for ax in fig.axes:
        ax.tick_params(axis="both", which="major", labelsize=S23_FONT_TICK)
        ax.tick_params(axis="both", which="minor", labelsize=S23_FONT_TICK - 1)
        ax.xaxis.label.set_size(S23_FONT_AXIS_LABEL)
        ax.yaxis.label.set_size(S23_FONT_AXIS_LABEL)
        ax.title.set_size(S23_FONT_AXIS_LABEL)

        leg = ax.get_legend()
        if leg is not None:
            for txt in leg.get_texts():
                txt.set_fontsize(S23_REGRESSION_LEGEND)
            leg.get_title().set_fontsize(S23_REGRESSION_LEGEND)
            bolden_legend_handles(leg)

    enforce_panel_label_style(fig)


def apply_dumbbell_fontsize(fig):
    """Apply larger fonts only to plot_dumbbell() outputs."""
    for ax in fig.axes:
        ax.tick_params(axis="both", which="major", labelsize=DUMBBELL_FONT_TICK)
        ax.tick_params(axis="both", which="minor", labelsize=DUMBBELL_FONT_TICK - 1)
        ax.xaxis.label.set_size(DUMBBELL_FONT_AXIS_LABEL)
        ax.yaxis.label.set_size(DUMBBELL_FONT_AXIS_LABEL)
        ax.title.set_size(DUMBBELL_FONT_AXIS_LABEL)

    for leg in fig.legends:
        for txt in leg.get_texts():
            txt.set_fontsize(DUMBBELL_FONT_LEGEND)
        leg.get_title().set_fontsize(DUMBBELL_FONT_LEGEND_TITLE)
        bolden_legend_handles(leg, line_width=3.2, patch_width=2.4, marker_scale=1.18)

    enforce_panel_label_style(fig)

def add_regression_line(ax, x, y_mean, style, ds_idx=0):
    slope, intercept, r_val, p_val, _ = linregress(x, y_mean)
    y_pred = slope * x + intercept
    
    ax.plot(x, y_pred, color=style["color"], linestyle="--", linewidth=1.0, zorder=2)
    
    n = len(x)
    if n > 2:
        t_val = t.ppf(0.975, n - 2)
        s_err = np.sqrt(np.sum((y_mean - y_pred)**2) / (n - 2))
        mean_x = np.mean(x)
        ssx = np.sum((x - mean_x)**2)
        ci = t_val * s_err * np.sqrt(1/n + ((x - mean_x)**2) / ssx)
        ax.fill_between(x, y_pred - ci, y_pred + ci, color=style["color"], alpha=0.15, zorder=1)

    is_significant = p_val <= 0.01

    if is_significant:
        target_x = max(x[-1] - (ds_idx * 4), x[0])
        star_y = slope * target_x + intercept
        ax.scatter(target_x, star_y, color=style["color"], marker='*', s=400, 
                   zorder=5, edgecolor='black', linewidth=1.0)
        p_string = "p < \\mathbf{0.01}"

    else:
        p_string = f"p = \\mathbf{{{p_val:.3f}}}"
    
    # Use r² < 0.01 instead of rounded r² = 0.00 in regression legends.
    r2_string = format_r2_for_math(r_val**2, decimals=2, bold=True)
    label_text = (
        f"{style['label']} $y = \\mathbf{{{slope:.3g}}}x "
        f"{'+' if intercept >= 0 else '-'} {abs(intercept):.2f}, "
        f"r^2 {r2_string}, "
        f"{p_string}${' *' if is_significant else ''}"
    )

    ax.plot([], [], color=style["color"], linewidth=2.4, label=label_text)

# ==============================================================================
# DATA LOADING & EXPORT
# ==============================================================================

def load_all_catchment_data(input_folder):
    if not METADATA_FILE.exists():
        raise FileNotFoundError(f"Metadata file not found at {METADATA_FILE}.")

    metadata = pd.read_excel(METADATA_FILE)
    metadata["Catchment_id"] = metadata["Catchment_id"].astype(str)
    metadata["Dataset"] = metadata["Dataset"].astype(str)
    lat_col = next((c for c in metadata.columns if c.lower() in ["latitude", "lat", "gauge_lat"]), None)
    
    data_map = {k: [] for k in DATASET_STYLE.keys()}
    files = list(input_folder.glob("*.csv"))
    print(f"Found {len(files)} files in {input_folder}\n")

    for f in files:
        try:
            dataset_original, catchment_id = f.stem.split("_", 1)
        except ValueError:
            continue

        group = "Obs-GC" if dataset_original in ["CAMELS", "GRDC"] else dataset_original
        if group not in DATASET_STYLE:
            continue

        subset = metadata[
            metadata["Dataset"].isin(["CAMELS", "GRDC", "Obs-GC"] if group == "Obs-GC" else [group]) &
            (metadata["Catchment_id"] == catchment_id)
        ]
        if subset.empty: continue

        weight = subset["Adjust_area"].iloc[0]
        lat = subset[lat_col].iloc[0] if lat_col else np.nan

        df = pd.read_csv(f, parse_dates=["Date"], index_col="Date")

        for col in ["P", "R", "ET", "T", "PET", "SM"]:
            if col not in df.columns: df[col] = np.nan

        annual = pd.DataFrame({
            "P": df["P"].resample("YE").sum(min_count=10),
            "R": df["R"].resample("YE").sum(min_count=10),
            "ET": df["ET"].resample("YE").sum(min_count=10),
            "T": df["T"].resample("YE").mean().where(df["T"].resample("YE").count() >= 10),
            "PET": df["PET"].resample("YE").sum(min_count=10),
        })

        annual["DS"] = annual["P"] - annual["R"] - annual["ET"]

        annual["DSM"] = df["SM"].resample("YE").last().diff()

        annual.index = annual.index.year

        data_map[group].append({"id": catchment_id, "data": annual, "weight": weight, "lat": lat})

    return metadata, data_map

def compute_catchment_statistics(metadata, data_map):
    print("Calculating catchment statistics...")

    ts_lookup = {
        (group, str(item["id"])): item["data"]
        for group, items in data_map.items()
        for item in items
    }

    export_cols = [
        "ET/P", "PET/P", "R/P",
        "mean_P", "mean_R", "mean_ET", "mean_T",
        "delta_P", "delta_R", "delta_ET", "delta_T",
        "mean_DS", "mean_DSM",
        "mean_PET", "mean_PETLang",
    ]

    for c in export_cols:
        metadata[c] = np.nan

    fig_r2_records = []

    for idx, row in metadata.iterrows():
        cid = str(row["Catchment_id"])
        ds_raw = str(row["Dataset"])

        group = "Obs-GC" if ds_raw in ["CAMELS", "GRDC"] else ds_raw
        
        annual = ts_lookup.get((group, cid))

        if annual is None or len(annual) < 5:
            continue

        means = annual.mean()

        P = means.get("P")
        R = means.get("R")
        ET = means.get("ET")
        T = means.get("T")

        metadata.at[idx, "mean_P"] = P
        metadata.at[idx, "mean_R"] = R
        metadata.at[idx, "mean_ET"] = ET
        metadata.at[idx, "mean_T"] = T
        metadata.at[idx, "mean_PET"] = means.get("PET")
        metadata.at[idx, "mean_DS"] = means.get("DS")
        metadata.at[idx, "mean_DSM"] = means.get("DSM")

        # Langbein PET
        if pd.notna(T):
            PETLang = 325 + 21 * T + 0.9 * T**2
            
            metadata.at[idx, "mean_PETLang"] = PETLang
        else:
            PETLang = np.nan

        if pd.notna(P) and P > 0:
            metadata.at[idx, "ET/P"] = ET / P
            metadata.at[idx, "R/P"] = R / P
            if pd.notna(PETLang):
                metadata.at[idx, "PET/P"] = PETLang / P

        # -----------------------------
        # 5. Period change delta
        # -----------------------------
        pre = annual.loc[1980:2002]
        post = annual.loc[2003:2025]

        if len(pre) >= 5 and len(post) >= 5:
            delta = post.mean() - pre.mean()
            metadata.at[idx, "delta_P"] = delta.get("P")
            metadata.at[idx, "delta_R"] = delta.get("R")
            metadata.at[idx, "delta_ET"] = delta.get("ET")
            metadata.at[idx, "delta_T"] = delta.get("T")

        has_delta = pd.notna(metadata.at[idx, "delta_P"]) and \
                    pd.notna(metadata.at[idx, "delta_R"]) and \
                    pd.notna(metadata.at[idx, "delta_ET"])
        
        fig_r2_records.append({
            "Dataset": group,
            "Catchment_id": cid,
            "P_mean": P,
            "R_mean": R,
            "ET_mean": ET,
            "T_mean": T,
            "P_delta": metadata.at[idx, "delta_P"],
            "R_delta": metadata.at[idx, "delta_R"],
            "ET_delta": metadata.at[idx, "delta_ET"],
            "T_delta": metadata.at[idx, "delta_T"],
            "Has_Delta": has_delta
        })

    print("Successfully calculated catchment statistics\n")
    return metadata, pd.DataFrame(fig_r2_records)

def load_catchment_geometries(shp_folder):
    shp_files = list(Path(shp_folder).glob("*.shp"))
    if not shp_files:
        raise FileNotFoundError(f"No shapefiles found in {shp_folder}")

    gdfs = []
    for shp in shp_files:
        try:
            gdf = gpd.read_file(shp)
            gdf.columns = [c.upper() for c in gdf.columns]
            
            id_col = next((c for c in ['REFID', 'FILENAME'] if c in gdf.columns), None)
            if id_col:
                if id_col == 'FILENAME':
                    gdf['Catchment_id'] = gdf[id_col].astype(str).str.replace(r'\.shp$', '', regex=True).str.strip()
                else:
                    gdf['Catchment_id'] = gdf[id_col].astype(str).str.strip()
                
                geom_col = next((c for c in gdf.columns if c == 'GEOMETRY'), None)
                if geom_col:
                    gdf = gdf.rename(columns={geom_col: 'geometry'}).set_geometry('geometry')
                
                gdfs.append(gdf[['Catchment_id', 'geometry']])
        except Exception as e:
            print(f"  [Warning] Could not read {shp.name}: {e}")

    full_gdf = pd.concat(gdfs, ignore_index=True)
    full_gdf = gpd.GeoDataFrame(full_gdf, geometry='geometry', crs=gdfs[0].crs)
    return full_gdf

def create_latitudinal_bands(min_lat, max_lat, step):
    lat_edges = np.arange(min_lat, max_lat + step, step)
    bands = []

    for i in range(len(lat_edges) - 1):
        bottom, top = lat_edges[i], lat_edges[i + 1]

        poly = Polygon([(-20, bottom), (60, bottom), (60, top), (-20, top)])

        label_bottom = f"{abs(int(bottom))}{'°S' if bottom < 0 else '°N'}"
        label_top = f"{abs(int(top))}{'°S' if top < 0 else '°N'}"
        band_name = f"{label_bottom} to {label_top}"

        bands.append({
            'Band_ID': band_name,
            'Lat_Center': (bottom + top) / 2,
            'geometry': poly
        })

    return gpd.GeoDataFrame(bands, crs="EPSG:4326")

def calculate_seasonal_quantiles_df(input_folder, metadata):
    print("Calculating seasonal quantiles from raw data...")
    all_stats = []
    files = list(Path(input_folder).glob("*.csv"))
    
    season_map = {12: 'DJF\n(Summer)', 1: 'DJF\n(Summer)', 2: 'DJF\n(Summer)',
                  3: 'MAM\n(Autumn)', 4: 'MAM\n(Autumn)', 5: 'MAM\n(Autumn)',
                  6: 'JJA\n(Winter)', 7: 'JJA\n(Winter)', 8: 'JJA\n(Winter)',
                  9: 'SON\n(Spring)', 10: 'SON\n(Spring)', 11: 'SON\n(Spring)'}

    for f in files:
        try:
            dataset_original, catchment_id = f.stem.split("_", 1)
        except ValueError: 
            continue

        group = "Obs-GC" if dataset_original in ["CAMELS", "GRDC"] else dataset_original
        df = pd.read_csv(f, parse_dates=["Date"], index_col="Date")

        df['Season'] = df.index.month.map(season_map)
        df['Year'] = df.index.year
        
        df['Period'] = np.where(df['Year'] <= 2002, "1980-2002", "2003-2025")
        
        df = df[(df['Year'] >= 1980) & (df['Year'] <= 2025)]

        for (period, season), group_df in df.groupby(['Period', 'Season']):
            stats = {
                'Catchment': catchment_id,
                'Dataset': group,
                'Period': period,
                'Season': season
            }
            
            for var in ['P', 'R', 'ET']:
                if var in group_df.columns:
                    valid_data = group_df[var].dropna()
                    if not valid_data.empty:
                        for p in [5, 50, 95]:
                            stats[f"{var}_{p}%"] = valid_data.quantile(p/100)
            
            all_stats.append(stats)

    print("Successfully calculated seasonal quantiles\n")
    return pd.DataFrame(all_stats)

# ==============================================================================
# PLOTTING FUNCTIONS
# ==============================================================================

def plot_bands(data_map, output_dir):
    print("Generating Figure 2 (Latitudinal bands)...")
    
    catchments_gdf = load_catchment_geometries(SHP_FOLDER)
    
    # FIX: Enforce unique geometries to prevent many-to-many merge conflicts
    # when identical catchment names exist across datasets.
    catchments_gdf = catchments_gdf.drop_duplicates(subset=['Catchment_id'])
    
    bands_gdf = create_latitudinal_bands(min_lat=-34.0, max_lat=8.0, step=4)
    
    bands_gdf['band_idx'] = range(len(bands_gdf))
    
    lat_edges = np.arange(-34, 8 + 4, 4)
    lat_centers = [(lat_edges[i] + lat_edges[i + 1]) / 2 for i in range(len(lat_edges) - 1)]
    lat_labels = [
        format_lat_axis_label(lat, is_first=(i == 0), is_last=(i == len(lat_centers) - 1))
        for i, lat in enumerate(lat_centers)
    ]

    catchments_ea = catchments_gdf.to_crs("EPSG:6933")
    bands_ea = bands_gdf.to_crs("EPSG:6933")
    intersections = gpd.overlay(catchments_ea, bands_ea, how='intersection')
    intersections['Area'] = intersections.geometry.area / 1e6

    records = []
    for group, items in data_map.items():         
        for item in items:
            if "id" not in item: continue
            data_filtered = item["data"][item["data"].index <= 2025]
            if data_filtered.empty: continue
            records.append({
                "Dataset": group,
                "Catchment_id": item["id"],
                "Latitude": item["lat"],
                "Area": item["weight"],
                **data_filtered.mean().to_dict()
            })

    df_data = pd.DataFrame(records)
    
    if not df_data.empty and not intersections.empty:
        df = intersections.merge(df_data, on='Catchment_id', how='inner')
    else:
        df = pd.DataFrame()

    if 'Area_x' in df.columns:
        df = df.rename(columns={'Area_x': 'Area'})  
    if 'Area_y' in df.columns:
        df = df.drop(columns=['Area_y'])  

    if 'Area' not in df.columns:
        raise ValueError("Area column missing after merge. Check intersections.")

    if df.empty: return

    CONGO_KEYWORDS = ["1147010"]

    def is_congo(catchment_id):
        return any(k in str(catchment_id).lower() for k in CONGO_KEYWORDS)

    df_congo = df[df["Catchment_id"].apply(is_congo)]

    band_areas = df_congo[df_congo["Dataset"] == "GLDAS"].groupby("band_idx")["Area"].sum()
    
    max_area = band_areas.max() if not band_areas.empty else 1
    cmap = mcolors.LinearSegmentedColormap.from_list("green_grad", ["#FFFFE0", "#6AFF00"])

    def safe_weighted_avg(g, var):
        if var not in g.columns:
            return np.nan
        valid = g[[var, "Area"]].dropna()
        return np.average(valid[var], weights=valid["Area"]) if not valid.empty and valid["Area"].sum() > 0 else np.nan

    target_cols = list(VARS_MAP.keys())
    grouped = df.groupby(["Dataset", "band_idx"]).apply(lambda g: pd.Series({v: safe_weighted_avg(g, v) for v in target_cols}))

    fig, axes = plt.subplots(2, 3, figsize=(SUB_W * 3, SUB_H * 2))
    axes = axes.flatten()

    valid_bands = sorted(df["band_idx"].dropna().unique())

    for i, (var, info) in enumerate(VARS_MAP.items()):
        if i >= len(axes): break
        ax = axes[i]
        for band in valid_bands:
            if (area := band_areas.get(band, 0)) > 0:
                ax.axvspan(band - 0.5, band + 0.5, color=cmap(area / max_area), alpha=0.6, zorder=0, ec='none')

        for ds, style in DATASET_STYLE.items():
            if ds in grouped.index.get_level_values(0) and var in grouped.columns:
                y = grouped.loc[ds, var].reindex(valid_bands)
                if y.notna().any():
                    ax.plot(valid_bands, y.values, color=style["color"], marker=style["marker"], markeredgecolor=style.get("mec", "black"), 
                            markeredgewidth=0.8, label=style["label"], zorder=3, linewidth=1.8, markersize=6)

        ax.annotate(f"{chr(97+i)}", xy=(0, 1.13), xycoords='axes fraction', va='top', ha='left', zorder=10, fontsize=FONT_PANEL, weight='bold')
        ax.set_ylabel(f"Mean {info['label']} ({info['unit']})")

        if var == "DSM":
            ax.ticklabel_format(axis='y', style='plain')
            
            y_vals = []
            for ds in DATASET_STYLE.keys():
                if ds in grouped.index.get_level_values(0):
                    y_vals.append(grouped.loc[ds, var].values)
            if y_vals:
                for line in ax.get_lines():
                    line.set_ydata(line.get_ydata() * 1e5)

            ax.relim()
            ax.autoscale_view()

            ax.text(0.02, 0.05, r"($\times 10^{-5}$)",
                    transform=ax.transAxes,
                    ha='left', va='bottom', fontsize=FONT_NOTE)
        
        ax.set_xticks(valid_bands)
        ax.set_xticklabels([lat_labels[int(b)] for b in valid_bands], ha="center")
        ax.set_xlim(min(valid_bands)-0.5, max(valid_bands)+0.5)
        # Reserve upper y-axis space so the legend does not cover the plotted lines.
        add_axis_headroom(ax, top_frac=0.5, bottom_frac=0.02)
        ax.legend(loc='upper left', frameon=True, framealpha=0.9)

    plt.tight_layout()
    apply_figure_fontsize(fig)
    plt.savefig(output_dir / "Fig 2.tiff", dpi=300)
    plt.close()

def plot_budyko(metadata_enriched, output_folder):
    print("Generating Figure S5 (Budyko framework)...")

    metadata_enriched['Dataset'] = metadata_enriched['Dataset'].replace('GRDC', 'Obs-GC')

    region_mapping = {
        'Congo': 'Congo River Basin',
        'Namibia': 'Namibian Stations',
        'South Africa': 'South Africa Stations'
    }
    metadata_enriched['Region'] = metadata_enriched['Region'].map(region_mapping).fillna(metadata_enriched['Region'])

    datasets = metadata_enriched['Dataset'].dropna().unique()
    regions = metadata_enriched['Region'].dropna().unique()
    n_datasets = len(datasets)
    
    global_style = globals().get('DATASET_STYLE', {})
    
    fig, axes = plt.subplots(1, n_datasets, figsize=(SUB_W * n_datasets * 0.75, SUB_H), sharex=True, sharey=True)
    if n_datasets == 1:
        axes = [axes]

    available_markers = ['*', 's', 'o']
    region_tint_factors = {
        'Congo River Basin': 0.6,
        'Namibian Stations': 1,
        'South Africa Stations': 1.8
    }

    region_size = {
        'Congo River Basin': 300,
        'Namibian Stations': 75,
        'South Africa Stations': 75
    }

    marker_zorders = {
        '*': 10,
        's': 9,
        'o': 8
    }
    
    region_markers = {
        region: available_markers[i % len(available_markers)] 
        for i, region in enumerate(regions)
    }
    
    x_max = metadata_enriched['PET/P'].max()
    x_max = max(x_max + 0.5, 2.5) if pd.notna(x_max) else 3.0
    
    x_limits = np.linspace(0.001, x_max, 100) 
    
    for ds_idx, (ax, dataset_name) in enumerate(zip(axes, datasets)):
        df_subset = metadata_enriched[metadata_enriched['Dataset'] == dataset_name]
        
        style_key = "Obs-GC" if dataset_name == "GRDC" else dataset_name
        dataset_color = global_style.get(style_key, {"color": "gray"})["color"]
        
        for region in regions:
            df_region = df_subset[df_subset['Region'] == region]
            factor = region_tint_factors.get(region, 0.5)
            shaded_color = tint_color(dataset_color, factor)
            ax.scatter(
                df_region['PET/P'],
                df_region['ET/P'],
                color=shaded_color,
                marker=region_markers[region],
                s=region_size[region],
                edgecolor='white',
                linewidth=0.5,
                zorder=marker_zorders.get(region_markers[region], 5)
            )
        
        ax.axvline(x=1.0, color='red', linestyle='--', linewidth=1.5, zorder=0)
        
        # Plot theoretical water and energy limits
        y_energy_water = np.minimum(1, x_limits)
        ax.plot(x_limits, y_energy_water, color='black', linewidth=1.5, label='Water/Energy Limits' if ax == axes[-1] else "")
        
        # Plot ideal budyko curve
        y_budyko = np.sqrt(x_limits * np.tanh(1/x_limits) * (1 - np.exp(-x_limits)))
        ax.plot(x_limits, y_budyko, color='gray', linestyle='--', linewidth=1.5, label='Ideal Budyko' if ax == axes[-1] else "")
        
        ax.set_xlim(0, x_max)
        ensure_budyko_xaxis_has_one(ax, x_max)
        ax.set_ylim(0, 1.5)
        ax.set_xlabel('PET/P')
        ax.set_ylabel('ET/P')

        legend_elements = []

        for region in regions:

            factor = region_tint_factors.get(region, 1.0)

            shaded_color = tint_color(dataset_color, factor)

            linear_markersize = np.sqrt(region_size[region])

            legend_elements.append(
                Line2D(
                    [0], [0],
                    marker=region_markers[region],
                    color='none',
                    markerfacecolor=shaded_color,
                    markeredgecolor='white',
                    markeredgewidth=0.5,
                    markersize=linear_markersize,
                    label=region
                )
            )

        ax.legend(
            handles=legend_elements, 
            title=f"{dataset_name}", 
            loc='lower right', 
            framealpha=0.9, 
            edgecolor='black')
        
        ax.annotate(f"{chr(97+ds_idx)}", xy=(-0.07, 1.15), xycoords='axes fraction', weight='bold',
                    va='top', ha='left', zorder=10, fontsize=FONT_PANEL)
            
    plt.tight_layout()
    apply_figure_fontsize(fig)
    
    out_file = output_folder / "Fig S5.tiff"
    plt.savefig(out_file, dpi=300, bbox_inches='tight')
    plt.close()

def plot_temporal(data_map, metadata_enriched, output_dir):
    print("Generating Figures 3, S8 and S9 (Temporal trends)...")
    
    region_mapping = {
        'Congo': 'Congo River Basin',
        'Namibia': 'Namibian Stations',
        'South Africa': 'South Africa Stations'
    }
    metadata_enriched['Region'] = metadata_enriched['Region'].replace(region_mapping)

    id_to_region = dict(zip(metadata_enriched['Catchment_id'], metadata_enriched['Region']))
    
    records = []
    for group, items in data_map.items():
        for item in items:
            df = item["data"].loc[1980:2025].copy()
            if group == "Obs-GC": df = df.loc[:2020]
            
            if not df.empty:
                df["Dataset"], df["Weight"], df["Year"] = group, item["weight"], df.index
            
                c_id = item.get("id") 
                df["Region"] = id_to_region.get(c_id, item.get("region", "Unknown"))
                
                records.append(df)

    if not records: 
        print("No records found to plot.")
        return
        
    df_all = pd.concat(records, ignore_index=True)

    # PART 1: GLOBAL TEMPORAL TRENDS (Figure 3)

    fig_global, axes_global = plt.subplots(2, 3, figsize=(SUB_W * 3, SUB_H * 2), sharex=True)
    axes_flat = axes_global.flatten()

    for i, (var, info) in enumerate(VARS_MAP.items()):
        if i >= len(axes_flat): break
        ax = axes_flat[i]
        
        if var not in df_all.columns:
            continue

        for ds_idx, (ds, style) in enumerate(DATASET_STYLE.items()):
            sub = df_all[df_all["Dataset"] == ds]
            if sub.empty: continue
            
            agg_df = compute_weighted_stats(sub, var)
            if len(agg_df) > 1:
                x, y_mean = agg_df.index.values, agg_df["mean"].values

                if var == "DSM":
                    y_mean = y_mean * 1e3

                ax.plot(x, y_mean, color=style["color"], linewidth=1.5, zorder=3)
                add_regression_line(ax, x, y_mean, style, ds_idx)

        ax.annotate(f"{chr(97+i)}", xy=(0, 1.12), xycoords='axes fraction', va='top', ha='left', zorder=10, fontsize=FONT_PANEL, weight='bold')
        ax.set_ylabel(f"{info['label']} ({info['unit']})")

        if var == "DSM":
            ax.ticklabel_format(axis='y', style='plain')

            ax.relim()
            ax.autoscale_view()

            ax.text(0.02, 0.05, r"($\times 10^{-3}$)",
                    transform=ax.transAxes,
                    ha='left', va='bottom', fontsize=FONT_NOTE)
            
        ymin, ymax = ax.get_ylim()
        ax.set_ylim(ymin, ymax + (ymax - ymin) * 0.5)
        
        ax.legend(loc='best', frameon=True, framealpha=0.9, fontsize=FIG4_REGRESSION_LEGEND)

    for j in range(3, 6):
        if j < len(axes_flat):
            axes_flat[j].set_xlabel("Year")
            axes_flat[j].tick_params(labelbottom=True)

    plt.tight_layout(w_pad=0.5, h_pad=0.5)
    apply_figure_fontsize(fig_global, regression_legend_size=FIG4_REGRESSION_LEGEND)
    out_file = output_dir / "Fig 3.tiff" 
    plt.savefig(out_file, dpi=300)
    plt.close()

    # PART 2: REGIONAL TEMPORAL TRENDS (Figures S8 & S9)

    region_order = ["Congo River Basin", "Namibian Stations", "South Africa Stations"]
    existing_regions = [r for r in df_all["Region"].unique() if pd.notna(r) and r != "Unknown"]
    regions = [r for r in region_order if r in existing_regions]
    regions += [r for r in existing_regions if r not in regions]
    
    configs = [
        {
            "file": "Fig S8.tiff", 
            "vars": [v for v in VARS_MAP.keys() if v in ['T', 'P', 'R']]
        },
        {
            "file": "Fig S9.tiff", 
            "vars": [v for v in VARS_MAP.keys() if v in ['ET', 'DS', 'DSM']]
        }
    ]

    for config in configs:
        target_vars = config["vars"]
        filename = config["file"]
        
        nrows = len(target_vars)
        ncols = len(regions)

        if nrows == 0 or ncols == 0:
            print(f"-> Skipping {filename}: Missing target variables or regions.")
            continue

        fig, axes = plt.subplots(nrows, ncols, figsize=(SUB_W * ncols, SUB_H * nrows), 
                                 sharex=True, sharey='row')
        
        if nrows == 1: axes = np.expand_dims(axes, axis=0)
        if ncols == 1: axes = np.expand_dims(axes, axis=1)

        panel_idx = 0
        for row_idx, var in enumerate(target_vars):
            info = VARS_MAP[var]
            if var not in df_all.columns:
                continue
                
            for col_idx, region in enumerate(regions):
                ax = axes[row_idx, col_idx]

                ax.annotate(f"{chr(97 + panel_idx)}", xy=(0, 1.12), xycoords='axes fraction', va='top', ha='left', zorder=10, fontsize=FONT_PANEL, weight='bold')
                panel_idx += 1
                
                for ds_idx, (ds, style) in enumerate(DATASET_STYLE.items()):
                    sub = df_all[(df_all["Dataset"] == ds) & (df_all["Region"] == region)]
                    if sub.empty: continue
                    
                    agg_df = compute_weighted_stats(sub, var)
                    if len(agg_df) > 1:
                        x = agg_df.index.values
                        y_mean = agg_df["mean"].values

                        if var == "DSM":
                            y_mean = y_mean * 1e3
                        
                        ax.plot(x, y_mean, color=style["color"], linewidth=1.5, zorder=3)
                        add_regression_line(ax, x, y_mean, style, ds_idx)

                if row_idx == 0:
                    ax.set_title(region, fontweight='bold')
                    
                if col_idx == 0:
                    ax.set_ylabel(f"{info['label']} ({info['unit']})")
                    
                    if var == "DSM":
                        ax.ticklabel_format(axis='y', style='plain')

                        ax.relim()
                        ax.autoscale_view()

                        ax.text(0.02, 0.05, r"($\times 10^{-3}$)",
                                transform=ax.transAxes,
                                ha='left', va='bottom', fontsize=FONT_NOTE)
                    
                ax.legend(loc='best', frameon=True, framealpha=0.85, fontsize=7.5)
                    
        for col_idx in range(ncols):
            ax_bottom = axes[-1, col_idx]
            ax_bottom.set_xlabel("Year")
            ax_bottom.tick_params(labelbottom=True)

        plt.tight_layout(w_pad=0.5, h_pad=0.5)
        apply_figure_fontsize(fig)
        out_file = output_dir / filename
        plt.savefig(out_file, dpi=300)
        plt.close()

def plot_r2(df_spatial, metadata_enriched, output_dir):
    print("Generating Figures S10, S11 and S12 (R² analysis)...")
    
    if df_spatial.empty: return

    # =========================================================
    # MAP REGION DATA TO DF_SPATIAL
    # =========================================================
    region_mapping = {
        'Congo': 'Congo River Basin',
        'Namibia': 'Namibian Stations',
        'South Africa': 'South Africa Stations'
    }
    metadata_enriched['Region'] = metadata_enriched['Region'].replace(region_mapping)
    id_to_region = dict(zip(metadata_enriched['Catchment_id'], metadata_enriched['Region']))

    # Find the correct ID column in df_spatial to map the regions
    id_col = 'Catchment_id' if 'Catchment_id' in df_spatial.columns else 'id' if 'id' in df_spatial.columns else None
    
    if id_col:
        df_spatial['Region'] = df_spatial[id_col].map(id_to_region).fillna('Unknown')
    else:
        # Fallback if the Catchment ID is the DataFrame index
        df_spatial['Region'] = df_spatial.index.map(id_to_region).fillna('Unknown')

    # DATA PREPARATION (Shared)
    results, pairs = [], [('T', 'R'), ('T', 'ET'), ('P', 'R'), ('P', 'ET')]
    for ds, ds_data in df_spatial.groupby('Dataset'):
        for x_var, y_var in pairs:

            if f'{x_var}_mean' not in ds_data.columns or f'{y_var}_mean' not in ds_data.columns:
                continue
            mask = ds_data[[f'{x_var}_mean', f'{y_var}_mean']].notna().all(axis=1)
            if mask.sum() > 10:
                slope, _, r_val, p_val, _ = linregress(ds_data.loc[mask, f'{x_var}_mean'], ds_data.loc[mask, f'{y_var}_mean'])
                results.append({'Dataset': ds, 'Panel': 'b', 'Pair': f'{y_var} vs {x_var}', 'R2': r_val**2, 'Sign': '+' if slope > 0 else '-', 'P_value': p_val})

            ds_delta = ds_data[ds_data['Has_Delta']]
            if ds_delta.empty: continue
            
            if f'{x_var}_delta' not in ds_delta.columns or f'{y_var}_delta' not in ds_delta.columns:
                continue
            mask_delta = ds_delta[[f'{x_var}_delta', f'{y_var}_delta']].notna().all(axis=1)
            if mask_delta.sum() > 10:
                slope, _, r_val, p_val, _ = linregress(ds_delta.loc[mask_delta, f'{x_var}_delta'], ds_delta.loc[mask_delta, f'{y_var}_delta'])
                results.append({'Dataset': ds, 'Panel': 'a', 'Pair': f'Δ{y_var} vs Δ{x_var}', 'R2': r_val**2, 'Sign': '+' if slope > 0 else '-', 'P_value': p_val})

    df_results = pd.DataFrame(results)
    dataset_order = ["Obs-GC", "GLDAS", "ERA5"]
    
    palette = {ds: DATASET_STYLE[ds]["color"] for ds in dataset_order if ds in DATASET_STYLE}

    # PART 1: FIGURE S10 (Bar Plots Only)
    if not df_results.empty:
        fig, axes = plt.subplots(2, 1, figsize=(SUB_W * 1.3, 2 * SUB_H * 0.75), sharey=True)
        ax_a, ax_b = axes
        
        panels = [('a', ax_a, ['ΔR vs ΔT', 'ΔET vs ΔT', 'ΔR vs ΔP', 'ΔET vs ΔP'], "Coefficient of determination\n($r^2$ value)"),
                  ('b', ax_b, ['R vs T', 'ET vs T', 'R vs P', 'ET vs P'], "Coefficient of determination\n($r^2$ value)")]

        for panel_label, ax, pair_order, ylabel in panels:
            data = df_results[df_results['Panel'] == panel_label]
            if data.empty: continue
            
            sns.barplot(data=data, x='Pair', y='R2', hue='Dataset', palette=palette, 
                        hue_order=dataset_order, order=pair_order, ax=ax, 
                        linewidth=1.2, errorbar=None)
            
            ax.set(ylim=(0, 1.2), xlabel="", ylabel=ylabel)
            ax.text(0.02, 0.95, panel_label, transform=ax.transAxes, va='top', fontsize=FONT_PANEL)
            
            for p_bar in ax.patches:
                fc = p_bar.get_facecolor()
                darker_edge = (fc[0] * 0.7, fc[1] * 0.7, fc[2] * 0.7, fc[3])
                p_bar.set_edgecolor(darker_edge)

                if np.isnan(h := p_bar.get_height()) or h <= 0: continue
                if 0 <= (idx := int(round(p_bar.get_x() + p_bar.get_width() / 2))) < len(pair_order):
                    row = data[(data['Pair'] == pair_order[idx]) & np.isclose(data['R2'], h, atol=1e-4)]
                    if not row.empty and row.iloc[0]['P_value'] < 0.01:
                        ax.text(p_bar.get_x() + p_bar.get_width() / 2, h + 0.02, 
                                f"*({row.iloc[0]['Sign']})", ha='center', va='bottom', 
                                color='black', fontweight='bold')
            if ax.get_legend(): ax.get_legend().remove()

        fig.legend(handles=[mpatches.Patch(color=palette[ds], label=ds) for ds in dataset_order if ds in palette], 
                    loc='upper center', bbox_to_anchor=(0.5, 1.03), ncol=3, frameon=False)

        plt.tight_layout()
        apply_figure_fontsize(fig)
        out_file = output_dir / "Fig S10.tiff"
        plt.savefig(out_file, dpi=300, bbox_inches="tight")
        plt.close(fig)

    # PART 2: Figures S11 & S12 (Scatter Plots)
    region_markers = {
        'Congo River Basin': 's',
        'Namibian Stations': 'o',
        'South Africa Stations': 'o',
        'Unknown': 'o'
    }
    
    region_sizes = {
        'Congo River Basin': 110,
        'Namibian Stations': 70,
        'South Africa Stations': 70,
        'Unknown': 70
    }

    region_zorders = {
        'Congo River Basin': 5,
        'Namibian Stations': 2,
        'South Africa Stations': 2,
        'Unknown': 2
    }

    fig_definitions = [
        ("Fig S11.tiff", [
            ('P_mean', 'R_mean', 'Mean P (mm/year)', 'Mean R (mm/year)'),
            ('P_delta', 'R_delta', 'ΔP (mm/year)', 'ΔR (mm/year)'),
            ('T_mean', 'R_mean', 'Mean T (°C)', 'Mean R (mm/year)'),
            ('T_delta', 'R_delta', 'ΔT (°C)', 'ΔR (mm/year)')
        ]),
        ("Fig S12.tiff", [
            ('P_mean', 'ET_mean', 'Mean P (mm/year)', 'Mean ET (mm/year)'),
            ('P_delta', 'ET_delta', 'ΔP (mm/year)', 'ΔET (mm/year)'),
            ('T_mean', 'ET_mean', 'Mean T (°C)', 'Mean ET (mm/year)'),            
            ('T_delta', 'ET_delta', 'ΔT (°C)', 'ΔET (mm/year)')
        ])
    ]

    for filename, scatter_configs in fig_definitions:
        # Fig. S12 excludes the Obs-GC ET row, because ET is only shown for
        # GLDAS and ERA5 in the no_ObsGC_ET manuscript version.
        current_dataset_order = ["GLDAS", "ERA5"] if filename == "Fig S12.tiff" else dataset_order

        nrows = len(current_dataset_order)
        ncols = len(scatter_configs)

        fig, axes = plt.subplots(nrows, ncols, figsize=(ncols * SUB_W, nrows * SUB_H), 
                                 sharex='col', sharey='col',
                                 gridspec_kw={'hspace': 0.12, 'wspace': 0.25})

        if nrows == 1:
            axes = np.expand_dims(axes, axis=0)
        
        has_scatter_data = False

        for row_idx, ds in enumerate(current_dataset_order):
            ds_data = df_spatial[df_spatial['Dataset'] == ds]
            style = DATASET_STYLE.get(ds, {"color": "steelblue", "label": ds})

            available_regions = ds_data['Region'].unique()

            for col_idx, (x_col, y_col, xlabel, ylabel) in enumerate(scatter_configs):
                ax = axes[row_idx, col_idx]
                
                panel_idx = row_idx * len(scatter_configs) + col_idx
                panel_letter = chr(97 + panel_idx)
                
                ax.text(0.04, 0.96, f"{panel_letter}", transform=ax.transAxes, 
                        va='top', ha='left', zorder=10, fontsize=S23_FONT_PANEL, weight='bold')
                
                if x_col in ds_data.columns and y_col in ds_data.columns:
                    mask = ds_data[[x_col, y_col]].notna().all(axis=1)
                    
                    if mask.sum() > 0:
                        has_scatter_data = True
                        X, Y = ds_data.loc[mask, x_col], ds_data.loc[mask, y_col]

                        for region in available_regions:
                            df_region = ds_data[ds_data['Region'] == region]
                            mask_region = df_region[[x_col, y_col]].notna().all(axis=1)
                            
                            if mask_region.sum() > 0:
                                c_marker = region_markers.get(region, 'o')
                                c_size = region_sizes.get(region, 35)
                                c_zorder = region_zorders.get(region, 2)
                                c_alpha = 1 if c_marker == 's' else 0.5

                                base_color = style["color"]
                                if c_marker == 's':
                                    rgb = mcolors.to_rgb(base_color)
                                    c_color = (rgb[0] * 0.5, rgb[1] * 0.5, rgb[2] * 0.5)
                                else:
                                    c_color = base_color

                                ax.scatter(
                                    df_region.loc[mask_region, x_col], 
                                    df_region.loc[mask_region, y_col], 
                                    color=c_color, 
                                    s=c_size,
                                    alpha=c_alpha, 
                                    marker=c_marker, 
                                    zorder=c_zorder
                                )
                        
                        if mask.sum() > 2: 
                            slope, intercept, r_val, p_val, _ = linregress(X, Y)
                            x_line = np.array([X.min(), X.max()])
                            ax.plot(x_line, slope * x_line + intercept, 'k--', linewidth=1.5, zorder=1)
        
                            p_str = "p < 0.01" if p_val < 0.01 else f"p = {p_val:.3f}"
                            r2_str = format_r2_for_math(r_val**2, decimals=3, bold=False)
                            stats_text = (f"$y = {slope:.2f}x {'+' if intercept >= 0 else '-'} {abs(intercept):.2f}$\n"
                                          f"$r^2 {r2_str}$\n${p_str}$")
                            
                            x_mid = X.min() + (X.max() - X.min()) / 2
                            y_mid = Y.min() + (Y.max() - Y.min()) / 2
                            
                            corner_counts = {
                                'upper right': ((X > x_mid) & (Y > y_mid)).sum(),
                                'lower right': ((X > x_mid) & (Y < y_mid)).sum(),
                                'lower left':  ((X < x_mid) & (Y < y_mid)).sum()
                            }
                            
                            best_safe_loc = min(corner_counts, key=corner_counts.get)
                            
                            ax.plot([], [], ' ', label=stats_text)

                            # Reserve a blank upper band for the statistics box.
                            # This avoids covering scatter points or the fitted line.
                            add_axis_headroom(ax, top_frac=0.35, bottom_frac=0.04)

                            ax.legend(
                                    loc="upper right",
                                    bbox_to_anchor=(0.98, 0.98),
                                    handlelength=0,
                                    handletextpad=0,
                                    borderaxespad=0.25,
                                    facecolor='white',
                                    framealpha=0.8,
                                    edgecolor='lightgray',
                                    fontsize=S23_REGRESSION_LEGEND
                                )
                                
                if row_idx == len(current_dataset_order) - 1:
                    ax.set_xlabel(xlabel)
                    ax.tick_params(labelbottom=True)
                else:
                    ax.set_xlabel("")
                    ax.tick_params(labelbottom=False)
                
                ax.tick_params(labelleft=True)
                if col_idx == 0:
                    ax.set_ylabel(f"{style.get('label', ds)}")
                    ax.set_ylabel(ylabel)
                else:
                    ax.set_ylabel(ylabel)

        if has_scatter_data:
            apply_s23_fontsize(fig)
            out_file = output_dir / filename
            fig.savefig(out_file, dpi=300, bbox_inches="tight")

        plt.close(fig)

def plot_dumbbell(df_stats, metadata_enriched, output_dir):
    print("Generating Figures 4, S13, S14 and S15 (Extreme event)...")

    output_dir = Path(output_dir)
    output_dir.mkdir(parents=True, exist_ok=True)

    region_mapping = {
        "Congo": "Congo River Basin",
        "Namibia": "Namibian Stations",
        "South Africa": "South Africa Stations"
    }

    def safe_map(x):
        return region_mapping.get(x, x)

    id_to_region = dict(
        zip(
            metadata_enriched["Catchment_id"].astype(str),
            metadata_enriched["Region"].apply(safe_map)
        )
    )

    df_stats = df_stats.copy()
    df_stats["Region"] = df_stats["Catchment"].astype(str).map(id_to_region)

    # Fixed order to avoid accidental region mix-up
    tasks = [(None, "Fig 4.tiff")]

    region_task_order = [
        ("Congo River Basin", "Fig S13.tiff"),
        ("South Africa Stations", "Fig S15.tiff"),
        ("Namibian Stations", "Fig S14.tiff"),
    ]

    available_regions = set(df_stats["Region"].dropna().unique())

    for reg, fname in region_task_order:
        if reg in available_regions:
            tasks.append((reg, fname))

    seasons = [
        "DJF\n(Summer)",
        "MAM\n(Autumn)",
        "JJA\n(Winter)",
        "SON\n(Spring)"
    ]

    variables = ["P", "R", "ET"]
    percentiles = [50, 5, 95]

    pct_labels = [
        "Median",
        "5th percentile value",
        "95th percentile value"
    ]

    datasets = ["Obs-GC", "GLDAS", "ERA5"]
    periods = ["1980-2002", "2003-2025"]

    BLOCK_SIZE = 3
    PADDING = 0.5

    # Only runoff uses two dry/wet seasons in these figures
    TWO_DRY_SEASON_FILES = {"Fig 4.tiff", "Fig S14.tiff", "Fig S15.tiff"}
    TWO_WET_SEASON_FILES = {"Fig S14.tiff"}

    def add_season_box(ax, target_idx, color, xmin, xmax):
        """
        Draw one box around one seasonal block.
        """
        y_base = (len(seasons) - 1 - target_idx) * BLOCK_SIZE

        y_min = y_base - PADDING
        box_h = (len(datasets) - 1) + (2 * PADDING)

        x_ext = (xmax - xmin) * 0.02

        rect = mpatches.Rectangle(
            (xmin - x_ext, y_min),
            (xmax - xmin) + 2 * x_ext,
            box_h,
            fill=False,
            edgecolor=color,
            lw=2.0,
            zorder=5,
            clip_on=False
        )

        ax.add_patch(rect)

    def add_multi_season_box(ax, target_indices, color, xmin, xmax):
        """
        Draw one box covering one or multiple seasonal blocks.

        Used here so that the two driest runoff seasons can be covered
        by one shared red box.
        """
        if not target_indices:
            return

        y_mins = []
        y_maxs = []

        for target_idx in target_indices:
            y_base = (len(seasons) - 1 - target_idx) * BLOCK_SIZE

            y_min = y_base - PADDING
            y_max = y_base + (len(datasets) - 1) + PADDING

            y_mins.append(y_min)
            y_maxs.append(y_max)

        y_min = min(y_mins)
        y_max = max(y_maxs)
        box_h = y_max - y_min

        x_ext = (xmax - xmin) * 0.02

        rect = mpatches.Rectangle(
            (xmin - x_ext, y_min),
            (xmax - xmin) + 2 * x_ext,
            box_h,
            fill=False,
            edgecolor=color,
            lw=2.0,
            zorder=5,
            clip_on=False
        )

        ax.add_patch(rect)

    for region_name, filename in tasks:

        if region_name is None:
            df_plot_raw = df_stats.copy()
        else:
            df_plot_raw = df_stats[df_stats["Region"] == region_name].copy()

        if df_plot_raw.empty:
            continue

        df_plot = (
            df_plot_raw
            .groupby(["Dataset", "Period", "Season"])
            .median(numeric_only=True)
            .reset_index()
        )

        fig, axes = plt.subplots(
            3,
            3,
            figsize=(3 * SUB_W * 0.95, 3 * SUB_H * 1.05),
            sharey=True
        )

        plt.subplots_adjust(wspace=0.15, hspace=0.25)

        # --------------------------------------------------
        # Identify wettest/driest seasons independently
        # for P, R and ET, based on each variable's median
        # --------------------------------------------------
        variable_highlights = {}

        for var0 in variables:
            median_col = f"{var0}_50%"

            if median_col not in df_plot.columns:
                variable_highlights[var0] = {
                    "wet_indices": [0],
                    "dry_indices": [2]
                }
                continue

            # Obs-GC does not provide ET for the extreme-event comparison.
            # Exclude it from ET season identification, while retaining Obs-GC
            # for P and R.
            highlight_source = (
                df_plot[df_plot["Dataset"] != "Obs-GC"]
                if var0 == "ET"
                else df_plot
            )

            season_medians = (
                highlight_source
                .groupby("Season")[median_col]
                .mean()
                .reindex(seasons)
                .dropna()
            )

            if season_medians.empty:
                variable_highlights[var0] = {
                    "wet_indices": [0],
                    "dry_indices": [2]
                }
                continue

            # Wettest season(s)
            # Only runoff in Fig S15 uses two wet seasons.
            if (
                var0 == "R"
                and filename in TWO_WET_SEASON_FILES
                and len(season_medians) >= 2
            ):
                wet_indices = [
                    seasons.index(s)
                    for s in season_medians.nlargest(2).index
                ]
            else:
                wet_indices = [
                    seasons.index(season_medians.idxmax())
                ]

            # Driest season(s)
            # Only runoff uses two dry seasons in selected figures.
            if (
                var0 == "R"
                and filename in TWO_DRY_SEASON_FILES
                and len(season_medians) >= 2
            ):
                dry_indices = [
                    seasons.index(s)
                    for s in season_medians.nsmallest(2).index
                ]
            else:
                dry_indices = [
                    seasons.index(season_medians.idxmin())
                ]

            variable_highlights[var0] = {
                "wet_indices": wet_indices,
                "dry_indices": dry_indices
            }

        for r_idx, pct in enumerate(percentiles):
            for c_idx, var in enumerate(variables):

                ax = axes[r_idx, c_idx]
                var_col = f"{var}_{pct}%"

                if var_col not in df_plot.columns:
                    continue

                # --------------------------------------------------
                # Background separator lines between seasonal blocks
                # --------------------------------------------------
                for i in range(1, len(seasons)):
                    sep_pos = i * BLOCK_SIZE - 0.5
                    ax.axhline(
                        sep_pos,
                        color="black",
                        lw=0.8,
                        alpha=0.3,
                        zorder=1
                    )

                # --------------------------------------------------
                # Plot dumbbell points
                # --------------------------------------------------
                for s_idx, season in enumerate(seasons):

                    y_base = (len(seasons) - 1 - s_idx) * BLOCK_SIZE

                    for d_idx, ds in enumerate(datasets):

                        # Remove Obs-GC only from ET panels. Obs-GC remains
                        # unchanged for precipitation and runoff.
                        if var == "ET" and ds == "Obs-GC":
                            continue

                        style = DATASET_STYLE[ds]

                        subset = df_plot[
                            (df_plot["Season"] == season)
                            & (df_plot["Dataset"] == ds)
                        ]

                        p1_data = subset[subset["Period"] == periods[0]]
                        p2_data = subset[subset["Period"] == periods[1]]

                        if p1_data.empty or p2_data.empty:
                            continue

                        v1 = p1_data[var_col].values[0]
                        v2 = p2_data[var_col].values[0]

                        y_pos = y_base + d_idx

                        diff = v2 - v1

                        pct_change = (
                            (abs(diff) / abs(v1)) * 100
                            if v1 != 0
                            else 0
                        )

                        data_range = df_plot[var_col].max() - df_plot[var_col].min()
                        offset = data_range * 0.05 if data_range != 0 else 0.05

                        if pct_change < 3:

                            ax.scatter(
                                v1,
                                y_pos,
                                color=style["color"],
                                marker="*",
                                s=45,
                                zorder=4
                            )

                        else:

                            ax.hlines(
                                y_pos,
                                v1,
                                v2,
                                colors=style["color"],
                                lw=1.8,
                                alpha=0.7,
                                zorder=3
                            )

                            ax.scatter(
                                v1,
                                y_pos,
                                edgecolors=style["color"],
                                facecolors="none",
                                marker="o",
                                s=20,
                                zorder=4
                            )

                            ax.scatter(
                                v2,
                                y_pos,
                                color=style["color"],
                                marker="D",
                                s=20,
                                zorder=4
                            )

                            box_params = {
                                "facecolor": "lime" if diff > 0 else "gold",
                                "edgecolor": "none"
                            }

                            ax.text(
                                v2 + offset if diff > 0 else v2 - offset,
                                y_pos,
                                "+" if diff > 0 else "−",
                                ha="center",
                                va="center",
                                size=DUMBBELL_FONT_SYMBOL,
                                fontweight="bold",
                                bbox=dict(
                                    boxstyle=(
                                        "square,pad=0.1"
                                        if diff > 0
                                        else "circle,pad=0.1"
                                    ),
                                    **box_params
                                )
                            )

                # --------------------------------------------------
                # Formatting and scaling
                # --------------------------------------------------
                ax.relim()
                ax.autoscale_view()

                xmin, xmax = ax.get_xlim()

                # --------------------------------------------------
                # Variable-specific wet/dry season boxes
                # P uses P seasonality
                # R uses R seasonality
                # ET uses ET seasonality
                # --------------------------------------------------
                highlights = variable_highlights.get(var)

                if highlights is not None:

                    # Blue box: wettest season(s) for the current variable
                    # For R in Fig S15, this becomes one shared blue box
                    # covering the two wettest runoff seasons.
                    if pct in [50, 95]:
                        add_multi_season_box(
                            ax,
                            highlights["wet_indices"],
                            "blue",
                            xmin,
                            xmax
                        )

                    # Red box: driest season(s) for the current variable
                    # For R in Fig6, FigS7 and FigS8, this is one box
                    # spanning two lowest-runoff seasons.
                    if pct in [50, 5]:
                        add_multi_season_box(
                            ax,
                            highlights["dry_indices"],
                            "red",
                            xmin,
                            xmax
                        )

                ax.set_ylim(
                    -PADDING,
                    (len(seasons) * BLOCK_SIZE) - 1 + PADDING
                )

                tick_locs = [
                    (len(seasons) - 1 - i) * BLOCK_SIZE + 1
                    for i in range(len(seasons))
                ]

                ax.set_yticks(tick_locs)

                if c_idx == 0:
                    ax.set_yticklabels(seasons, fontsize=DUMBBELL_FONT_TICK)
                    ax.set_ylabel(
                        pct_labels[r_idx],
                        fontweight="bold"
                    )

                if r_idx == 2:
                    ax.set_xlabel(f"{var} (mm/month)")

                ax.grid(
                    axis="x",
                    linestyle="--",
                    alpha=0.3
                )

                panel_idx = r_idx * len(variables) + c_idx

                ax.annotate(
                    f"{chr(97 + panel_idx)}",
                    xy=(-0.08, 1.12),
                    xycoords="axes fraction",
                    va="top",
                    ha="left",
                    zorder=10,
                    fontsize=DUMBBELL_FONT_PANEL,
                    weight='bold'
                )

        # --------------------------------------------------
        # Legends
        # --------------------------------------------------
        # Use a single baseline and separated x-anchors to prevent the four
        # legend boxes from overlapping after bbox_inches="tight" export.
        legend_y = 0.045
        leg_args = {
            "frameon": True,
            "edgecolor": "black",
            "framealpha": 1,
            "loc": "lower center",
            "fontsize": DUMBBELL_FONT_LEGEND,
            "title_fontsize": DUMBBELL_FONT_LEGEND_TITLE,
            "borderpad": 0.30,
            "labelspacing": 0.30,
            "handlelength": 1.25,
            "handletextpad": 0.35,
            "columnspacing": 0.55
        }

        fig.legend(
            handles=[
                Line2D(
                    [0],
                    [0],
                    color=DATASET_STYLE[ds]["color"],
                    lw=4,
                    label=ds
                )
                for ds in datasets
            ],
            ncol=3,
            bbox_to_anchor=(0.13, legend_y),
            title="Datasets",
            **leg_args
        )

        fig.legend(
            handles=[
                Line2D(
                    [0],
                    [0],
                    color="black",
                    lw=0,
                    linestyle="None",
                    marker="o",
                    markerfacecolor="none",
                    markeredgecolor="black",
                    markeredgewidth=1.2,
                    label=f"P1: {periods[0]}"
                ),
                Line2D(
                    [0],
                    [0],
                    color="black",
                    lw=0,
                    linestyle="None",
                    marker="D",
                    markerfacecolor="black",
                    markeredgecolor="black",
                    markeredgewidth=1.2,
                    label=f"P2: {periods[1]}"
                )
            ],
            ncol=2,
            bbox_to_anchor=(0.36, legend_y),
            title="Periods",
            **leg_args
        )

        fig.legend(
            handles=[
                ChangeTypeLegendSymbol("square", "lime", "+"),
                ChangeTypeLegendSymbol("circle", "gold", "−"),
                Line2D(
                    [0],
                    [0],
                    marker="*",
                    color="gray",
                    linestyle="None",
                    markersize=12,
                    label="No change"
                )
            ],
            labels=["Increase", "Decrease", "No change"],
            handler_map={ChangeTypeLegendSymbol: HandlerChangeTypeLegendSymbol()},
            ncol=3,
            bbox_to_anchor=(0.61, legend_y),
            title="Change Types",
            **leg_args
        )

        fig.legend(
            handles=[
                mpatches.Patch(
                    edgecolor="red",
                    facecolor="none",
                    linewidth=1.5,
                    label="Driest season(s)"
                ),
                mpatches.Patch(
                    edgecolor="blue",
                    facecolor="none",
                    linewidth=1.5,
                    label="Wettest season(s)"
                )
            ],
            ncol=2,
            bbox_to_anchor=(0.86, legend_y),
            title="Seasons",
            **leg_args
        )

        plt.subplots_adjust(
            left=0.08,
            right=0.98,
            top=0.94,
            bottom=0.17,
            wspace=0.15,
            hspace=0.2
        )

        apply_dumbbell_fontsize(fig)

        plt.savefig(
            output_dir / filename,
            dpi=300,
            bbox_inches="tight"
        )

        plt.close()


def plot_histogram(data_map, metadata, output_dir):
    print("Generating Figures S16, S17 and S18 (Statistical distributions)...")
    
    catchment_groups = {
        'Whole region': metadata['Catchment_id'].dropna().astype(str).unique().tolist(),
        'Congo River Basin': metadata.loc[metadata['Region'] == 'Congo River Basin', 'Catchment_id'].dropna().astype(str).unique().tolist(),
        'Namibian Stations': metadata.loc[metadata['Region'] == 'Namibian Stations', 'Catchment_id'].dropna().astype(str).unique().tolist(),
        'South Africa Stations': metadata.loc[metadata['Region'] == 'South Africa Stations', 'Catchment_id'].dropna().astype(str).unique().tolist()
    }

    # Store all available datasets initially
    datasets_all = list(data_map.keys())
    n_cols = len(catchment_groups)
    
    if len(datasets_all) == 0:
        print("Error: No datasets found in data_map.")
        return

    var_config = {
        'P':  {'fig_name': 'Fig S16.tiff', 'xlabel': 'P (mm/month)'},
        'R':  {'fig_name': 'Fig S17.tiff', 'xlabel': 'R (mm/month)'},
        'ET': {'fig_name': 'Fig S18.tiff', 'xlabel': 'ET (mm/month)'}
    }

    monthly_data = {var: {ds: {} for ds in datasets_all} for var in var_config.keys()}
    files = list(INPUT_FOLDER.glob("*.csv"))
    
    for f in files:
        try:
            ds_orig, cid = f.stem.split("_", 1)
        except ValueError:
            continue
            
        group = "Obs-GC" if ds_orig in ["CAMELS", "GRDC"] else ds_orig
        
        if group in datasets_all:
            df = pd.read_csv(f)
            for var in var_config.keys():
                if var in df.columns:
                    monthly_data[var][group][str(cid)] = df[var].dropna().values

    for var, config in var_config.items():
        
        # Dynamically filter datasets: Exclude Obs-GC if the variable is ET
        current_datasets = [ds for ds in datasets_all if not (var == 'ET' and ds == 'Obs-GC')]
        n_rows = len(current_datasets)
        
        fig, axes = plt.subplots(nrows=n_rows, ncols=n_cols, 
                                 figsize=(n_cols * SUB_W * 0.6, n_rows * SUB_H * 0.6), 
                                 sharex='col')
        
        if n_rows == 1: axes = np.expand_dims(axes, axis=0)
        if n_cols == 1: axes = np.expand_dims(axes, axis=1)

        for i, dataset in enumerate(current_datasets):
            
            ds_color = DATASET_STYLE.get(dataset, {}).get("color", "lightgray")
            
            for j, (region_name, catch_ids) in enumerate(catchment_groups.items()):
                ax = axes[i, j]

                panel_label = f"{chr(97 + i * n_cols + j)}"
                ax.text(0.95, 0.95, panel_label, transform=ax.transAxes, 
                        va='top', ha='right', fontsize=FONT_PANEL, weight='bold')
                
                region_data = []
                for cid in catch_ids:
                    if cid in monthly_data[var][dataset]:
                        region_data.append(monthly_data[var][dataset][cid])
                
                if not region_data:
                    ax.text(0.5, 0.5, 'Insufficient Data', ha='center', va='center', transform=ax.transAxes, fontsize=FONT_NOTE)
                    if i == 0: ax.set_title(region_name, fontweight='bold')
                    if j == 0: ax.set_ylabel(f"{dataset}\nRelative frequency")
                    continue
                    
                region_data = np.concatenate(region_data)
                
                if len(region_data) == 0:
                    continue
                
                sns.histplot(region_data, bins=40, stat='density', color=ds_color, 
                             edgecolor='black', alpha=0.35, ax=ax)
                sns.kdeplot(region_data, color='black', linewidth=1, ax=ax)

                p1 = np.nanpercentile(region_data, 1)
                p5 = np.nanpercentile(region_data, 5)
                p95 = np.nanpercentile(region_data, 95)
                p99 = np.nanpercentile(region_data, 99)

                ax.axvline(p1, color='#ff66b2', linestyle='-.', linewidth=1)
                ax.axvline(p5, color='#ff66b2', linestyle='--', linewidth=1)
                ax.axvline(p95, color='purple', linestyle='--', linewidth=1)
                ax.axvline(p99, color='purple', linestyle='-.', linewidth=1)

                if i == 0:
                    ax.set_title(region_name, fontweight='bold')
                if j == 0:
                    ax.set_ylabel(f"{dataset}\nRelative frequency")
                else:
                    ax.set_ylabel("")
                    
                if i == n_rows - 1:
                    ax.set_xlabel(config['xlabel'])
                else:
                    ax.set_xlabel("")

        legend_elements = [
            Line2D([0], [0], color='black', lw=2, label='KDE'),
            Line2D([0], [0], color='#ff66b2', lw=2, linestyle='-.', label='1st percentile'),
            Line2D([0], [0], color='#ff66b2', lw=2, linestyle='--', label='5th percentile'),
            Line2D([0], [0], color='purple', lw=2, linestyle='--', label='95th percentile'),
            Line2D([0], [0], color='purple', lw=2, linestyle='-.', label='99th percentile')
        ]
        
        legend_ncol = 5
        legend_anchor_y = 0
        bottom_margin = 0.05

        fig.legend(handles=legend_elements, loc='lower center', ncol=legend_ncol,
                   bbox_to_anchor=(0.5, legend_anchor_y), frameon=False, fontsize=15)

        plt.tight_layout(rect=[0, bottom_margin, 1, 1])
        apply_figure_fontsize(fig)
        
        out_file = output_dir / config['fig_name']
        plt.savefig(out_file, dpi=300, bbox_inches='tight')
        plt.close()


# ==============================================================================
# MAIN BATCH PROCESSING
# ==============================================================================

if __name__ == "__main__":
    print(f"\n{'='*60}\nSTARTING PROCESSING\nInput Data: {INPUT_FOLDER.name}\nTarget Output: {OUTPUT_FOLDER.name}\n{'='*60}")
    OUTPUT_FOLDER.mkdir(exist_ok=True, parents=True)

    try:
        print("Loading data...")
        if not INPUT_FOLDER.exists() or not list(INPUT_FOLDER.glob("*.csv")):
             print(f"{'-'*40}\nWARNING: Input data not found in {INPUT_FOLDER.name}.\n{'-'*40}")
        else:
            metadata, data_map = load_all_catchment_data(INPUT_FOLDER)
            
            if not any(data_map.values()):
                 print(f"\nNo catchment data loaded. Check input data.")

            else:
                metadata_enriched, df_spatial_fig_r2 = compute_catchment_statistics(metadata, data_map)
                metadata_enriched.to_excel(OUTPUT_FOLDER / "catchments_with_stats.xlsx", index=False)

                df_extreme_stats = calculate_seasonal_quantiles_df(INPUT_FOLDER, metadata)
                
                plot_bands(data_map, OUTPUT_FOLDER)
                plot_budyko(metadata_enriched, OUTPUT_FOLDER)
                plot_temporal(data_map, metadata_enriched, OUTPUT_FOLDER)
                plot_r2(df_spatial_fig_r2, metadata_enriched, OUTPUT_FOLDER)
                plot_dumbbell(df_extreme_stats, metadata_enriched, OUTPUT_FOLDER)
                plot_histogram(data_map, metadata, OUTPUT_FOLDER)
                
                print(f"\nSuccessfully generated all figures!")

    except Exception as e:
        import traceback
        traceback.print_exc()
        print(f"\nAn unexpected error occurred processing {INPUT_FOLDER.name}: {e}")