garch11-ged 0.1.0
Fast GARCH(1,1) with GED innovations implementation in C++
License: MIT
Requires Python: >=3.6
Keywords: garch, volatility, financial-modeling, time-series, econometrics

# GARCH(1,1) with GED Innovations

A fast C++ implementation of GARCH(1,1) model with Generalized Error Distribution (GED) innovations, with Python bindings via pybind11.

## Features

- **Fast C++ Implementation**: Core algorithms implemented in C++ for optimal performance
- **GED Innovations**: Support for Generalized Error Distribution for heavy-tailed financial returns
- **Easy Python Interface**: Simple and intuitive Python API similar to popular packages like `arch`
- **Comprehensive Output**: Get fitted volatilities, residuals, forecasts, and model statistics
- **Parameter Validation**: Built-in parameter constraints and stationarity checks

## Installation

### From PyPI (recommended)

```bash
pip install garch11_ged
```

### From Source

```bash
git clone https://github.com/yourusername/garch11_ged.git
cd garch11_ged
pip install .
```

### Development Installation

```bash
git clone https://github.com/yourusername/garch11_ged.git
cd garch11_ged
pip install -e ".[dev]"
```

## Quick Start

```python
import numpy as np
import garch11_ged

# Generate sample return data
np.random.seed(42)
returns = np.random.normal(0, 0.01, 1000)

# Fit GARCH(1,1) model with GED innovations
model = garch11_ged.GARCH11_GED()
model.fit(returns)

# Print model summary
print(model.summary())

# Get parameter estimates
params = model.parameters
print(f"Parameters: {params}")

# Get fitted volatilities
volatilities = model.volatilities

# Forecast volatility
forecast = model.predict_volatility(horizon=10)
print(f"10-step forecast: {forecast}")
```

## API Reference

### GARCH11_GED Class

#### Constructor

```python
model = garch11_ged.GARCH11_GED()
model = garch11_ged.GARCH11_GED(mu, omega, alpha, beta, nu)
```

#### Methods

- `fit(returns, max_iter=1000, tolerance=1e-6)`: Fit the model to data
- `predict_volatility(horizon=1)`: Forecast volatility
- `get_parameters()`: Get parameter estimates [mu, omega, alpha, beta, nu]
- `get_volatilities()`: Get fitted conditional volatilities
- `get_residuals()`: Get fitted residuals
- `get_standardized_residuals()`: Get standardized residuals
- `get_log_likelihood()`: Get log-likelihood value
- `get_aic()`: Get AIC (Akaike Information Criterion)
- `get_bic()`: Get BIC (Bayesian Information Criterion)
- `summary()`: Get detailed model summary

#### Properties

- `parameters`: Model parameters
- `volatilities`: Fitted volatilities
- `residuals`: Fitted residuals
- `standardized_residuals`: Standardized residuals
- `log_likelihood`: Log-likelihood value
- `aic`: AIC value
- `bic`: BIC value
- `fitted`: Whether model is fitted

### Convenience Functions

```python
# Fit model in one line
model = garch11_ged.fit_garch(returns)
```

## Model Specification

The GARCH(1,1) model with GED innovations is specified as:

**Mean Equation:**
```
r_t = μ + ε_t
```

**Variance Equation:**
```
σ²_t = ω + α·ε²_{t-1} + β·σ²_{t-1}
```

**Innovation Distribution:**
```
ε_t | F_{t-1} ~ GED(0, σ_t, ν)
```

Where:
- `μ` is the mean return
- `ω > 0` is the constant term
- `α ≥ 0` is the ARCH parameter
- `β ≥ 0` is the GARCH parameter  
- `α + β < 1` for stationarity
- `ν > 0` is the GED shape parameter

## Performance

This implementation is significantly faster than pure Python implementations:

```python
import time
import numpy as np

# Generate large dataset
returns = np.random.normal(0, 0.01, 10000)

# Time the fitting
start_time = time.time()
model = garch11_ged.GARCH11_GED()
model.fit(returns)
end_time = time.time()

print(f"Fitting time: {end_time - start_time:.3f} seconds")
```

## Requirements

- Python ≥ 3.7
- NumPy ≥ 1.17.0
- C++14 compatible compiler

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Citation

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

```bibtex
@software{garch11_ged,
  title={GARCH(1,1) with GED Innovations},
  author={Your Name},
  year={2024},
  url={https://github.com/yourusername/garch11_ged}
}
```

## Acknowledgments

This implementation is based on the GARCH modeling framework from the rugarch R package by Alexios Ghalanos.