Historical Simulation VaR and Expected Shortfall

A reproducible Python project for estimating Value at Risk (VaR) and Expected Shortfall (ES) from overlapping historical return scenarios.

Public-data design

The committed dataset and demo outputs are explicitly synthetic. They are deterministic, redistributable, and are not copied, calibrated, or derived from the S&P 500 or another proprietary market series.

Optional live market data can be retrieved at runtime with yfinance. Downloaded data and all live-data outputs go to Git-ignored folders. Users are responsible for the source provider's terms and any redistribution restrictions.

Repository structure

.
|-- code/
|   |-- fetch_live_data.py
|   |-- generate_synthetic_data.py
|   |-- historical_var.py
|   |-- historical_var_analysis.ipynb
|   `-- test_historical_var.py
|-- data/
|   |-- local/                         # ignored except .gitkeep
|   |-- synthetic_data_metadata.json
|   `-- synthetic_index_prices.csv
|-- outputs/
|   |-- live/                          # ignored except .gitkeep
|   `-- synthetic_demo/
|-- VALIDATION.md
`-- requirements.txt

Method

The analysis cleans the daily price series, keeps the latest 504 valid observations, calculates overlapping three-observation simple returns, and applies those returns to the current index level. Loss is the current value minus each scenario value. The default 95% VaR uses NumPy's conservative higher quantile, while ES is the mean loss across scenarios at or above VaR.

This is an educational implementation for one index unit. It is not a production risk engine or investment advice.

Run the public demo

python -m pip install -r requirements.txt
python code/generate_synthetic_data.py
python code/historical_var.py
python -m unittest discover -s code -p "test_*.py"

The first command after installation regenerates the committed synthetic data exactly. The analysis writes tables and three charts to outputs/synthetic_demo/.

Optional live-data run

python code/fetch_live_data.py --ticker "^GSPC" --period 5y
python code/historical_var.py \
  --data data/local/GSPC_prices.csv \
  --output outputs/live \
  --instrument "S&P 500"

The live folders are ignored by Git. Do not move downloaded data or derived live outputs into committed folders unless you have confirmed the right to redistribute them.

Scope and provenance

This repository is an independently rebuilt portfolio demonstration based on standard graduate-level market-risk concepts. It does not claim to be original market research, a production model, or an endorsed implementation by any data provider.