Metadata-Version: 2.4
Name: asr-var-cvar-tail-risk
Version: 1.0.0
Summary: Reproducible research package for Value at Risk, Conditional Value at Risk, and tail-risk analysis.
Author-email: Alpha Stochastic Research <research@asr-lab.online>
License-Expression: MIT
Project-URL: Homepage, https://asr-lab.online
Project-URL: Repository, https://github.com/Alpha-Stochastic-Research/asr-var-cvar-tail-risk
Project-URL: Documentation, https://github.com/Alpha-Stochastic-Research/asr-var-cvar-tail-risk#readme
Project-URL: Issues, https://github.com/Alpha-Stochastic-Research/asr-var-cvar-tail-risk/issues
Keywords: quantitative-finance,risk-management,value-at-risk,conditional-value-at-risk,expected-shortfall,monte-carlo,student-t,backtesting
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: pandas>=2.0
Requires-Dist: matplotlib>=3.7
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: nbconvert>=7.0; extra == "dev"
Requires-Dist: ipykernel>=6.0; extra == "dev"
Requires-Dist: jupyterlab>=4.0; extra == "dev"
Dynamic: license-file

<div align="center">

# Value at Risk versus Conditional Value at Risk

### A Rigorous Framework for Measuring Extreme Tail Risk and Regulatory Compliance

**Alpha Stochastic Research**  
*Independent Quantitative Finance Research Laboratory*

[![Python](https://img.shields.io/badge/Python-3.10+-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![Tests](https://img.shields.io/badge/tests-pytest-0A2540)](tests/)
[![License](https://img.shields.io/badge/license-MIT-16A34A)](LICENSE)
[![Python CI](https://github.com/Alpha-Stochastic-Research/asr-var-cvar-tail-risk/actions/workflows/python-ci.yml/badge.svg)](https://github.com/Alpha-Stochastic-Research/asr-var-cvar-tail-risk/actions/workflows/python-ci.yml)

</div>

## Overview

This repository is the reproducible research package for the working paper:

> **Value at Risk versus Conditional Value at Risk: A Rigorous Framework for Measuring Extreme Tail Risk and Regulatory Compliance**

It studies VaR, CVaR, and Expected Shortfall through mathematical analysis, Monte Carlo simulation, robustness checks, backtesting, and regulatory interpretation.

## What is included

- empirical and closed-form VaR/CVaR implementations;
- the two-defaultable-bond counterexample to VaR subadditivity;
- Gaussian and standardized Student-t loss models;
- convergence and tail-thickness sensitivity studies;
- VaR exception and Kupiec backtesting utilities;
- a reproducible Jupyter notebook;
- generated CSV result tables and publication-ready figures;
- a LaTeX working paper;
- automated tests and GitHub Actions CI;
- citation, authorship, license, and reproducibility metadata.

## Repository structure

```text
asr-var-cvar-tail-risk/
├── .github/workflows/python-ci.yml
├── docs/METHODOLOGY.md
├── figures/
├── notebooks/var_cvar_reproduction.ipynb
├── paper/
│   ├── main.tex
│   ├── references.bib
│   └── README.md
├── results/
├── scripts/run_analysis.py
├── src/asr_tail_risk/
│   ├── __init__.py
│   ├── backtesting.py
│   ├── models.py
│   ├── plotting.py
│   ├── risk_measures.py
│   └── simulation.py
├── tests/
├── AUTHORS.md
├── CHANGELOG.md
├── CITATION.cff
├── LICENSE
├── Makefile
├── README.md
├── REPRODUCIBILITY.md
├── pyproject.toml
└── requirements.txt
```

## Installation

```bash
git clone https://github.com/Alpha-Stochastic-Research/asr-var-cvar-tail-risk.git
cd asr-var-cvar-tail-risk

python -m venv .venv
source .venv/bin/activate        # macOS/Linux
# .venv\Scripts\activate         # Windows

python -m pip install --upgrade pip
pip install -e ".[dev]"
```

## Reproduce everything

```bash
python scripts/run_analysis.py
pytest -q
```

Or:

```bash
make reproduce
```

The analysis writes tables to `results/` and figures to `figures/`.

## Baseline experiment

| Parameter | Value |
|---|---:|
| Portfolio notional | USD 10,000,000 |
| Daily volatility | 1.2% |
| Student-t degrees of freedom | 4 |
| Monte Carlo paths | 200,000 |
| Seed | 42 |
| Confidence levels | 95%, 97.5%, 99% |

The Student-t model is rescaled so that its unconditional volatility matches the Gaussian benchmark.

## Package usage

```python
from asr.risk.tail import (
    empirical_var,
    empirical_cvar,
    gaussian_var,
    gaussian_cvar,
    simulate_student_t_losses,
)

losses = simulate_student_t_losses(
    n_paths=200_000,
    notional=10_000_000,
    volatility=0.012,
    degrees_of_freedom=4,
    seed=42,
)

var_99 = empirical_var(losses, 0.99)
cvar_99 = empirical_cvar(losses, 0.99)
```

## Python Import Namespace

The package is distributed under the project name:

```text
asr-var-cvar-tail-risk
```

The recommended Python import namespace is:

```python
from asr.risk.tail import TailRiskConfig
```

The legacy namespace remains available for backward compatibility:

```python
from asr_tail_risk import TailRiskConfig
```

New applications, notebooks, and research scripts should use `asr.risk.tail`.



## Working paper

Compile from the repository root:

```bash
cd paper
pdflatex main.tex
bibtex main
pdflatex main.tex
pdflatex main.tex
```

## Citation

Citation metadata are provided in [`CITATION.cff`](CITATION.cff).

## License

MIT License. See [`LICENSE`](LICENSE).

## Contact

Alpha Stochastic Research  
https://asr-lab.online  
research@asr-lab.online
