Upload 2 files

app.py

@@ -0,0 +1,935 @@
+"""
+UK Groundwater Level Prediction Dashboard
+==========================================
+Benchmarking SARIMAX, LSTM, and TCN for Monthly Groundwater Level Prediction.
+
+Gradio app comparing three time-series forecasting models on a long-term UK
+borehole dataset (1944-2023). Presents pre-computed evaluation results and
+allows interactive scenario-based predictions.
+
+Author: Ahmed | Module: IJC319 Responsible Data Science | University of Sheffield
+"""
+
+import gradio as gr
+import pandas as pd
+import numpy as np
+import plotly.graph_objects as go
+from plotly.subplots import make_subplots
+import joblib
+from huggingface_hub import hf_hub_download
+from sklearn.metrics import mean_squared_error, mean_absolute_error, r2_score
+import warnings
+
+warnings.filterwarnings("ignore")
+
+
+# ======================================================================
+#  CONFIGURATION - UPDATE THESE TO MATCH YOUR DATA
+# ======================================================================
+# Check your CSV column names and update if they differ.
+# Check FEATURE_COLS order matches the order your scalers were
+# fitted on (open your notebook and verify).
+# ======================================================================
+
+DATE_COL = "date"
+TARGET_COL = "water_level"
+FEATURE_COLS = ["water_level", "temperature", "precipitation", "wind_speed"]
+EXOG_COLS = ["temperature", "precipitation", "wind_speed"]
+
+LOOKBACK = 24  # Sliding window length for LSTM/TCN
+
+# HuggingFace repository IDs
+LSTM_REPO = "kozy9/GWLSTM"
+TCN_REPO = "kozy9/GWTCN"
+SARIMAX_REPO = "kozy9/GWSarimax"
+
+# Local CSV paths (place alongside app.py in your HF Space)
+TRAIN_CSV = "uk_train.csv"
+VALIDATE_CSV = "uk_validate.csv"
+TEST_CSV = "uk_test.csv"
+
+# Consistent colour palette across all tabs
+COLOURS = {
+    "actual": "#1a2744",
+    "LSTM": "#2ecc71",
+    "TCN": "#e67e22",
+    "SARIMAX": "#3498db",
+    "Persistence": "#95a5a6",
+    "Seasonal": "#bdc3c7",
+}
+
+
+# ======================================================================
+#  DATA LOADING
+# ======================================================================
+
+print("=" * 60)
+print("Loading data files...")
+print("=" * 60)
+
+try:
+    df_train = pd.read_csv(TRAIN_CSV, parse_dates=[DATE_COL])
+    df_val = pd.read_csv(VALIDATE_CSV, parse_dates=[DATE_COL])
+    df_test = pd.read_csv(TEST_CSV, parse_dates=[DATE_COL])
+    print(f"   Train: {len(df_train)} rows")
+    print(f"   Validate: {len(df_val)} rows")
+    print(f"   Test: {len(df_test)} rows")
+except FileNotFoundError as e:
+    raise FileNotFoundError(
+        f"Could not find data file: {e}\n"
+        "Make sure uk_train.csv, uk_validate.csv, and uk_test.csv "
+        "are in the same directory as app.py."
+    )
+
+# Combine chronologically
+df_all = (
+    pd.concat([df_train, df_val, df_test], ignore_index=True)
+    .sort_values(DATE_COL)
+    .reset_index(drop=True)
+)
+test_start_idx = len(df_train) + len(df_val)
+test_dates = df_all[DATE_COL].iloc[test_start_idx:].values
+test_actual = df_all[TARGET_COL].iloc[test_start_idx:].values
+
+print(f"   Total records: {len(df_all)}")
+print(f"   Features: {FEATURE_COLS}")
+print(f"   Test set starts at index: {test_start_idx}")
+
+
+# ======================================================================
+#  MODEL LOADING (with error handling)
+# ======================================================================
+
+print("\n" + "=" * 60)
+print("Downloading models from HuggingFace...")
+print("=" * 60)
+
+# -- LSTM --
+lstm_model = None
+lstm_scaler_X = None
+lstm_scaler_y = None
+try:
+    print("   Loading LSTM from", LSTM_REPO, "...")
+    from tensorflow.keras.models import load_model
+
+    lstm_model = load_model(hf_hub_download(LSTM_REPO, "lstm_model.keras"))
+    lstm_scaler_X = joblib.load(hf_hub_download(LSTM_REPO, "scaler_X.pkl"))
+    lstm_scaler_y = joblib.load(hf_hub_download(LSTM_REPO, "scaler_y.pkl"))
+    print("   LSTM loaded successfully.")
+except Exception as e:
+    print(f"   WARNING - LSTM failed to load: {e}")
+
+# -- TCN --
+tcn_model = None
+tcn_scaler_X = None
+tcn_scaler_y = None
+try:
+    print("   Loading TCN from", TCN_REPO, "...")
+    from tensorflow.keras.models import load_model as load_keras_model
+
+    try:
+        from tcn import TCN as TCNLayer
+
+        tcn_model = load_keras_model(
+            hf_hub_download(TCN_REPO, "tcn_model.keras"),
+            custom_objects={"TCN": TCNLayer},
+        )
+    except ImportError:
+        tcn_model = load_keras_model(hf_hub_download(TCN_REPO, "tcn_model.keras"))
+    tcn_scaler_X = joblib.load(hf_hub_download(TCN_REPO, "scaler_features.pkl"))
+    tcn_scaler_y = joblib.load(hf_hub_download(TCN_REPO, "scaler_target.pkl"))
+    print("   TCN loaded successfully.")
+except Exception as e:
+    print(f"   WARNING - TCN failed to load: {e}")
+
+# -- SARIMAX --
+sarimax_model = None
+try:
+    print("   Loading SARIMAX from", SARIMAX_REPO, "...")
+    sarimax_model = joblib.load(
+        hf_hub_download(SARIMAX_REPO, "sarimax_model.pkl")
+    )
+    # Verify it is a SARIMAXResultsWrapper, not a Keras model
+    model_type = type(sarimax_model).__name__
+    if "SARIMAX" not in model_type and "Results" not in model_type:
+        print(f"   WARNING: Expected SARIMAXResultsWrapper but got {model_type}.")
+        print("   This may cause forecast errors. Re-run your SARIMAX notebook and")
+        print("   ensure the correct object is saved to the .pkl file.")
+    print("   SARIMAX loaded successfully.")
+except Exception as e:
+    print(f"   WARNING - SARIMAX failed to load: {e}")
+
+loaded_models = {
+    "LSTM": lstm_model is not None,
+    "TCN": tcn_model is not None,
+    "SARIMAX": sarimax_model is not None,
+}
+print(f"\n   Model status: {loaded_models}")
+
+
+# ======================================================================
+#  GENERATE TEST SET PREDICTIONS
+# ======================================================================
+
+print("\n" + "=" * 60)
+print("Generating test set predictions...")
+print("=" * 60)
+
+
+def predict_dl_test(model, scaler_X, scaler_y, data, feature_cols, test_start, lookback):
+    """Run sliding-window single-step-ahead inference over the test set."""
+    predictions = []
+    features = data[feature_cols].values
+    for i in range(test_start, len(data)):
+        if i - lookback < 0:
+            predictions.append(np.nan)
+            continue
+        window = features[i - lookback : i]
+        window_scaled = scaler_X.transform(window)
+        X_input = window_scaled.reshape(1, lookback, len(feature_cols))
+        y_scaled = model.predict(X_input, verbose=0)
+        pred = scaler_y.inverse_transform(y_scaled)[0][0]
+        predictions.append(pred)
+    return np.array(predictions)
+
+
+# LSTM predictions
+lstm_preds = np.full(len(df_test), np.nan)
+if lstm_model is not None:
+    print("   Running LSTM inference on test set...")
+    lstm_preds = predict_dl_test(
+        lstm_model, lstm_scaler_X, lstm_scaler_y,
+        df_all, FEATURE_COLS, test_start_idx, LOOKBACK,
+    )
+    print("   LSTM predictions complete.")
+
+# TCN predictions
+tcn_preds = np.full(len(df_test), np.nan)
+if tcn_model is not None:
+    print("   Running TCN inference on test set...")
+    tcn_preds = predict_dl_test(
+        tcn_model, tcn_scaler_X, tcn_scaler_y,
+        df_all, FEATURE_COLS, test_start_idx, LOOKBACK,
+    )
+    print("   TCN predictions complete.")
+
+# SARIMAX predictions
+sarimax_preds = np.full(len(df_test), np.nan)
+sarimax_lower = np.full(len(df_test), np.nan)
+sarimax_upper = np.full(len(df_test), np.nan)
+if sarimax_model is not None:
+    print("   Running SARIMAX forecast on test set...")
+    try:
+        exog_test = df_all[EXOG_COLS].iloc[test_start_idx:]
+        sarimax_fc = sarimax_model.get_forecast(steps=len(df_test), exog=exog_test)
+        sarimax_preds = sarimax_fc.predicted_mean.values
+        sarimax_ci = sarimax_fc.conf_int()
+        sarimax_lower = sarimax_ci.iloc[:, 0].values
+        sarimax_upper = sarimax_ci.iloc[:, 1].values
+        print("   SARIMAX forecast complete.")
+    except Exception as e:
+        print(f"   WARNING - SARIMAX forecast error: {e}")
+
+# Naive baselines
+print("   Computing naive baselines...")
+persistence_preds = df_all[TARGET_COL].iloc[test_start_idx - 1 : -1].values
+seasonal_preds = df_all[TARGET_COL].iloc[test_start_idx - 12 : len(df_all) - 12].values
+
+# Assemble results DataFrame
+results_df = pd.DataFrame({
+    "date": test_dates,
+    "actual": test_actual,
+    "LSTM": lstm_preds,
+    "TCN": tcn_preds,
+    "SARIMAX": sarimax_preds,
+    "SARIMAX_lower": sarimax_lower,
+    "SARIMAX_upper": sarimax_upper,
+    "Persistence": persistence_preds,
+    "Seasonal": seasonal_preds,
+})
+
+print("All predictions generated.\n")
+
+
+# ======================================================================
+#  METRICS
+# ======================================================================
+
+def compute_metrics(actual, predicted, name):
+    """Compute RMSE, MAE, MAPE, R-squared, NSE - handling NaN values."""
+    mask = ~np.isnan(predicted) & ~np.isnan(actual)
+    a, p = actual[mask], predicted[mask]
+    if len(a) == 0:
+        return {"Model": name, "RMSE (m)": "N/A", "MAE (m)": "N/A",
+                "MAPE (%)": "N/A", "R²": "N/A", "NSE": "N/A"}
+    rmse = np.sqrt(mean_squared_error(a, p))
+    mae = mean_absolute_error(a, p)
+    mape = np.mean(np.abs((a - p) / a)) * 100 if np.all(a != 0) else np.nan
+    r2 = r2_score(a, p)
+    nse = 1 - np.sum((a - p) ** 2) / np.sum((a - np.mean(a)) ** 2)
+    return {
+        "Model": name,
+        "RMSE (m)": round(rmse, 3),
+        "MAE (m)": round(mae, 3),
+        "MAPE (%)": round(mape, 2),
+        "R²": round(r2, 4),
+        "NSE": round(nse, 4),
+    }
+
+
+metrics_list = [
+    compute_metrics(test_actual, sarimax_preds, "SARIMAX"),
+    compute_metrics(test_actual, lstm_preds, "LSTM"),
+    compute_metrics(test_actual, tcn_preds, "TCN"),
+    compute_metrics(test_actual, persistence_preds, "Persistence Baseline"),
+    compute_metrics(test_actual, seasonal_preds, "Seasonal Naive Baseline"),
+]
+metrics_df = pd.DataFrame(metrics_list)
+
+
+# ======================================================================
+#  PREPROCESSING FOR SCENARIO PREDICTION
+# ======================================================================
+
+def preprocess_dl(last_24_rows, next_month_meteo, scaler_X, lookback=LOOKBACK):
+    """
+    Construct a scaled sliding window for LSTM/TCN inference.
+
+    Parameters
+    ----------
+    last_24_rows : pd.DataFrame
+        Most recent 24 months of observed data with columns matching FEATURE_COLS.
+    next_month_meteo : dict
+        User-specified values: {temperature, precipitation, wind_speed}.
+    scaler_X : MinMaxScaler
+        Fitted on training data only.
+
+    Returns
+    -------
+    np.ndarray of shape (1, 24, n_features)
+    """
+    # Use last known water_level as placeholder for target in the appended row
+    last_wl = last_24_rows[TARGET_COL].iloc[-1]
+    new_row = pd.DataFrame([{
+        TARGET_COL: last_wl,
+        "temperature": next_month_meteo["temperature"],
+        "precipitation": next_month_meteo["precipitation"],
+        "wind_speed": next_month_meteo["wind_speed"],
+    }])
+
+    # Append and take the last 24 rows as the input window
+    combined = pd.concat(
+        [last_24_rows[FEATURE_COLS], new_row[FEATURE_COLS]], ignore_index=True
+    )
+    window = combined.iloc[-lookback:].values
+    window_scaled = scaler_X.transform(window)
+    return window_scaled.reshape(1, lookback, len(FEATURE_COLS))
+
+
+# Prepare the last 24 observed months for the scenario tab
+last_24_df = df_all[FEATURE_COLS + [DATE_COL]].iloc[-LOOKBACK:].copy()
+last_24_display = last_24_df.copy()
+last_24_display[DATE_COL] = last_24_display[DATE_COL].dt.strftime("%Y-%m")
+last_24_display = last_24_display.rename(columns={
+    DATE_COL: "Month",
+    TARGET_COL: "Water Level (m)",
+    "temperature": "Temp (C)",
+    "precipitation": "Precip (mm)",
+    "wind_speed": "Wind (m/s)",
+})
+
+# Slider ranges from training data
+temp_min = float(df_train["temperature"].min())
+temp_max = float(df_train["temperature"].max())
+precip_min = float(df_train["precipitation"].min())
+precip_max = float(df_train["precipitation"].max())
+wind_min = float(df_train["wind_speed"].min())
+wind_max = float(df_train["wind_speed"].max())
+temp_mean = round(float(df_train["temperature"].mean()), 1)
+precip_mean = round(float(df_train["precipitation"].mean()), 1)
+wind_mean = round(float(df_train["wind_speed"].mean()), 1)
+
+
+# ======================================================================
+#  TAB 1: FORECAST COMPARISON (PRE-COMPUTED)
+# ======================================================================
+
+def build_forecast_comparison(show_lstm, show_tcn, show_sarimax, show_ci):
+    """Overlay plot of test set predictions vs actual with toggleable traces."""
+    fig = go.Figure()
+
+    # Actual
+    fig.add_trace(go.Scatter(
+        x=results_df["date"], y=results_df["actual"],
+        name="Actual (Ground Truth)", mode="lines",
+        line=dict(color=COLOURS["actual"], width=2.5),
+    ))
+
+    if show_sarimax:
+        fig.add_trace(go.Scatter(
+            x=results_df["date"], y=results_df["SARIMAX"],
+            name="SARIMAX", mode="lines",
+            line=dict(color=COLOURS["SARIMAX"], width=1.8),
+        ))
+        if show_ci:
+            fig.add_trace(go.Scatter(
+                x=list(results_df["date"]) + list(results_df["date"][::-1]),
+                y=list(results_df["SARIMAX_upper"]) + list(results_df["SARIMAX_lower"][::-1]),
+                fill="toself", fillcolor="rgba(52, 152, 219, 0.1)",
+                line=dict(color="rgba(0,0,0,0)"),
+                name="SARIMAX 95% CI", showlegend=True,
+            ))
+
+    if show_lstm:
+        fig.add_trace(go.Scatter(
+            x=results_df["date"], y=results_df["LSTM"],
+            name="LSTM", mode="lines",
+            line=dict(color=COLOURS["LSTM"], width=1.8),
+        ))
+
+    if show_tcn:
+        fig.add_trace(go.Scatter(
+            x=results_df["date"], y=results_df["TCN"],
+            name="TCN", mode="lines",
+            line=dict(color=COLOURS["TCN"], width=1.8),
+        ))
+
+    fig.update_layout(
+        title="Test Set: Model Predictions vs Actual Groundwater Level",
+        xaxis_title="Date",
+        yaxis_title="Groundwater Level (m)",
+        height=520,
+        template="plotly_white",
+        font=dict(family="IBM Plex Sans, system-ui, sans-serif"),
+        legend=dict(orientation="h", yanchor="bottom", y=1.02, xanchor="right", x=1),
+        margin=dict(t=60, b=40),
+        xaxis=dict(rangeslider=dict(visible=True, thickness=0.05)),
+    )
+    return fig
+
+
+# ======================================================================
+#  TAB 2: SCENARIO PREDICTION
+# ======================================================================
+
+def predict_scenario(temperature, precipitation, wind_speed):
+    """Run all three models with user-specified next-month meteorological values."""
+    meteo = {
+        "temperature": temperature,
+        "precipitation": precipitation,
+        "wind_speed": wind_speed,
+    }
+
+    results = {}
+
+    # -- LSTM --
+    if lstm_model is not None:
+        try:
+            X_in = preprocess_dl(last_24_df, meteo, lstm_scaler_X)
+            y_sc = lstm_model.predict(X_in, verbose=0)
+            results["LSTM"] = float(lstm_scaler_y.inverse_transform(y_sc)[0][0])
+        except Exception as e:
+            results["LSTM"] = f"Error: {e}"
+    else:
+        results["LSTM"] = "Model not loaded"
+
+    # -- TCN --
+    if tcn_model is not None:
+        try:
+            X_in = preprocess_dl(last_24_df, meteo, tcn_scaler_X)
+            y_sc = tcn_model.predict(X_in, verbose=0)
+            results["TCN"] = float(tcn_scaler_y.inverse_transform(y_sc)[0][0])
+        except Exception as e:
+            results["TCN"] = f"Error: {e}"
+    else:
+        results["TCN"] = "Model not loaded"
+
+    # -- SARIMAX --
+    if sarimax_model is not None:
+        try:
+            exog_row = pd.DataFrame([{
+                "temperature": temperature,
+                "precipitation": precipitation,
+                "wind_speed": wind_speed,
+            }])
+            fc = sarimax_model.get_forecast(steps=1, exog=exog_row)
+            results["SARIMAX"] = float(fc.predicted_mean.iloc[0])
+        except Exception as e:
+            results["SARIMAX"] = f"Error: {e}"
+    else:
+        results["SARIMAX"] = "Model not loaded"
+
+    # -- Build output text --
+    lines = ["## Predicted Groundwater Level (Next Month)\n"]
+    for model_name in ["LSTM", "TCN", "SARIMAX"]:
+        val = results[model_name]
+        if isinstance(val, float):
+            lines.append(f"- **{model_name}:** {val:.2f} m")
+        else:
+            lines.append(f"- **{model_name}:** {val}")
+
+    # SARIMAX sensitivity check
+    sarimax_note = ""
+    if isinstance(results.get("SARIMAX"), float):
+        try:
+            exog_alt = pd.DataFrame([{
+                "temperature": temp_mean,
+                "precipitation": precip_mean,
+                "wind_speed": wind_mean,
+            }])
+            fc_alt = sarimax_model.get_forecast(steps=1, exog=exog_alt)
+            alt_pred = float(fc_alt.predicted_mean.iloc[0])
+            diff = abs(results["SARIMAX"] - alt_pred)
+            if diff < 0.5:
+                sarimax_note = (
+                    "\n\n> **Note:** SARIMAX predictions are largely unaffected by "
+                    "meteorological inputs (prediction changed by only "
+                    f"{diff:.2f} m compared to mean conditions). This is consistent "
+                    "with this study's finding that the model relies on autoregressive "
+                    "structure rather than exogenous features."
+                )
+        except Exception:
+            pass
+
+    lines.append(sarimax_note)
+
+    # -- Build bar chart --
+    fig = go.Figure()
+    model_names = []
+    pred_values = []
+    bar_colours = []
+    for m in ["LSTM", "TCN", "SARIMAX"]:
+        if isinstance(results[m], float):
+            model_names.append(m)
+            pred_values.append(results[m])
+            bar_colours.append(COLOURS[m])
+
+    if pred_values:
+        fig.add_trace(go.Bar(
+            x=model_names, y=pred_values,
+            marker_color=bar_colours,
+            text=[f"{v:.2f} m" for v in pred_values],
+            textposition="outside",
+            width=0.5,
+        ))
+        fig.update_layout(
+            title="Scenario Prediction: All Models",
+            yaxis_title="Groundwater Level (m)",
+            height=400, template="plotly_white",
+            font=dict(family="IBM Plex Sans, system-ui, sans-serif"),
+            margin=dict(t=60, b=30),
+        )
+
+    return "\n".join(lines), fig
+
+
+# ======================================================================
+#  TAB 3: PERFORMANCE METRICS
+# ======================================================================
+
+def build_metrics_bar():
+    """Grouped bar chart for key metrics across all models."""
+    fig = make_subplots(
+        rows=1, cols=2,
+        subplot_titles=(
+            "Error Metrics (Lower is Better)",
+            "Goodness-of-Fit (Higher is Better)",
+        ),
+    )
+
+    models = metrics_df["Model"].tolist()
+    rmse_vals = pd.to_numeric(metrics_df["RMSE (m)"], errors="coerce")
+    mae_vals = pd.to_numeric(metrics_df["MAE (m)"], errors="coerce")
+    r2_vals = pd.to_numeric(metrics_df["R²"], errors="coerce")
+    nse_vals = pd.to_numeric(metrics_df["NSE"], errors="coerce")
+
+    colours = [COLOURS.get(m.split(" ")[0], "#888") for m in models]
+
+    fig.add_trace(go.Bar(
+        name="RMSE (m)", x=models, y=rmse_vals,
+        marker_color=colours, opacity=0.9,
+    ), row=1, col=1)
+    fig.add_trace(go.Bar(
+        name="MAE (m)", x=models, y=mae_vals,
+        marker_color=colours, opacity=0.55,
+    ), row=1, col=1)
+
+    fig.add_trace(go.Bar(
+        name="R²", x=models, y=r2_vals,
+        marker_color=colours, opacity=0.9,
+    ), row=1, col=2)
+    fig.add_trace(go.Bar(
+        name="NSE", x=models, y=nse_vals,
+        marker_color=colours, opacity=0.55,
+    ), row=1, col=2)
+
+    fig.update_layout(
+        height=430, template="plotly_white",
+        font=dict(family="IBM Plex Sans, system-ui, sans-serif"),
+        showlegend=True,
+        legend=dict(orientation="h", yanchor="bottom", y=1.08, xanchor="center", x=0.5),
+        margin=dict(t=70, b=30),
+    )
+    return fig
+
+
+# ======================================================================
+#  TAB 4: FEATURE IMPORTANCE
+# ======================================================================
+# UPDATE: Replace these placeholder values with your actual results
+# from your notebooks.
+
+lstm_importance = {
+    "water_level": 0.85,    # UPDATE with your actual value
+    "temperature": 0.12,    # UPDATE with your actual value
+    "wind_speed": 0.08,     # UPDATE with your actual value
+    "precipitation": 0.03,  # UPDATE with your actual value
+}
+
+sarimax_importance = {
+    "temperature": -0.02,    # UPDATE with your actual value
+    "precipitation": -0.01,  # UPDATE with your actual value
+    "wind_speed": 0.005,     # UPDATE with your actual value
+}
+
+
+def build_feature_importance():
+    """Side-by-side horizontal bar charts for LSTM and SARIMAX."""
+    fig = make_subplots(
+        rows=1, cols=2,
+        subplot_titles=(
+            "LSTM - Permutation Feature Importance",
+            "SARIMAX - Permutation Feature Importance",
+        ),
+        horizontal_spacing=0.2,
+    )
+
+    # LSTM
+    lstm_sorted = sorted(lstm_importance.items(), key=lambda x: x[1])
+    lstm_features = [p[0] for p in lstm_sorted]
+    lstm_values = [p[1] for p in lstm_sorted]
+
+    fig.add_trace(go.Bar(
+        y=lstm_features, x=lstm_values,
+        orientation="h",
+        marker_color=[COLOURS["LSTM"] if v > 0 else "#e74c3c" for v in lstm_values],
+        text=[f"{v:.3f}" for v in lstm_values],
+        textposition="outside",
+        name="LSTM", showlegend=False,
+    ), row=1, col=1)
+
+    # SARIMAX
+    sar_sorted = sorted(sarimax_importance.items(), key=lambda x: x[1])
+    sar_features = [p[0] for p in sar_sorted]
+    sar_values = [p[1] for p in sar_sorted]
+
+    fig.add_trace(go.Bar(
+        y=sar_features, x=sar_values,
+        orientation="h",
+        marker_color=[COLOURS["SARIMAX"] if v > 0 else "#e74c3c" for v in sar_values],
+        text=[f"{v:.3f}" for v in sar_values],
+        textposition="outside",
+        name="SARIMAX", showlegend=False,
+    ), row=1, col=2)
+
+    fig.add_vline(x=0, line_dash="dot", line_color="#ccc", row=1, col=2)
+
+    fig.update_layout(
+        height=380, template="plotly_white",
+        font=dict(family="IBM Plex Sans, system-ui, sans-serif"),
+        margin=dict(t=60, b=30, l=130),
+    )
+    return fig
+
+
+# ======================================================================
+#  TAB 5: MODEL ARCHITECTURES
+# ======================================================================
+# UPDATE: Replace all (UPDATE) placeholders with your actual
+# hyperparameters from your notebooks.
+
+ARCHITECTURE_MD = """
+## SARIMAX
+
+| Parameter | Value |
+|-----------|-------|
+| Order (p, d, q) | *(UPDATE)* |
+| Seasonal Order (P, D, Q, s) | *(UPDATE, e.g. (P, D, Q, 12))* |
+| Optimisation | Optuna (TPE sampler, 80 trials, seed=42) |
+| Exogenous Variables | temperature, precipitation, wind_speed |
+| Key Finding | Performance driven by autoregressive structure; meteorological inputs statistically insignificant |
+
+[View on HuggingFace](https://huggingface.co/Kozy9/GWSarimax)
+
+---
+
+## LSTM
+
+| Parameter | Value |
+|-----------|-------|
+| Architecture | *(UPDATE: e.g. 2 LSTM layers)* |
+| Units per Layer | *(UPDATE)* |
+| Dropout | *(UPDATE)* |
+| Optimiser | *(UPDATE: e.g. Adam)* |
+| Lookback Window | 24 months |
+| Optimisation | Keras Tuner (BayesianOptimization) |
+| Input Shape | (24, 4) - 24 timesteps x 4 features |
+
+[View on HuggingFace](https://huggingface.co/Kozy9/GWLSTM)
+
+---
+
+## TCN
+
+| Parameter | Value |
+|-----------|-------|
+| Receptive Field | *(UPDATE)* |
+| Filters | *(UPDATE)* |
+| Kernel Size | *(UPDATE)* |
+| Dilations | *(UPDATE: e.g. [1, 2, 4, 8])* |
+| Dropout | *(UPDATE)* |
+| Lookback Window | 24 months |
+| Optimisation | Keras Tuner (BayesianOptimization, 20 trials) |
+| Input Shape | (24, 4) - 24 timesteps x 4 features |
+| Baseline RMSE (before tuning) | 5.91 m (R-squared/NSE = -0.82) |
+| Tuned RMSE | 3.58 m (R-squared/NSE = 0.33) |
+| Underperformance Factors | Small dataset (~766 training sequences), constrained search space, MSE loss under-predicting peaks |
+
+[View on HuggingFace](https://huggingface.co/Kozy9/GWTCN)
+
+---
+
+## Preprocessing (Shared Across Models)
+
+| Component | Detail |
+|-----------|--------|
+| Scaling | MinMaxScaler (separate scalers for features and target) |
+| Fitting | Scalers fitted on training data only (no data leakage) |
+| Lookback Window | 24 monthly timesteps for LSTM and TCN |
+| Target Variable | water_level (metres) |
+"""
+
+
+# ======================================================================
+#  GRADIO APP
+# ======================================================================
+
+with gr.Blocks(
+    title="UK Groundwater Level Prediction",
+    theme=gr.themes.Soft(
+        primary_hue="teal",
+        secondary_hue="blue",
+        font=["IBM Plex Sans", "system-ui", "sans-serif"],
+    ),
+    css="""
+        .main-header { text-align: center; margin-bottom: 0.3rem; }
+        .sub-header  { text-align: center; color: #666; font-size: 0.95rem; margin-bottom: 1rem; }
+        .caveat-box  { background: #f0f7ff; border-left: 4px solid #3498db;
+                        padding: 12px 16px; border-radius: 6px; margin: 10px 0;
+                        font-size: 0.88rem; color: #2c3e50; }
+        .warn-box    { background: #fef9e7; border-left: 4px solid #f39c12;
+                        padding: 12px 16px; border-radius: 6px; margin: 10px 0;
+                        font-size: 0.88rem; color: #7d6608; }
+    """,
+) as app:
+
+    gr.Markdown(
+        "# Benchmarking SARIMAX, LSTM, and TCN for Monthly Groundwater Level Prediction",
+        elem_classes="main-header",
+    )
+    gr.Markdown(
+        "Comparing statistical and deep learning forecasting models on 79 years of UK "
+        "borehole observations (1944-2023). Module IJC319 | University of Sheffield.",
+        elem_classes="sub-header",
+    )
+
+    # ──────────────────────────────────────────────
+    # TAB 1 - FORECAST COMPARISON
+    # ──────────────────────────────────────────────
+    with gr.Tab("Forecast Comparison"):
+        gr.Markdown("### Test Set: Predicted vs Actual Groundwater Level")
+        gr.Markdown(
+            "Toggle individual model traces with the checkboxes below. "
+            "Use the date-range slider beneath the chart to zoom into specific periods."
+        )
+
+        with gr.Row():
+            fc_lstm = gr.Checkbox(value=True, label="LSTM")
+            fc_tcn = gr.Checkbox(value=True, label="TCN")
+            fc_sarimax = gr.Checkbox(value=True, label="SARIMAX")
+            fc_ci = gr.Checkbox(value=True, label="SARIMAX 95% CI")
+
+        fc_plot = gr.Plot(
+            value=build_forecast_comparison(True, True, True, True),
+        )
+
+        for chk in [fc_lstm, fc_tcn, fc_sarimax, fc_ci]:
+            chk.change(
+                fn=build_forecast_comparison,
+                inputs=[fc_lstm, fc_tcn, fc_sarimax, fc_ci],
+                outputs=fc_plot,
+            )
+
+    # ──────────────────────────────────────────────
+    # TAB 2 - SCENARIO PREDICTION
+    # ──────────────────────────────────────────────
+    with gr.Tab("Scenario Prediction"):
+        gr.Markdown("### Interactive Next-Month Prediction")
+        gr.Markdown(
+            "Adjust the meteorological sliders to define a scenario for the next month. "
+            "All three models will generate a prediction based on the last 24 months "
+            "of observed data shown below."
+        )
+
+        with gr.Accordion("Important Methodological Caveats", open=False):
+            gr.Markdown(
+                '<div class="caveat-box">'
+                "<strong>Different forecasting procedures:</strong> LSTM and TCN produce "
+                "single-step-ahead predictions using the last 24 months as a sliding window input. "
+                "SARIMAX forecasts using its fitted autoregressive parameters and internal state. "
+                "These are not identical forecasting procedures. See the Performance Metrics tab "
+                "for further details on this methodological asymmetry."
+                "</div>"
+            )
+            gr.Markdown(
+                '<div class="warn-box">'
+                "Predictions are based on models trained on a <strong>single UK observation "
+                "borehole</strong> dataset (1944-2023) and should <strong>not</strong> be used for "
+                "operational groundwater management decisions."
+                "</div>"
+            )
+
+        with gr.Row():
+            with gr.Column(scale=1):
+                gr.Markdown("#### Historical Context (Last 24 Observed Months)")
+                gr.DataFrame(
+                    value=last_24_display,
+                    label="Lookback Window",
+                    interactive=False,
+                )
+
+            with gr.Column(scale=1):
+                gr.Markdown("#### Next Month's Meteorological Scenario")
+                sl_temp = gr.Slider(
+                    minimum=temp_min, maximum=temp_max, value=temp_mean,
+                    step=0.5, label="Temperature (C)",
+                )
+                sl_precip = gr.Slider(
+                    minimum=precip_min, maximum=precip_max, value=precip_mean,
+                    step=1.0, label="Precipitation (mm)",
+                )
+                sl_wind = gr.Slider(
+                    minimum=wind_min, maximum=wind_max, value=wind_mean,
+                    step=0.1, label="Wind Speed (m/s)",
+                )
+                btn_predict = gr.Button(
+                    "Predict Next Month", variant="primary", size="lg",
+                )
+
+        pred_output = gr.Markdown()
+        pred_chart = gr.Plot()
+
+        btn_predict.click(
+            fn=predict_scenario,
+            inputs=[sl_temp, sl_precip, sl_wind],
+            outputs=[pred_output, pred_chart],
+        )
+
+    # ──────────────────────────────────────────────
+    # TAB 3 - PERFORMANCE METRICS
+    # ──────────────────────────────────────────────
+    with gr.Tab("Performance Metrics"):
+        gr.Markdown("### Evaluation Metrics on Held-Out Test Set")
+        gr.Markdown(
+            "All models evaluated on the same test period. Persistence (previous month's value) "
+            "and seasonal naive (same month, previous year) baselines provide benchmarking context."
+        )
+
+        gr.DataFrame(value=metrics_df, label="Performance Metrics", interactive=False)
+
+        gr.Markdown(
+            '<div class="caveat-box">'
+            "<strong>Methodological note:</strong> SARIMAX was evaluated using "
+            "<em>multi-step-ahead forecasting</em>; LSTM and TCN used "
+            "<em>single-step-ahead (rolling one-step) evaluation</em>. Direct metric "
+            "comparison should be interpreted with caution due to this methodological "
+            "difference. Multi-step forecasting accumulates error over the forecast horizon, "
+            "which may disadvantage SARIMAX relative to the deep learning models."
+            "</div>"
+        )
+
+        gr.Markdown("### Visual Comparison")
+        gr.Plot(value=build_metrics_bar())
+
+    # ──────────────────────────────────────────────
+    # TAB 4 - FEATURE IMPORTANCE
+    # ──────────────────────────────────────────────
+    with gr.Tab("Feature Importance"):
+        gr.Markdown("### Permutation Feature Importance Analysis")
+        gr.Markdown(
+            "Permutation feature importance measures how much each input variable "
+            "contributes to model accuracy. A feature is shuffled, and the resulting "
+            "increase in prediction error indicates its importance."
+        )
+
+        gr.Plot(value=build_feature_importance())
+
+        with gr.Row():
+            with gr.Column():
+                gr.Markdown(
+                    "#### LSTM Interpretation\n\n"
+                    "**Water level history** is the dominant input feature, confirming that "
+                    "the LSTM relies heavily on autoregressive patterns in the target series. "
+                    "Among meteorological variables, **temperature** is the most influential, "
+                    "followed by wind speed and precipitation."
+                )
+            with gr.Column():
+                gr.Markdown(
+                    "#### SARIMAX Interpretation\n\n"
+                    "**Negative importance values** indicate that the exogenous meteorological "
+                    "features did not contribute meaningfully to prediction accuracy. In some "
+                    "cases, removing these features actually *improved* predictions. This is "
+                    "consistent with the finding that SARIMAX performance is driven by its "
+                    "**autoregressive and seasonal components**, not by external weather inputs."
+                )
+
+        gr.Markdown(
+            '<div class="warn-box">'
+            "<strong>Note:</strong> Feature importance analysis was not performed for "
+            "the TCN model in this study due to the model's weaker overall performance "
+            "and the focus on comparing the two stronger-performing approaches."
+            "</div>"
+        )
+
+    # ──────────────────────────────────────────────
+    # TAB 5 - MODEL ARCHITECTURES
+    # ──────────────────────────────────────────────
+    with gr.Tab("Model Architectures"):
+        gr.Markdown("### Model Specifications and Hyperparameters")
+        gr.Markdown(
+            "Full details of each model's architecture, optimisation approach, and "
+            "training configuration. Links to HuggingFace repositories are provided "
+            "for full reproducibility."
+        )
+        gr.Markdown(ARCHITECTURE_MD)
+
+    # ─────────────────────────���────────────────────
+    # FOOTER
+    # ──────────────────────────────────────────────
+    gr.Markdown(
+        "---\n"
+        "**IJC319 Responsible Data Science** | University of Sheffield | "
+        "[LSTM Repo](https://huggingface.co/Kozy9/GWLSTM) | "
+        "[TCN Repo](https://huggingface.co/Kozy9/GWTCN) | "
+        "[SARIMAX Repo](https://huggingface.co/Kozy9/GWSarimax)\n\n"
+        "*This tool is a research demonstrator trained on a single UK observation borehole. "
+        "Predictions are site-specific and must not be used for operational water management decisions.*"
+    )
+
+
+# ======================================================================
+#  LAUNCH
+# ======================================================================
+
+if __name__ == "__main__":
+    app.launch()

requirements.txt

@@ -0,0 +1,10 @@
+gradio>=4.0.0
+tensorflow
+keras-tcn
+joblib
+pandas
+numpy
+plotly
+huggingface_hub
+scikit-learn
+statsmodels