HedgerSys – Geopolitical Black Swan Hedging Recommender

A research-grade prototype of a geopolitical Black Swan hedging recommender system using a retrieval–ranking–output pipeline. The system recommends top-K hedges (with suggested allocation sizes) for a given portfolio under a geopolitical risk regime.

Project Structure

Thesis-main/
├── hedgersys/              # Core library (pipeline, models, evaluation)
│   ├── data/               #   Data loaders & metadata
│   ├── evaluation/         #   Backtest, episodes, crisis typing, metrics
│   ├── costs/              #   Transaction cost model
│   ├── ranking/            #   Candidate scoring & ranking
│   ├── retrieval/          #   Candidate retrieval & filtering
│   ├── sizing/             #   Position sizing (inverse-vol, marginal CVaR)
│   ├── explain/            #   Explanation generation
│   ├── portfolio/          #   Portfolio construction
│   └── utils/              #   Shared utilities
├── improved/               # Improved pipeline (7 enhancements)
│   ├── backtest.py         #   Improved backtest runner
│   ├── conviction.py       #   Conviction gating
│   ├── marginal_sizing.py  #   Marginal CVaR sizing
│   ├── soft_regime.py      #   Soft regime probabilities
│   ├── soft_crisis.py      #   Multi-label crisis typing
│   ├── robust_effectiveness.py
│   ├── uncertainty.py      #   Sample-size uncertainty penalisation
│   └── role_diversification.py
├── scripts/                # Runnable scripts (analysis, generation, etc.)
│   ├── generation/         #   generate_final_results.py, figures, tables, thesis plots
│   ├── discovery/          #   Crisis type discovery (Bayesian GMM exploration)
│   ├── analysis/           #   Ad-hoc analyses (2022, correlation breakdown, PCA verification)
│   ├── sensitivity/        #   Hedge budget sensitivity, static allocators
│   └── data_prep/          #   Data download / caching
├── tests/                  # Unit & integration tests
├── docs/                   # Documentation
│   ├── METHODOLOGY_DEEP_DIVE.md
│   ├── REPORT_Methodology_and_Results.md
│   └── thesis_additions_guide.txt
├── data/                   # Input data (GPR index, price cache)
├── results/                # Intermediate results & discovery plots
├── final_results/          # Authoritative pipeline output (V2.2)
├── sensitivity_results/    # Sensitivity analysis output
├── plots_for_thesis/       # Publication-ready thesis figures (76 PNGs)
├── run_config.yaml         # Main configuration file
└── README.md               # This file

Quick Start

# Install dependencies
pip install pandas numpy scipy scikit-learn statsmodels matplotlib pyyaml yfinance

# Run the full pipeline (generates final_results/)
python scripts/generation/generate_final_results.py

# Run tests
pytest tests/ -v

Key Commands

# Full results generation (backtest + plots + report)
python scripts/generation/generate_final_results.py

# Crisis type discovery analysis
python scripts/discovery/discover_crisis_types.py

# Discovery figures for thesis
python scripts/generation/generate_discovery_figures.py

# Hedge budget sensitivity analysis
python scripts/sensitivity/sensitivity_hedge_budget.py

# CLI single-point recommendation
python -m hedgersys run run_config.yaml

Documentation

Document	Description
METHODOLOGY_DEEP_DIVE.md	Full pipeline methodology (accessible)
REPORT_Methodology_and_Results.md	Formal methodology & results report
FINAL_REPORT.md	Latest results report (V2.2)
thesis_additions_guide.txt	Thesis integration guide

V2.2 Methodology & Pipeline

Four key improvements to the crisis typing and evaluation pipeline:

1. Rank-Normal Transform (V2.1) — maps features to normal quantiles before PCA, eliminating fat tails (92% of features were non-normal)
2. Bayesian Gaussian Mixture (V2.1) — replaces frequentist GMM + BIC with Dirichlet process prior for automatic cluster count selection (produces 9 effective clusters, silhouette = 0.344)
3. Expanding-Window Refit (V2.1) — crisis typing refit every 3 years using only past episodes, eliminating look-ahead bias
4. Severity-Preserving Features (V2.2) — 25 additional features capturing tail magnitude (threshold exceedances, aggregate extremity), growing feature space from 65 to 90, restoring extreme episode cluster purity from 0.13 to 0.75

Current state: 53 instruments, 112 episodes (34 minor / 51 major / 25 severe / 2 systemic), 81/81 tests passing.

References

• Caldara, D. & Iacoviello, M. (2022). "Measuring Geopolitical Risk." American Economic Review, 112(4), 1194–1225.