Metadata-Version: 2.4
Name: varpy
Version: 2.0.0
Summary: Value at Risk tools
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas-stubs>=2.2.3.250308
Requires-Dist: pandas>=2.2.3
Requires-Dist: arch>=7.2.0
Requires-Dist: numpy>=2.2.5
Requires-Dist: scipy>=1.15.3
Requires-Dist: scipy-stubs>=1.15.3.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Dynamic: license-file

# VaRpy - Value at Risk Models

A Python library for computing Value at Risk (VaR) and Conditional Value at Risk (CVaR) using various statistical distributions and GARCH models.

## Recent Refactoring

The codebase has undergone a major refactoring to improve code organization, maintainability, and consistency. Here are the key changes:

### 1. Class-Based Architecture

All VaR models now follow a consistent class-based architecture inheriting from `BaseVar`:

```python
class BaseVar:
    def __init__(self, theta: float, horizon: int):
        self.theta = theta
        self.horizon = horizon
        self._var = None
        self._cvar = None

    def run(self, ret: NDArray[np.float64]) -> None:
        """Compute VaR and CVaR. To be implemented by subclasses."""
        raise NotImplementedError
```

### 2. Standardized Model Structure

Each VaR model (Normal, Student's t, EVT) follows the same pattern:

- Constructor takes only `theta` and `horizon` parameters
- `run` method accepts returns data as input
- Private helper methods for specific computations
- Consistent method naming and documentation

Example structure:
```python
class SomeVar(BaseVar):
    def __init__(self, theta: float, horizon: int):
        super().__init__(theta, horizon)

    def run(self, ret: NDArray[np.float64]) -> None:
        # 1. Get GARCH forecasts
        # 2. Process innovations
        # 3. Fit distribution
        # 4. Compute VaR/CVaR
        pass
```

### 3. Improved Type Hints

- Added comprehensive type hints using `numpy.typing`
- Consistent use of `NDArray[np.float64]` for numpy arrays
- Proper return type annotations for all methods

### 4. Modular Design

Each model is broken down into logical private methods:

- `_get_garch_forecasts`: GARCH model fitting and forecasting
- `_get_excess_innovations`: Innovation processing
- `_fit_distribution`: Distribution fitting
- `_compute_unconditional_var`: Unconditional VaR calculation
- `_compute_var`: Final VaR computation
- `_compute_cvar`: Final CVaR computation

### 5. Enhanced Documentation

- Comprehensive docstrings for all classes and methods
- Clear parameter and return type documentation
- Consistent documentation style across all models

### 6. Code Organization

- Moved models to `varpy/var/models/` directory
- Consistent file naming (lowercase with underscores)
- Clear separation of concerns between models

## Available Models

### Normal Distribution
- Assumes returns follow a normal distribution
- Uses GARCH(1,1) with Gaussian innovations
- Suitable for well-behaved financial returns

### Student's t Distribution
- Assumes returns follow a Student's t distribution
- Uses GARCH(1,1) with Student's t innovations
- Better suited for heavy-tailed returns

### Extreme Value Theory (EVT)
- Uses Generalized Pareto Distribution for tail modeling
- Combines GARCH with EVT for better tail estimation
- Most suitable for extreme risk measurement

## Usage Example

```python
import numpy as np
from varpy.var.models import Normal, Student, EVT

# Initialize model
model = Normal(theta=0.05, horizon=1)

# Compute VaR and CVaR
returns = np.array([...])  # Your return data
model.run(returns)

# Get results
var = model.var
cvar = model.cvar
```

## Dependencies

- numpy
- scipy
- arch (for GARCH modeling)

## Contributing

When adding new VaR models, please follow the established pattern:
1. Inherit from `BaseVar`
2. Implement the `run` method
3. Use private helper methods for specific computations
4. Add comprehensive type hints and documentation
5. Follow the modular design pattern 
