Metadata-Version: 2.4
Name: heteroscedastic-edrvfl
Version: 0.1.0
Summary: Heteroscedastic ensemble deep RVFL model for high-frequency volatility forecasting and risk assessment.
Author: Aryan Bhambu, Ponnuthurai Nagaratnam Suganthan, Selvaraju Natarajan
License-Expression: MIT
Project-URL: Homepage, https://github.com/statsdl/heteroscedastic-edrvfl
Project-URL: Issues, https://github.com/statsdl/heteroscedastic-edrvfl/issues
Keywords: hedrvfl,edrvfl,heteroscedastic,volatility,forecasting,hyperopt
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.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Requires-Dist: pandas>=1.3
Provides-Extra: tuning
Requires-Dist: hyperopt>=0.2.7; extra == "tuning"
Requires-Dist: setuptools<81; extra == "tuning"
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"
Dynamic: license-file

[![Feature - Volatility Forecasting](https://img.shields.io/badge/Feature-Volatility%20Forecasting-blue)](https://github.com/statsdl/heteroscedastic-edrvfl)
[![GitHub last commit](https://img.shields.io/github/last-commit/statsdl/heteroscedastic-edrvfl)](https://github.com/statsdl/heteroscedastic-edrvfl/commits/main)
[![GitHub issues](https://img.shields.io/github/issues/statsdl/heteroscedastic-edrvfl)](https://github.com/statsdl/heteroscedastic-edrvfl/issues)
[![GitHub stars](https://img.shields.io/github/stars/statsdl/heteroscedastic-edrvfl)](https://github.com/statsdl/heteroscedastic-edrvfl/stargazers)
[![Python Version](https://img.shields.io/pypi/pyversions/heteroscedastic-edrvfl)](https://pypi.org/project/heteroscedastic-edrvfl/)
[![License](https://img.shields.io/pypi/l/heteroscedastic-edrvfl)](https://github.com/statsdl/heteroscedastic-edrvfl/blob/main/LICENSE)

A rich documentation is available in the GitHub repository.

# heteroscedastic-edrvfl

Heteroscedastic ensemble deep random vector functional link neural network for high-frequency volatility forecasting and risk assessment.

heteroscedastic-edrvfl is a Python package for volatility forecasting using the HedRVFL model with multiple output layers.

HedRVFL combines randomized neural feature mapping, ensemble deep RVFL representations, heteroscedastic volatility information, and efficient regularized output-layer learning. This allows the model to capture nonlinear volatility dynamics with fast training.

## Key Features

- **HedRVFL Model**: Implements a heteroscedastic ensemble deep RVFL model for high-frequency volatility forecasting and risk assessment.
- **Multiple Output Layers**: Uses layer-wise output readouts and aggregates predictions across hidden depths.
- **Randomized Feature Learning**: Uses randomly initialized hidden mappings with efficient output-layer training.
- **Feature Selection**: Includes feature-selection support to identify the most informative volatility predictors and reduce irrelevant input variables.
- **Pruning Strategy**: Uses pruning to remove weak or redundant hidden representations, improving model compactness and forecasting efficiency.
- **Hyperparameter Tuning**: Supports Hyperopt/TPE search for layer-wise model selection.
- **Forecasting Metrics**: Provides RMSE, MAE, NMAE, and Value-at-Risk helpers.

## Installation

Downloading locally and installing:

```bash
git clone https://github.com/statsdl/heteroscedastic-edrvfl.git
cd heteroscedastic-edrvfl
```

Install dependencies:

```bash
pip install -r requirements.txt
```

Install the package:

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

Using pip install from GitHub:

```bash
pip install git+https://github.com/statsdl/heteroscedastic-edrvfl.git
```

Using pip install from PyPI:

```bash
pip install heteroscedastic-edrvfl
```

Optional tuning installation:

```bash
pip install "heteroscedastic-edrvfl[tuning]"
```

Development installation:

```bash
pip install -e ".[dev]"
```

## Usage

### 1. HedRVFLRegressor

```python
from heteroscedastic_edrvfl import (
    HedRVFLRegressor,
    generate_synthetic_crypto_volatility,
    make_supervised_frame,
)

frame = generate_synthetic_crypto_volatility(n_steps=1200, seed=0)
X, y = make_supervised_frame(frame)

model = HedRVFLRegressor(n_layers=3, random_state=0)
model.fit(X[:800], y[:800])

pred = model.predict(X[800:])
print("Volatility forecasts:", pred[:5])
```

### 2. Hyperopt/TPE tuning

```python
from heteroscedastic_edrvfl import generate_synthetic_crypto_volatility, make_supervised_frame
from heteroscedastic_edrvfl.tuning import tune_hedrvfl

frame = generate_synthetic_crypto_volatility(n_steps=1200, seed=0)
X, y = make_supervised_frame(frame)

result = tune_hedrvfl(
    X[:900],
    y[:900],
    n_layers=3,
    max_evals=10,
    random_state=0,
)

print("Best validation loss:", result.validation_loss)
print("Best parameters:", result.best_params)
```

The benchmark reports RMSE, MAE, NMAE, Value-at-Risk, tuning time, training time, testing time, and selected hyperparameters.

## API Reference

### HedRVFLRegressor

A heteroscedastic ensemble deep random vector functional link regressor for volatility forecasting.

**Parameters**

- `n_layers` (int): Number of stacked randomized hidden layers.
- `layer_params` (list): Optional layer-wise parameter dictionaries.
- `random_state` (int): Random seed for reproducibility.
- `aggregation` (str): Prediction aggregation method, either `median` or `mean`.

**Methods**

- `fit(X, y)`: Fits the ensemble model.
- `predict(X)`: Generates final volatility forecasts.
- `predict(X, return_layers=True)`: Returns layer-wise predictions.

### Tuning utilities

- `hedrvfl_search_space`: Returns the default Hyperopt/TPE search space.
- `tune_hedrvfl`: Tunes HedRVFL hyperparameters.

### Metrics

- `root_mean_squared_error`: Computes RMSE.
- `mean_absolute_error`: Computes MAE.
- `normalized_mean_absolute_error`: Computes range-normalized MAE.
- `value_at_risk`: Computes normal Value-at-Risk from volatility forecasts.

## License

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

## Citation

If you use this package in your research, please cite:

```bibtex
@article{bhambu2025heteroscedastic,
  title={Heteroscedastic ensemble deep random vector functional link neural network with multiple output layers for High Frequency Volatility Forecasting and Risk Assessment},
  author={Bhambu, Aryan and Suganthan, Ponnuthurai Nagaratnam and Natarajan, Selvaraju},
  journal={Neurocomputing},
  volume={638},
  pages={130078},
  year={2025},
  doi={10.1016/j.neucom.2025.130078}
}

