README.md

---
license: mit
tags:
  - time-series
  - forecasting
  - sarimax
  - hydrology
  - groundwater
---

# SARIMAX Groundwater Level Forecasting — UK

A SARIMAX model trained to forecast monthly groundwater levels (GWLs)
using historical water level data and meteorological variables.

## Model Details

| Parameter | Value |
|---|---|
| Architecture | SARIMAX(2, 1, 1)x(2, 0, 2, 12) |
| Seasonal period | 12 months |
| Target | Water level (m) |
| Exogenous variables | Temperature (°C), Precipitation (mm), Wind Speed (km/h) |
| Feature engineering | None — raw exog only |
| Training period | 1944-01-01 → 2015-10-01 (862 months) |
| Test period | 2015-11-01 → 2023-10-01 (96 months) |

## Hyperparameter Tuning

Bayesian search : 50 trials | criterion: validation RMSE
ranked by out-of-sample validation RMSE.



## Test Set Performance

| Metric | Value |
|---|---|
| RMSE | 5.154 |
| MAE | 4.1969 |
| MAPE (%) | 6.5844 |
| R² | -0.3826 |
| NSE | -0.3826 |

> This model is a statistical baseline for benchmarking against
> deep learning approaches (LSTM, TCN).

## Important Note

Contemporaneous meteorological variables are used as exogenous inputs
at forecast time (oracle assumption). Future met values are treated as known.
This matches the experimental setup used for LSTM/TCN comparisons in this study.

## Repository Contents

```
├── sarimax_model.pkl     # Fitted model (joblib)
├── model_config.json     # Parameters, metadata & metrics
├── inference.py          # Load model & generate forecasts
└── README.md             # This file
```

## Quick Start

```python
from huggingface_hub import hf_hub_download
import joblib, pandas as pd, numpy as np

model_path = hf_hub_download(repo_id='kozy9/GWSarimax', filename='sarimax_model.pkl')
model = joblib.load(model_path)

idx   = pd.date_range(start='2024-01-01', periods=12, freq='MS')
X_fut = pd.DataFrame({
    'temperature'  : [...],
    'precipitation': [...],
    'wind_speed'   : [...],
}, index=idx)

fc   = model.get_forecast(steps=12, exog=X_fut)
pred = fc.predicted_mean
ci   = fc.conf_int()
```