Upload TCN — test RMSE 3.5771 m R² 0.334

.gitattributes

@@ -33,3 +33,5 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+tcn_forecast_comparison.png filter=lfs diff=lfs merge=lfs -text
+tcn_model.keras filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,98 @@
+---
+license: mit
+tags:
+  - time-series
+  - forecasting
+  - tcn
+  - hydrology
+  - groundwater
+---
+
+# TCN Groundwater Level Forecasting — UK
+
+A tuned Temporal Convolutional Network (TCN) for single-step monthly groundwater
+level forecasting using meteorological variables as exogenous inputs.
+
+## Model Details
+
+| Parameter | Value |
+|---|---|
+| Architecture | TCN(nb_filters=32, kernel_size=3, dilations=[1, 2, 4, 8]) → Dense(1) |
+| Framework | TensorFlow / Keras (keras-tcn) |
+| Task | Single-step monthly forecasting |
+| Lookback window | 24 months |
+| Input features | water_level, temperature, precipitation, wind_speed |
+| Tuning method | Bayesian Optimisation (Keras Tuner, 20 trials) |
+
+## Data Splits
+
+| Split | Period | Months |
+|---|---|---|
+| Training | 1944-01-01 → 2007-10-01 | 766 |
+| Validation | 2007-11-01 → 2015-10-01 | 96 |
+| Test | 2015-11-01 → 2023-10-01 | 96 |
+
+## Best Hyperparameters
+
+| Parameter | Value |
+|---|---|
+| nb_filters | 32 |
+| kernel_size | 3 |
+| dilations | [1, 2, 4, 8] |
+| dropout_rate | 0.1 |
+| learning_rate | 0.001000 |
+| Receptive field | 61 months |
+
+## Test Set Performance
+
+| Metric | Value |
+|---|---|
+| RMSE | 3.5771 m |
+| MAE | 2.8901 m |
+| MAPE | 4.3138% |
+| R² | 0.334 |
+| NSE | 0.334 |
+
+> This model is part of a benchmark study comparing SARIMAX, LSTM, and TCN
+> for UK groundwater level forecasting.
+
+## Important Note
+
+Contemporaneous meteorological variables are used as inputs at forecast time
+(oracle assumption). Future met values are treated as known — consistent with
+the experimental setup used across all models in this study.
+
+## Repository Contents
+```
+├── tcn_model.keras        # Trained Keras TCN model
+├── scaler_features.pkl    # Feature scaler (MinMaxScaler, fit on train only)
+├── scaler_target.pkl      # Target scaler (MinMaxScaler, for inverse transform)
+├── model_config.json      # Config, hyperparameters & metrics
+├── inference.py           # Load model & generate forecasts
+└── README.md              # This file
+```
+
+## Quick Start
+```python
+from huggingface_hub import hf_hub_download
+from tensorflow.keras.models import load_model
+import joblib, pandas as pd, numpy as np
+
+model           = load_model(hf_hub_download('kozy9/GWTCN', 'tcn_model.keras'))
+scaler_features = joblib.load(hf_hub_download('kozy9/GWTCN', 'scaler_features.pkl'))
+scaler_target   = joblib.load(hf_hub_download('kozy9/GWTCN', 'scaler_target.pkl'))
+
+# Provide a 24-month window of features
+X_window = pd.DataFrame({
+    'water_level'  : [...],   # 24 values
+    'temperature'  : [...],
+    'precipitation': [...],
+    'wind_speed'   : [...],
+})
+
+X_scaled = scaler_features.transform(X_window)
+X_input  = X_scaled.reshape(1, 24, 4)
+y_scaled = model.predict(X_input)
+pred     = scaler_target.inverse_transform(y_scaled)[0][0]
+print(f'Next month forecast: {pred:.2f} m')
+```

inference.py

@@ -0,0 +1,88 @@
+"""
+inference.py — TCN Groundwater Level Forecasting
+=================================================
+Usage
+-----
+    from inference import load_model, forecast
+    model, scaler_features, scaler_target = load_model()
+    prediction = forecast(model, scaler_features, scaler_target, X_window)
+"""
+
+import json
+import joblib
+import numpy as np
+import pandas as pd
+from pathlib import Path
+from tensorflow.keras.models import load_model as keras_load
+
+MODEL_PATH          = Path(__file__).parent / "tcn_model.keras"
+SCALER_FEATURES_PATH = Path(__file__).parent / "scaler_features.pkl"
+SCALER_TARGET_PATH  = Path(__file__).parent / "scaler_target.pkl"
+CONFIG_PATH         = Path(__file__).parent / "model_config.json"
+
+
+def load_model():
+    """Load the TCN model and both scalers."""
+    model           = keras_load(MODEL_PATH)
+    scaler_features = joblib.load(SCALER_FEATURES_PATH)
+    scaler_target   = joblib.load(SCALER_TARGET_PATH)
+    print("TCN model and scalers loaded.")
+    return model, scaler_features, scaler_target
+
+
+def load_config():
+    with open(CONFIG_PATH) as f:
+        return json.load(f)
+
+
+def forecast(model, scaler_features, scaler_target, X_window: pd.DataFrame):
+    """
+    Predict the next month's groundwater level.
+
+    Parameters
+    ----------
+    model           : loaded Keras TCN model
+    scaler_features : fitted MinMaxScaler for all 4 input features
+    scaler_target   : fitted MinMaxScaler for water_level target
+    X_window        : DataFrame with columns [water_level, temperature,
+                      precipitation, wind_speed] and exactly 24 rows
+                      (the lookback window)
+
+    Returns
+    -------
+    prediction : float — forecasted water level in original units (m)
+    """
+    cfg      = load_config()
+    required = cfg['features']
+    lookback = cfg['lookback_months']
+
+    missing = [c for c in required if c not in X_window.columns]
+    if missing:
+        raise ValueError(f"X_window is missing columns: {missing}")
+    if len(X_window) != lookback:
+        raise ValueError(f"X_window must have {lookback} rows, got {len(X_window)}")
+
+    X_scaled   = scaler_features.transform(X_window[required])
+    X_input    = X_scaled.reshape(1, lookback, len(required))
+
+    y_scaled   = model.predict(X_input, verbose=0).flatten()
+    prediction = scaler_target.inverse_transform(y_scaled.reshape(-1, 1)).flatten()[0]
+
+    return float(prediction)
+
+
+if __name__ == "__main__":
+    model, scaler_features, scaler_target = load_model()
+    cfg = load_config()
+    print(f"Model: {cfg['architecture']}")
+    print(f"Test RMSE: {cfg['test_metrics']['RMSE']} m")
+
+    # Dummy window — replace with real data
+    dummy = pd.DataFrame({
+        'water_level'  : np.random.uniform(60, 75, 24),
+        'temperature'  : np.random.uniform(3, 15, 24),
+        'precipitation': np.random.uniform(20, 120, 24),
+        'wind_speed'   : np.random.uniform(10, 25, 24),
+    })
+    pred = forecast(model, scaler_features, scaler_target, dummy)
+    print(f"\nForecast (next month): {pred:.4f} m")

model_config.json

@@ -0,0 +1,57 @@
+{
+  "model_type": "TCN",
+  "architecture": "TCN(nb_filters=32, kernel_size=3, dilations=[1, 2, 4, 8]) \u2192 Dense(1)",
+  "framework": "TensorFlow/Keras (keras-tcn)",
+  "task": "Single-step monthly groundwater level forecasting",
+  "features": [
+    "water_level",
+    "temperature",
+    "precipitation",
+    "wind_speed"
+  ],
+  "target": "water_level",
+  "lookback_months": 24,
+  "horizon_months": 1,
+  "tuning": {
+    "method": "Bayesian Optimisation (Keras Tuner)",
+    "n_trials": 20,
+    "best_config": {
+      "nb_filters": 32,
+      "kernel_size": 3,
+      "dilations": [
+        1,
+        2,
+        4,
+        8
+      ],
+      "dropout_rate": 0.1,
+      "learning_rate": 0.001,
+      "receptive_field": 61
+    }
+  },
+  "data_splits": {
+    "train": {
+      "start": "1944-01-01",
+      "end": "2007-10-01",
+      "n_months": 766
+    },
+    "validation": {
+      "start": "2007-11-01",
+      "end": "2015-10-01",
+      "n_months": 96
+    },
+    "test": {
+      "start": "2015-11-01",
+      "end": "2023-10-01",
+      "n_months": 96
+    }
+  },
+  "test_metrics": {
+    "RMSE": 3.5771,
+    "MAE": 2.8901,
+    "MAPE_pct": 4.3138,
+    "R2": 0.334,
+    "NSE": 0.334
+  },
+  "notes": "Scaler fitted on train only. Oracle exog assumption \u2014 contemporaneous met vars used at forecast time."
+}

scaler_features.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3c0d11dcc6e97c52246a4bc0a08b926e75edaa58a268400446e4eafdd81c199a
+size 1127

scaler_target.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:865d8113514357d4b75338166ebba5771c914f7cd10b5892fc2187265ae4515c
+size 975

tcn_model.keras

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f7b000cf26bedc98461a4d960aa999747d38e39fe1545ddcf093f0f88cd0f537
+size 387592