Quantitative Finance Lab

Project-based research & a reusable Python library for quantitative finance

A research lab of reproducible quant-finance projects (notes, math, experiments) backed by a growing Python package: quantfinlab.

Author

Ramtin Asadi

Note

This site is the published companion to the GitHub repository:
https://github.com/ramtin-asadi/Quantitative-Finance-Lab

Quantitative-Finance-Lab is a sequence of research projects in quantitative finance, each built end-to-end: financial motivation, mathematical derivation, real-data implementation, diagnostics, and honest interpretation. It is meant to be used as three things: A self-study curriculum that forces every model to be implemented and tested rather than just read about, a research notebook series, and a real software library (quantfinlab) that can be reusable for parts of the notebook that created it.

Clear narrative: intuition to math to implementation
Reproducible experiments: consistent metrics, plots, and comparisons
Library-first engineering: reusable components are extracted into quantfinlab

The goal is to build a series that is both research-grade (well explained) and engineering-grade (reusable, testable, maintainable).

Start here

Read the Overview for how projects are structured, what the notebook-to-library workflow means, and the evaluation conventions used throughout.
Read Data below before trying to run anything locally — the notebooks are not directly re-runnable on a fresh clone without first preparing data.
Then open a project notebook and read it top to bottom; the final section of most notebooks re-runs the same workflow on a second market using only quantfinlab.
The library itself is documented in quantfinlab/README.md on GitHub, with the full module map and code examples.

Projects

1. Fixed Income and Yield Curve Construction

Bootstrap US and Japan Treasury curves from par yields into discount, zero-rate, and forward-rate curves
Price fixed-coupon bonds and rolling synthetic bond issuance from curve inputs
Measure duration, convexity, PV01, and key-rate duration exposures
Build duration-targeted bond portfolios with reusable fixed-income utilities

Open Project 01

2. Portfolio Optimization with Mean-Variance Models

Select a liquid Nasdaq stock universe with realistic history and liquidity filters
Estimate expected returns with momentum, Bayes-Stein shrinkage, and Bayes-Stein momentum
Compare sample, Ledoit-Wolf, OAS, and EWMA covariance estimators inside constrained optimizers
Backtest min-variance, mean-variance, and max-Sharpe portfolios with turnover, drawdown, and risk diagnostics

Open Project 02

3. Risk Analysis and CAPM

Build a reusable risk report for assets, strategies, and portfolios
Compute performance, distribution shape, drawdowns, VaR, expected shortfall, and stress windows
Estimate CAPM alpha, beta, rolling exposure, and benchmark-relative behavior
Add risk contribution and diversification diagnostics reused across later projects

Open Project 03

4. Black-Scholes, Implied Volatility, Greeks and Hedging

Build option payoffs, risk-neutral pricing intuition, and the Black-Scholes-Merton model
Clean SPX option chains and invert implied volatility with robust solver diagnostics
Compute Greeks with analytic, autodiff, and finite-difference validation
Test delta and delta-vega hedging with P&L attribution, transaction costs, and a BTC options repeat

Open Project 04

5. Volatility Forecasting with GARCH and Variance Risk Premium

Forecast realized volatility with GARCH, GJR-GARCH, EGARCH, and HAR-RV models
Build a clean 30-day ATM implied-volatility panel from SPX option chains
Estimate the variance risk premium as an implied-versus-realized variance spread
Translate VRP signals into straddle overlays with performance, risk, and diagnostic checks

Open Project 05

6. Black-Litterman with Learned Confidence

Build ETF strategic benchmarks, covariance estimates, and market-implied priors
Encode active views and learn confidence from realized historical view payoff reliability
Convert Black-Litterman posterior returns into active weights with tracking-error controls
Evaluate active portfolios against benchmarks and repeat the workflow on sector ETFs through the library

Open Project 06

7. Dynamic Hedge Ratios and Residual Trading

Estimate static, rolling, ridge, and Kalman/state-space hedge ratios
Diagnose hedgeability across equity, commodity, currency, and ETF relationships
Measure hedged books with volatility, expected shortfall, drawdown, beta, turnover, and cost drag
Test residual spreads with ADF, Engle-Granger, half-life, z-score rules, no-trade bands, and robustness repeats

Open Project 07

8. Volatility Surface and Local Volatility

Construct a clean SPX option surface from forwards, rates, paired quotes, and bid-ask-aware IV
Fit raw PCHIP and smoother log-total-variance B-spline volatility surfaces
Derive Dupire local volatility with no-arbitrage, stress, and surface-quality diagnostics
Build historical surface features, PCA surface dynamics, surface-aware Greeks, and a BTC options repeat

Open Project 08

9. Term Structure Models, Curve Factors, and Swap-Based Duration Overlays

Reuse Treasury curve data to build monthly zero-rate panels, SOFR returns, and curve factors
Calibrate Vasicek, CIR, HW1F, and G2-style term-structure models with diagnostic checks
Decompose curve moves with PCA level, slope, and curvature factors plus term-premium proxies
Convert curve views into duration-ladder and fixed-for-floating swap overlay backtests

Open Project 09

10. Portfolio Optimization: Tail Risk, Risk Parity and Robust Models

Compare tail-risk, CVaR, risk-parity, HRP, robust, and Wasserstein-DRO portfolio objectives
Stress optimizer sensitivity to expected-return, covariance, and scenario assumptions
Study mean-variance, Black-Litterman, CVaR, ellipsoid-robust, and distributionally robust allocations
Evaluate drawdowns, costs, turnover, risk contributions, and secondary library replication

Open Project 10

11. Stochastic Volatility Models and Model-Risk-Aware Option Relative Value

Build a clean SPX option modeling panel from the earlier option-chain and IV stack
Fit SVI, SSVI, SABR, Merton, Heston, and Bates-style smile and stochastic-volatility models
Compare fit quality, residuals, weighted IV errors, runtime, parameter warnings, and model stability
Trade model-risk-aware option relative value with hedging attribution, controls, and secondary market repeats

Open Project 11

12. Macro Financial Conditions Index and Macro-Regime Allocation

Transform macro series into stress-oriented monthly features across inflation, policy, growth, labor, housing, trade, and breadth
Build economic-weighted, PCA, PLS, stress-probability, and blended financial-conditions indexes
Validate FCI signals against future equity stress, volatility, and drawdowns
Apply macro-regime signals to sector rotation and risk scaling with performance, drawdown, and library replication

Open Project 12

13. American Options and Numerical Pricing Methods

Price American options with Cox-Ross-Rubinstein trees, finite differences, PDE logic, and Longstaff-Schwartz Monte Carlo
Build a SPY American-option panel with dividends, rates, spreads, and early-exercise inputs
Study convergence, PSOR, exercise boundaries, assignment risk, and model disagreement
Compare Python, Numba, and C++ engines and repeat the workflow through reusable library tools

Open Project 13

14. Fourier-Based Methods for Option Pricing

Price options from characteristic functions instead of closed-form formulas, trees, or simulated paths
Implement direct Fourier integration, Carr-Madan FFT, and COS pricing methods
Compare BSM, Merton, Variance Gamma, Heston, and Bates pricing and calibration behavior
Diagnose SPX and BTC fit, convergence, runtime, jump risk, stochastic volatility, and reusable library implementation

Open Project 14

15. Factor Investing and Fama-French Allocation

Build Fama-French factor, sector ETF, industry portfolio, and broad ETF return panels
Estimate full-sample and rolling factor exposures for sectors and tradable ETFs
Convert factor states, residual alpha, and validation-weighted scores into allocation signals
Test factor-timing and sector-rotation portfolios with risk, turnover, drawdown, and library diagnostics

Open Project 15

16. Regime Switching Portfolio Selection

Build cross-asset, macro, FCI, breadth, volatility, drawdown, and correlation features
Define realized future regimes from forward risk-versus-defensive outcomes
Compare clustering, Markov-switching, hidden Markov, and supervised classification models
Convert regime probabilities into state-conditioned sleeves and repeat the workflow on sector ETFs

Open Project 16

17. Network-Aware Portfolio Construction

Turn a rolling NASDAQ stock universe into correlation and tail-dependence networks
Compare dense graphs with filtered MST and PMFG market structures
Measure centrality, clustering, graph roles, and dependence concentration
Use network scores as portfolio signals with diversification, turnover, and stress diagnostics

Open Project 17

18. Rough Volatility for Option Pricing

Estimate physical roughness from log realized variance and moment-scaling diagnostics
Compare rough-kernel variance forecasts with HAR and GARCH-style benchmarks
Study option-implied roughness through short-maturity skew power laws
Simulate and calibrate rBergomi and rough-Heston-style models for pricing, calibration, and hedge sensitivity

Open Project 18

19. Machine Learning and Neural Forecasting for Uncertainty-Aware Kelly Allocation

Build 21-day cross-asset forward alpha targets and date-asset feature panels
Train tabular, neural sequence, and probabilistic forecasting models
Evaluate rank IC, bucket spreads, pinball loss, coverage, calibration, and uncertainty diagnostics
Convert forecasts into fractional Kelly and forecast-gated MaxSharpe allocations with sector ETF transfer

Open Project 19

20. Reinforcement Learning for Portfolio Allocation

Build a weekly RL portfolio environment with costs, drawdown, volatility, prior weights, and market-state features
Define a continuous action-to-weight map that always produces valid long-only portfolio allocations
Train PPO, recurrent PPO, and SAC policies with a differential-Sharpe reward and risk penalties
Compare RL policies against forecast-gated, Kelly, and regime-aware baselines plus a sector ETF library transfer

Open Project 20

Data

The notebooks cannot be re-run directly on a fresh clone. Data has to be prepared first. No large or licensed market data is committed to the repository. Instead, the repository ships a data/ reproducibility layer: one small, readable script per data source, plus a README.md documenting exactly what each one does and where its data comes from.

Two kinds of sources are handled differently:

Scripted/automatic sources: FRED (US Treasury yields, NFCI), the NY Fed (ACM term premia), Japan’s Ministry of Finance (JGB yields), yfinance (equities, ETFs, BTC), the Kenneth French data library (factor returns) download themselves when you run the corresponding script, for example python data/us_treasury_yields/download.py.
Manual/licensed sources: OptionsDX option chains (SPX, SPY, QQQ, BTC/Deribit) and Stooq’s bulk equity archives require you to obtain the files yourself from the linked source (free registration in OptionsDX’s case) and place them in the matching data/<source>/raw/ folder; a build.py script then turns them into the clean file each notebook expects.

The complete list of sources, what to put where, and citation requirements per source live in data/README.md in the repository. Every number in every notebook has a scripted path back to where it came from.

The library

Reusable logic from every project lives in quantfinlab, a typed, tested Python package covering fixed income, options pricing (with a compiled C++ pricing core for the numerically heavy methods), portfolio construction, risk reporting, volatility modeling, hedging, macro indicators, and ML/RL Applications for finance. It ships with 171 tests covering everything from optimizer invariants to the C++ kernels, all passing in CI. Full documentation, the module map, and worked code examples are in quantfinlab/README.md on GitHub.

Disclaimer

This repository is for research and educational purposes. Nothing here is investment advice, and results may vary by dataset, assumptions, costs, constraints, and implementation details.

--- title: "Home" subtitle: "Project-based research & a reusable Python library for quantitative finance" description: "A research lab of reproducible quant-finance projects (notes, math, experiments) backed by a growing Python package: quantfinlab." toc: false page-layout: full --- :::{.callout-note} This site is the published companion to the GitHub repository: `https://github.com/ramtin-asadi/Quantitative-Finance-Lab` ::: **Quantitative-Finance-Lab** is a sequence of research projects in quantitative finance, each built end-to-end: financial motivation, mathematical derivation, real-data implementation, diagnostics, and honest interpretation. It is meant to be used as three things: A self-study curriculum that forces every model to be implemented and tested rather than just read about, a research notebook series, and a real software library (`quantfinlab`) that can be reusable for parts of the notebook that created it. - **Clear narrative**: intuition to math to implementation - **Reproducible experiments**: consistent metrics, plots, and comparisons - **Library-first engineering**: reusable components are extracted into **`quantfinlab`** The goal is to build a series that is both **research-grade** (well explained) and **engineering-grade** (reusable, testable, maintainable). --- ## Start here - Read the **[Overview](overview.qmd)** for how projects are structured, what the notebook-to-library workflow means, and the evaluation conventions used throughout. - Read **[Data](#data)** below before trying to run anything locally — the notebooks are not directly re-runnable on a fresh clone without first preparing data. - Then open a project notebook and read it top to bottom; the final section of most notebooks re-runs the same workflow on a second market using only `quantfinlab`. - The library itself is documented in [`quantfinlab/README.md`](https://github.com/ramtin-asadi/Quantitative-Finance-Lab/blob/main/quantfinlab/README.md) on GitHub, with the full module map and code examples. --- ## Projects :::: {.columns} ::: {.column width="50%"} ### 1. Fixed Income and Yield Curve Construction - Bootstrap US and Japan Treasury curves from par yields into discount, zero-rate, and forward-rate curves - Price fixed-coupon bonds and rolling synthetic bond issuance from curve inputs - Measure duration, convexity, PV01, and key-rate duration exposures - Build duration-targeted bond portfolios with reusable fixed-income utilities [Open Project 01](notebooks/01_yield_curve_bond_pricing_and_risk.html) ::: ::: {.column width="50%"} ### 2. Portfolio Optimization with Mean-Variance Models - Select a liquid Nasdaq stock universe with realistic history and liquidity filters - Estimate expected returns with momentum, Bayes-Stein shrinkage, and Bayes-Stein momentum - Compare sample, Ledoit-Wolf, OAS, and EWMA covariance estimators inside constrained optimizers - Backtest min-variance, mean-variance, and max-Sharpe portfolios with turnover, drawdown, and risk diagnostics [Open Project 02](notebooks/02_portfolio_optimization_MV_models.html) ::: :::: :::: {.columns} ::: {.column width="50%"} ### 3. Risk Analysis and CAPM - Build a reusable risk report for assets, strategies, and portfolios - Compute performance, distribution shape, drawdowns, VaR, expected shortfall, and stress windows - Estimate CAPM alpha, beta, rolling exposure, and benchmark-relative behavior - Add risk contribution and diversification diagnostics reused across later projects [Open Project 03](notebooks/03_risk_report_engine_and_CAPM.html) ::: ::: {.column width="50%"} ### 4. Black-Scholes, Implied Volatility, Greeks and Hedging - Build option payoffs, risk-neutral pricing intuition, and the Black-Scholes-Merton model - Clean SPX option chains and invert implied volatility with robust solver diagnostics - Compute Greeks with analytic, autodiff, and finite-difference validation - Test delta and delta-vega hedging with P&L attribution, transaction costs, and a BTC options repeat [Open Project 04](notebooks/04_BSM_IV_greeks_hedging.html) ::: :::: :::: {.columns} ::: {.column width="50%"} ### 5. Volatility Forecasting with GARCH and Variance Risk Premium - Forecast realized volatility with GARCH, GJR-GARCH, EGARCH, and HAR-RV models - Build a clean 30-day ATM implied-volatility panel from SPX option chains - Estimate the variance risk premium as an implied-versus-realized variance spread - Translate VRP signals into straddle overlays with performance, risk, and diagnostic checks [Open Project 05](notebooks/05_GARCH_forecasting_VRP.html) ::: ::: {.column width="50%"} ### 6. Black-Litterman with Learned Confidence - Build ETF strategic benchmarks, covariance estimates, and market-implied priors - Encode active views and learn confidence from realized historical view payoff reliability - Convert Black-Litterman posterior returns into active weights with tracking-error controls - Evaluate active portfolios against benchmarks and repeat the workflow on sector ETFs through the library [Open Project 06](notebooks/06_portfolio_black_littreman.html) ::: :::: :::: {.columns} ::: {.column width="50%"} ### 7. Dynamic Hedge Ratios and Residual Trading - Estimate static, rolling, ridge, and Kalman/state-space hedge ratios - Diagnose hedgeability across equity, commodity, currency, and ETF relationships - Measure hedged books with volatility, expected shortfall, drawdown, beta, turnover, and cost drag - Test residual spreads with ADF, Engle-Granger, half-life, z-score rules, no-trade bands, and robustness repeats [Open Project 07](notebooks/07_dynamic_hedge_ratios.html) ::: ::: {.column width="50%"} ### 8. Volatility Surface and Local Volatility - Construct a clean SPX option surface from forwards, rates, paired quotes, and bid-ask-aware IV - Fit raw PCHIP and smoother log-total-variance B-spline volatility surfaces - Derive Dupire local volatility with no-arbitrage, stress, and surface-quality diagnostics - Build historical surface features, PCA surface dynamics, surface-aware Greeks, and a BTC options repeat [Open Project 08](notebooks/08_vol_surface_local_vol.html) ::: :::: :::: {.columns} ::: {.column width="50%"} ### 9. Term Structure Models, Curve Factors, and Swap-Based Duration Overlays - Reuse Treasury curve data to build monthly zero-rate panels, SOFR returns, and curve factors - Calibrate Vasicek, CIR, HW1F, and G2-style term-structure models with diagnostic checks - Decompose curve moves with PCA level, slope, and curvature factors plus term-premium proxies - Convert curve views into duration-ladder and fixed-for-floating swap overlay backtests [Open Project 09](notebooks/09_term_structure_models.html) ::: ::: {.column width="50%"} ### 10. Portfolio Optimization: Tail Risk, Risk Parity and Robust Models - Compare tail-risk, CVaR, risk-parity, HRP, robust, and Wasserstein-DRO portfolio objectives - Stress optimizer sensitivity to expected-return, covariance, and scenario assumptions - Study mean-variance, Black-Litterman, CVaR, ellipsoid-robust, and distributionally robust allocations - Evaluate drawdowns, costs, turnover, risk contributions, and secondary library replication [Open Project 10](notebooks/10_portfolio_tail_parity_robust.html) ::: :::: :::: {.columns} ::: {.column width="50%"} ### 11. Stochastic Volatility Models and Model-Risk-Aware Option Relative Value - Build a clean SPX option modeling panel from the earlier option-chain and IV stack - Fit SVI, SSVI, SABR, Merton, Heston, and Bates-style smile and stochastic-volatility models - Compare fit quality, residuals, weighted IV errors, runtime, parameter warnings, and model stability - Trade model-risk-aware option relative value with hedging attribution, controls, and secondary market repeats [Open Project 11](notebooks/11_stochastic_volatility.html) ::: ::: {.column width="50%"} ### 12. Macro Financial Conditions Index and Macro-Regime Allocation - Transform macro series into stress-oriented monthly features across inflation, policy, growth, labor, housing, trade, and breadth - Build economic-weighted, PCA, PLS, stress-probability, and blended financial-conditions indexes - Validate FCI signals against future equity stress, volatility, and drawdowns - Apply macro-regime signals to sector rotation and risk scaling with performance, drawdown, and library replication [Open Project 12](notebooks/12_financial_conditions_index.html) ::: :::: :::: {.columns} ::: {.column width="50%"} ### 13. American Options and Numerical Pricing Methods - Price American options with Cox-Ross-Rubinstein trees, finite differences, PDE logic, and Longstaff-Schwartz Monte Carlo - Build a SPY American-option panel with dividends, rates, spreads, and early-exercise inputs - Study convergence, PSOR, exercise boundaries, assignment risk, and model disagreement - Compare Python, Numba, and C++ engines and repeat the workflow through reusable library tools [Open Project 13](notebooks/13_american_option_numerics.html) ::: ::: {.column width="50%"} ### 14. Fourier-Based Methods for Option Pricing - Price options from characteristic functions instead of closed-form formulas, trees, or simulated paths - Implement direct Fourier integration, Carr-Madan FFT, and COS pricing methods - Compare BSM, Merton, Variance Gamma, Heston, and Bates pricing and calibration behavior - Diagnose SPX and BTC fit, convergence, runtime, jump risk, stochastic volatility, and reusable library implementation [Open Project 14](notebooks/14_fourier_option_pricing.html) ::: :::: :::: {.columns} ::: {.column width="50%"} ### 15. Factor Investing and Fama-French Allocation - Build Fama-French factor, sector ETF, industry portfolio, and broad ETF return panels - Estimate full-sample and rolling factor exposures for sectors and tradable ETFs - Convert factor states, residual alpha, and validation-weighted scores into allocation signals - Test factor-timing and sector-rotation portfolios with risk, turnover, drawdown, and library diagnostics [Open Project 15](notebooks/15_factor_investing.html) ::: ::: {.column width="50%"} ### 16. Regime Switching Portfolio Selection - Build cross-asset, macro, FCI, breadth, volatility, drawdown, and correlation features - Define realized future regimes from forward risk-versus-defensive outcomes - Compare clustering, Markov-switching, hidden Markov, and supervised classification models - Convert regime probabilities into state-conditioned sleeves and repeat the workflow on sector ETFs [Open Project 16](notebooks/16_regime_switching_portfolio.html) ::: :::: :::: {.columns} ::: {.column width="50%"} ### 17. Network-Aware Portfolio Construction - Turn a rolling NASDAQ stock universe into correlation and tail-dependence networks - Compare dense graphs with filtered MST and PMFG market structures - Measure centrality, clustering, graph roles, and dependence concentration - Use network scores as portfolio signals with diversification, turnover, and stress diagnostics [Open Project 17](notebooks/17_network_portfolio.html) ::: ::: {.column width="50%"} ### 18. Rough Volatility for Option Pricing - Estimate physical roughness from log realized variance and moment-scaling diagnostics - Compare rough-kernel variance forecasts with HAR and GARCH-style benchmarks - Study option-implied roughness through short-maturity skew power laws - Simulate and calibrate rBergomi and rough-Heston-style models for pricing, calibration, and hedge sensitivity [Open Project 18](notebooks/18_rough_volatility.html) ::: :::: :::: {.columns} ::: {.column width="50%"} ### 19. Machine Learning and Neural Forecasting for Uncertainty-Aware Kelly Allocation - Build 21-day cross-asset forward alpha targets and date-asset feature panels - Train tabular, neural sequence, and probabilistic forecasting models - Evaluate rank IC, bucket spreads, pinball loss, coverage, calibration, and uncertainty diagnostics - Convert forecasts into fractional Kelly and forecast-gated MaxSharpe allocations with sector ETF transfer [Open Project 19](notebooks/19_forecasting_kelly_allocation.html) ::: ::: {.column width="50%"} ### 20. Reinforcement Learning for Portfolio Allocation - Build a weekly RL portfolio environment with costs, drawdown, volatility, prior weights, and market-state features - Define a continuous action-to-weight map that always produces valid long-only portfolio allocations - Train PPO, recurrent PPO, and SAC policies with a differential-Sharpe reward and risk penalties - Compare RL policies against forecast-gated, Kelly, and regime-aware baselines plus a sector ETF library transfer [Open Project 20](notebooks/20_rl_portfolio_allocation.html) ::: :::: --- ## Data {#data} **The notebooks cannot be re-run directly on a fresh clone. Data has to be prepared first.** No large or licensed market data is committed to the repository. Instead, the repository ships a `data/` reproducibility layer: one small, readable script per data source, plus a `README.md` documenting exactly what each one does and where its data comes from. Two kinds of sources are handled differently: - **Scripted/automatic sources**: FRED (US Treasury yields, NFCI), the NY Fed (ACM term premia), Japan's Ministry of Finance (JGB yields), yfinance (equities, ETFs, BTC), the Kenneth French data library (factor returns) download themselves when you run the corresponding script, for example `python data/us_treasury_yields/download.py`. - **Manual/licensed sources**: OptionsDX option chains (SPX, SPY, QQQ, BTC/Deribit) and Stooq's bulk equity archives require you to obtain the files yourself from the linked source (free registration in OptionsDX's case) and place them in the matching `data/<source>/raw/` folder; a `build.py` script then turns them into the clean file each notebook expects. The complete list of sources, what to put where, and citation requirements per source live in `data/README.md` in the repository. Every number in every notebook has a scripted path back to where it came from. ## The library Reusable logic from every project lives in **`quantfinlab`**, a typed, tested Python package covering fixed income, options pricing (with a compiled C++ pricing core for the numerically heavy methods), portfolio construction, risk reporting, volatility modeling, hedging, macro indicators, and ML/RL Applications for finance. It ships with 171 tests covering everything from optimizer invariants to the C++ kernels, all passing in CI. Full documentation, the module map, and worked code examples are in [`quantfinlab/README.md`](https://github.com/ramtin-asadi/Quantitative-Finance-Lab/blob/main/quantfinlab/README.md) on GitHub. --- ## Disclaimer This repository is for **research and educational purposes**. Nothing here is investment advice, and results may vary by dataset, assumptions, costs, constraints, and implementation details.