kozy9/GWTCN

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

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')