volatility-gamm 0.1.0

GARCH-based MLP Mixer for high-frequency volatility forecasting and risk assessment.

Project description

A rich documentation is available in the GitHub repository.

volatility-gamm

GARCH-based MLP Mixer for high-frequency volatility forecasting and risk assessment.

volatility-gamm is a Python package for volatility forecasting using GARCH-based MLP Mixer models. The package is designed for high-frequency financial time-series experiments where volatility dynamics, risk estimation, and nonlinear temporal structure are important.

The package combines GARCH-family volatility information with MLP-Mixer style neural feature learning. This allows volatility forecasts to benefit from both econometric conditional-volatility modeling and neural nonlinear representation learning.

This package provides two primary components:

• GARCH-based volatility features: utilities for using GARCH, GJR-GARCH, Threshold GARCH, AVGARCH, and FIGARCH conditional-volatility estimates as model inputs.

• GaMM neural model: a configurable MLP-Mixer style architecture for volatility forecasting with normalization, activation, dropout, feed-forward dimension, and mixer-block controls.

Both components are useful for volatility forecasting and risk assessment because financial time series often contain volatility clustering, nonlinear temporal dependence, and heavy-tailed risk behavior.

Key Features

• GARCH-based MLP Mixer: Combines GARCH-family volatility features with neural MLP-Mixer modeling.

• High-Frequency Volatility Forecasting: Designed for intraday financial volatility forecasting tasks.

• Econometric Feature Integration: Supports GARCH, GJR-GARCH, Threshold GARCH, AVGARCH, and FIGARCH-style volatility features.

• Neural Forecasting Model: Provides Keras-based GaMM model construction and compilation utilities.

• Hyperparameter Tuning: Includes Hyperopt/TPE-based tuning helpers for reproducible model selection.

• Risk Assessment: Includes Value-at-Risk utilities for volatility-based financial risk evaluation.

• Forecasting Metrics: Provides RMSE, MAE, MAPE, NMAE, and QLIKE.

• Research-Oriented Design: Suitable for reproducible academic experiments in volatility forecasting and financial risk modeling.

Installation

Downloading locally and installing

git clone https://github.com/statsdl/GaMM.git
cd GaMM

Install dependencies:

pip install -r requirements.txt

Install the package:

pip install -e .

Using pip install from GitHub

pip install git+https://github.com/statsdl/GaMM.git

Using pip install from PyPI

pip install volatility-gamm

Optional full installation

pip install "volatility-gamm[full]"

Development installation

pip install -e ".[dev]"

Usage

1. GaMM model

Example

import numpy as np
from gamm.model import compile_gamm_model

X_train = np.random.randn(200, 20, 6).astype("float32")
y_train = np.random.rand(200).astype("float32")

model = compile_gamm_model(
    input_shape=(X_train.shape[1], X_train.shape[2]),
    learning_rate=0.001,
    activation="relu",
    n_block=2,
    dropout=0.1,
    ff_dim=64,
)

model.fit(X_train, y_train, epochs=5, batch_size=32, verbose=0)

predictions = model.predict(X_train[:10], verbose=0)
print("Volatility forecasts:", predictions.reshape(-1))

2. Volatility forecasting metrics

Example

import numpy as np
from gamm.metrics import (
    root_mean_squared_error,
    mean_absolute_error,
    mean_absolute_percentage_error,
    normalized_mean_absolute_error,
    quasi_likelihood,
    value_at_risk,
)

y_true = np.array([0.12, 0.15, 0.09, 0.18])
y_pred = np.array([0.11, 0.14, 0.10, 0.17])

print("RMSE:", root_mean_squared_error(y_true, y_pred))
print("MAE:", mean_absolute_error(y_true, y_pred))
print("MAPE:", mean_absolute_percentage_error(y_true, y_pred))
print("NMAE:", normalized_mean_absolute_error(y_true, y_pred))
print("QLIKE:", quasi_likelihood(y_true, y_pred))
print("VaR:", value_at_risk(0.05, y_pred))

3. Synthetic benchmark

Example

python examples/run_synthetic_benchmark.py

The benchmark compares GaMM with GARCH-family volatility estimates and reports volatility forecasting and risk metrics.

API Reference

Model utilities

build_gamm_model: Builds a GARCH-based MLP Mixer model.

compile_gamm_model: Builds and compiles the GaMM model with Adam optimizer and MSE loss.

Tuning utilities

gamm_tuning_space: Returns the default Hyperopt/TPE search space.

tune_gamm: Tunes GaMM hyperparameters.

GARCH utilities

append_garch_features: Adds GARCH-family conditional-volatility features when optional dependencies are installed.

Metrics

root_mean_squared_error: Computes RMSE.

mean_absolute_error: Computes MAE.

mean_absolute_percentage_error: Computes MAPE.

normalized_mean_absolute_error: Computes range-normalized MAE.

quasi_likelihood: Computes QLIKE.

value_at_risk: Computes normal Value-at-Risk from volatility forecasts.

How It Works

GaMM:

The model receives a lagged volatility feature tensor with lagged return and standard deviation-based volatility measure.

Mixer blocks learn interactions across time steps and variables.

The final dense output layer produces the volatility forecast.

GARCH-based features:

Conditional-volatility estimates are generated from GARCH-family models.

These features provide the neural model with econometric volatility information.

Risk assessment:

Forecasted volatility can be converted into Value-at-Risk estimates.

Forecast quality is evaluated using volatility-specific metrics such as QLIKE.

Dataset Details

Component	Description
Input type	High-frequency financial time-series features
Forecasting target	Volatility / realized volatility
Optional features	GARCH-family conditional volatilities
Model type	GARCH-based MLP Mixer
Split type	Chronological train-validation-test split
Metrics	RMSE, MAE, MAPE, NMAE, QLIKE, VaR

License

This project is licensed under the MIT License. See the LICENSE file for details.

Citation

If you are using this package in your research, please cite the following paper:

@article{bhambu2025highfrequency,
  title={High frequency volatility forecasting and risk assessment using neural networks-based heteroscedasticity model},
  author={Bhambu, Aryan and Bera, Koushik and Natarajan, Selvaraju and Suganthan, Ponnuthurai Nagaratnam},
  journal={Engineering Applications of Artificial Intelligence},
  volume={149},
  pages={110397},
  year={2025},
  doi={10.1016/j.engappai.2025.110397}
}