Metadata-Version: 2.4
Name: harlstmgarch
Version: 0.1.0
Summary: Three-stage hybrid HAR-LSTM-GARCH framework for realized volatility forecasting
Author-email: Belhimer Hocine <hbelhimer@escf.constantine.dz>, Merwan Roudane <merwanroudane920@gmail.com>
License: MIT
Keywords: volatility forecasting,realized volatility,HAR,LSTM,GARCH,hybrid models,financial econometrics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Requires-Dist: statsmodels>=0.14
Requires-Dist: arch>=6.0
Requires-Dist: tensorflow>=2.13
Requires-Dist: scikit-learn>=1.3
Requires-Dist: matplotlib>=3.7

# harlstmgarch

A Python library implementing the **three-stage hybrid HAR-LSTM-GARCH
framework** for realized volatility forecasting.

**Authors:**

- **Belhimer Hocine** — Maître de conférences A,
  Higher School of Accounting and Finance of Constantine (ESCF Constantine)
  — <hbelhimer@escf.constantine.dz>
- **Merwan Roudane** — <merwanroudane920@gmail.com>
  ([github.com/merwanroudane](https://github.com/merwanroudane))

## The model

The framework follows a sequential decomposition principle:

| Stage | Component | Role |
|-------|-----------|------|
| 1 | **HAR** (Corsi, 2009) | Linear filter for the persistent, multi-scale volatility dynamics (daily / weekly / monthly components, OLS) |
| 2 | **LSTM** | Recurrent neural network that learns the *non-linear* patterns left in the HAR residuals |
| 3 | **GARCH(1,1)** | Models the conditional variance of the hybrid forecast errors — time-varying prediction intervals for risk management |

The point forecast is `H_{t+1} = HAR_{t+1} + LSTM residual forecast`,
and Stage 3 wraps it in a 95% interval `H_{t+1} ± 1.96 σ_{z,t+1}`.

Reference: Ben Romdhane, W., & Boubaker, H. (2026). *A Hybrid
HAR-LSTM-GARCH Model for Forecasting Volatility in Energy Markets.*
Journal of Risk and Financial Management, 19(2), 77.

## Installation

```bash
pip install -e .
```

Requires Python ≥ 3.10 with `tensorflow`, `arch`, `statsmodels`,
`pandas`, `scikit-learn`, `matplotlib`.

## Quick start

```python
import numpy as np
from harlstmgarch import (
    HARLSTMGARCH, load_realized_measures,
    har_components, chronological_split, metrics,
)

rv = load_realized_measures("RealizedMeasures03_10.csv")["RV"]
df = har_components(np.log(rv))               # log-RV, HAR features
train, val, test = chronological_split(df, train=0.70, val=0.15)

model = HARLSTMGARCH(lstm_kwargs={"lookback": 20, "units": 32})
model.fit(train, val)
fc = model.forecast(test)                     # strictly one-step-ahead

print(metrics.scoreboard(
    np.exp(test["RV"]),
    {"HAR": np.exp(fc.har), "Hybrid": np.exp(fc.point)},
))
print("95% coverage:",
      metrics.interval_coverage(np.exp(test["RV"]),
                                np.exp(fc.lower), np.exp(fc.upper)))
```

## Package layout

```
harlstmgarch/
├── data.py      # RV construction, HAR components, chronological split
├── har.py       # Stage 1 — HAR-RV model (OLS, statsmodels)
├── lstm.py      # Stage 2 — LSTM on HAR residuals (TensorFlow/Keras)
├── garch.py     # Stage 3 — GARCH(1,1) on hybrid errors (arch)
├── hybrid.py    # HARLSTMGARCH orchestrator
├── metrics.py   # RMSE/MAE/MAPE/R²/QLIKE, McLeod-Li, Diebold-Mariano
└── plots.py     # publication-quality figures
examples/
└── run_case_study.py   # full empirical case study (2003-2010 RV data)
```

## Case study

`examples/run_case_study.py` reproduces the full pipeline on 1,842 days
of realized volatility computed from intraday data (Sept 2003 – Dec 2010,
spanning the Global Financial Crisis), evaluates HAR, standalone LSTM and
the hybrid out-of-sample, runs McLeod-Li and Diebold-Mariano tests, and
exports all figures and tables to `assets/`.
