Upload LSTM — test RMSE 2.9386 m R² 0.5505

.gitattributes

@@ -33,3 +33,7 @@ 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
+fig_lstm_baseline_forecast.png filter=lfs diff=lfs merge=lfs -text
+fig_lstm_comparison.png filter=lfs diff=lfs merge=lfs -text
+fig_lstm_forecast.png filter=lfs diff=lfs merge=lfs -text
+lstm_model.keras filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,99 @@
+---
+license: mit
+tags:
+  - time-series
+  - forecasting
+  - lstm
+  - hydrology
+  - groundwater
+---
+
+# LSTM Groundwater Level Forecasting — UK
+
+A tuned LSTM model for single-step monthly groundwater level forecasting
+using meteorological variables as exogenous inputs.
+
+## Model Details
+
+| Parameter | Value |
+|---|---|
+| Architecture | LSTM(128) → Dropout(0.1) → Dense(32) → Dense(1) |
+| Framework | TensorFlow / Keras |
+| 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 |
+|---|---|
+| LSTM layers | 2 |
+| Units | 64 |
+| Dropout | 0.1 |
+| Learning rate | 0.000773 |
+| Batch size | 32 |
+
+## Test Set Performance
+
+| Metric | Value |
+|---|---|
+| RMSE | 2.9386 m |
+| MAE | 2.397 m |
+| MAPE | 3.671% |
+| R² | 0.5505 |
+| NSE | 0.5505 |
+
+> 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
+
+```
+├── lstm_model.keras    # Trained Keras model
+├── scaler_X.pkl        # Feature scaler (MinMaxScaler)
+├── scaler_y.pkl        # Target scaler (MinMaxScaler)
+├── 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/GWLSTM', 'lstm_model.keras'))
+scaler_X = joblib.load(hf_hub_download('kozy9/GWLSTM', 'scaler_X.pkl'))
+scaler_y = joblib.load(hf_hub_download('kozy9/GWLSTM', 'scaler_y.pkl'))
+
+# Provide a 24-month window of features
+X_window = pd.DataFrame({
+    'water_level'  : [...],   # 24 values
+    'temperature'  : [...],
+    'precipitation': [...],
+    'wind_speed'   : [...],
+})
+
+X_scaled = scaler_X.transform(X_window)
+X_input  = X_scaled.reshape(1, 24, 4)
+y_scaled = model.predict(X_input)
+pred     = scaler_y.inverse_transform(y_scaled)[0][0]
+print(f'Next month forecast: {pred:.2f} m')
+```

inference.py

@@ -0,0 +1,89 @@
+"""
+inference.py — LSTM Groundwater Level Forecasting
+==================================================
+Usage
+-----
+    from inference import load_model, forecast
+    model, scaler_X, scaler_y = load_model()
+    prediction = forecast(model, scaler_X, scaler_y, 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 / "lstm_model.keras"
+SCALER_X_PATH = Path(__file__).parent / "scaler_X.pkl"
+SCALER_Y_PATH = Path(__file__).parent / "scaler_y.pkl"
+CONFIG_PATH   = Path(__file__).parent / "model_config.json"
+
+
+def load_model():
+    """Load the LSTM model and both scalers."""
+    model    = keras_load(MODEL_PATH)
+    scaler_X = joblib.load(SCALER_X_PATH)
+    scaler_y = joblib.load(SCALER_Y_PATH)
+    print("LSTM model and scalers loaded.")
+    return model, scaler_X, scaler_y
+
+
+def load_config():
+    with open(CONFIG_PATH) as f:
+        return json.load(f)
+
+
+def forecast(model, scaler_X, scaler_y, X_window: pd.DataFrame):
+    """
+    Predict the next month's groundwater level.
+
+    Parameters
+    ----------
+    model     : loaded Keras model
+    scaler_X  : fitted MinMaxScaler for features
+    scaler_y  : fitted MinMaxScaler for 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_X.transform(X_window[required])
+    X_input  = X_scaled.reshape(1, lookback, len(required))
+
+    y_scaled    = model.predict(X_input, verbose=0).flatten()
+    prediction  = scaler_y.inverse_transform(y_scaled.reshape(-1, 1)).flatten()[0]
+
+    return float(prediction)
+
+
+if __name__ == "__main__":
+    model, scaler_X, scaler_y = 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
+    import numpy as np
+    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_X, scaler_y, dummy)
+    print(f"\nForecast (next month): {pred:.4f} m")

lstm_model.keras

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

model_config.json

@@ -0,0 +1,51 @@
+{
+  "model_type": "LSTM",
+  "architecture": "LSTM(128) \u2192 Dropout(0.1) \u2192 Dense(32) \u2192 Dense(1)",
+  "framework": "TensorFlow/Keras",
+  "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": {
+      "n_layers": 2,
+      "units_1": 64,
+      "dropout": 0.1,
+      "lr": 0.0007731576839806804,
+      "batch_size": 32
+    }
+  },
+  "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": 2.9386,
+    "MAE": 2.397,
+    "MAPE_pct": 3.671,
+    "R2": 0.5505,
+    "NSE": 0.5505
+  },
+  "notes": "Scaler fitted on train only. Oracle exog assumption \u2014 contemporaneous met vars used at forecast time."
+}

scaler_X.pkl

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

scaler_y.pkl

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