volatility-gamm 0.1.0__tar.gz

volatility_gamm-0.1.0/CITATION.cff

@@ -0,0 +1,27 @@
+cff-version: 1.2.0
+message: "If you use GaMM in academic work, please cite this software and the associated paper."
+title: "GaMM"
+version: "0.1.0"
+date-released: "2026-06-25"
+authors:
+  - family-names: "Bhambu"
+    given-names: "Aryan"
+license: "MIT"
+repository-code: "https://github.com/statsdl/GaMM"
+preferred-citation:
+  type: article
+  title: "High frequency volatility forecasting and risk assessment using neural networks-based heteroscedasticity model"
+  authors:
+    - family-names: "Bhambu"
+      given-names: "Aryan"
+    - family-names: "Bera"
+      given-names: "Koushik"
+    - family-names: "Natarajan"
+      given-names: "Selvaraju"
+    - family-names: "Suganthan"
+      given-names: "Ponnuthurai Nagaratnam"
+  journal: "Engineering Applications of Artificial Intelligence"
+  volume: "149"
+  year: 2025
+  start: "110397"
+  doi: "10.1016/j.engappai.2025.110397"

volatility_gamm-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contributing to GaMM
+
+Contributions are welcome.
+
+## Development setup
+
+```bash
+git clone https://github.com/statsdl/GaMM.git
+cd GaMM
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+python -m pytest
+```
+
+## Pull requests
+
+Please keep changes focused, add tests for behavioral changes, and make sure the test suite passes before opening a pull request.
+
+## Issues
+
+Use GitHub Issues for bugs, feature requests, and questions about package behavior.

volatility_gamm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aryan Bhambu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

volatility_gamm-0.1.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include PYPI_README.md
+include LICENSE
+include CITATION.cff
+include CONTRIBUTING.md
+include requirements.txt
+recursive-include examples *.py
+recursive-include docs *.rst

volatility_gamm-0.1.0/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: volatility-gamm
+Version: 0.1.0
+Summary: GARCH-based MLP Mixer for high-frequency volatility forecasting and risk assessment.
+Author: Aryan Bhambu
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/statsdl/GaMM
+Project-URL: Issues, https://github.com/statsdl/GaMM/issues
+Keywords: gamm,garch,mlp-mixer,volatility,finance,high-frequency
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: pandas>=1.3
+Provides-Extra: model
+Requires-Dist: tensorflow>=2.12; extra == "model"
+Provides-Extra: tuning
+Requires-Dist: hyperopt>=0.2.7; extra == "tuning"
+Requires-Dist: setuptools<81; extra == "tuning"
+Provides-Extra: arch
+Requires-Dist: arch>=6.0; extra == "arch"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: hyperopt>=0.2.7; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: setuptools<81; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: full
+Requires-Dist: arch>=6.0; extra == "full"
+Requires-Dist: hyperopt>=0.2.7; extra == "full"
+Requires-Dist: setuptools<81; extra == "full"
+Requires-Dist: tensorflow>=2.12; extra == "full"
+Dynamic: license-file
+
+# Project description
+
+[![Feature - Volatility Forecasting](https://img.shields.io/badge/Feature-Volatility%20Forecasting-blue)](https://github.com/statsdl/GaMM)
+[![GitHub last commit](https://img.shields.io/github/last-commit/statsdl/GaMM)](https://github.com/statsdl/GaMM/commits/main)
+[![GitHub issues](https://img.shields.io/github/issues/statsdl/GaMM)](https://github.com/statsdl/GaMM/issues)
+[![GitHub stars](https://img.shields.io/github/stars/statsdl/GaMM)](https://github.com/statsdl/GaMM/stargazers)
+[![Python Version](https://img.shields.io/pypi/pyversions/volatility-gamm)](https://pypi.org/project/volatility-gamm/)
+[![License](https://img.shields.io/pypi/l/volatility-gamm)](https://github.com/statsdl/GaMM/blob/main/LICENSE)
+
+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}
+    }
+
+

volatility_gamm-0.1.0/PYPI_README.md

@@ -0,0 +1,218 @@
+# Project description
+
+[![Feature - Volatility Forecasting](https://img.shields.io/badge/Feature-Volatility%20Forecasting-blue)](https://github.com/statsdl/GaMM)
+[![GitHub last commit](https://img.shields.io/github/last-commit/statsdl/GaMM)](https://github.com/statsdl/GaMM/commits/main)
+[![GitHub issues](https://img.shields.io/github/issues/statsdl/GaMM)](https://github.com/statsdl/GaMM/issues)
+[![GitHub stars](https://img.shields.io/github/stars/statsdl/GaMM)](https://github.com/statsdl/GaMM/stargazers)
+[![Python Version](https://img.shields.io/pypi/pyversions/volatility-gamm)](https://pypi.org/project/volatility-gamm/)
+[![License](https://img.shields.io/pypi/l/volatility-gamm)](https://github.com/statsdl/GaMM/blob/main/LICENSE)
+
+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}
+    }
+
+