harlstmgarch 0.1.0

Three-stage hybrid HAR-LSTM-GARCH framework for realized volatility forecasting

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) — [e-mail]
• Merwan Roudane — [e-mail] (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

pip install -e .

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

Quick start

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/.