Quant Research Lab is a local Python research framework for institutional-style portfolio analytics, statistical arbitrage, macro regime research, options volatility analysis, and transaction-cost-aware backtesting.
This is structured as a package-style repository rather than a notebook dump. The modules are reusable from scripts, tests, notebooks, VS Code, PyCharm, or an installed Python environment.
Professional quant research is judged on reproducibility, risk controls, clean data handling, and the ability to convert research into repeatable workflows. This repository combines five systems that are common in asset management, banking, prop trading, and portfolio analytics:
- Multi-asset portfolio risk dashboard
- Pairs trading statistical arbitrage model
- Macro regime detection model
- Implied volatility surface builder
- Institutional backtesting engine with transaction costs
The implementation emphasizes modular architecture, local execution, graceful data-provider failure handling, saved artifacts, and testable analytics code.
Quant-Research-Lab/
configs/ YAML parameters for assets, macro data, options, and backtests
scripts/ Command-line entry points for each research system
notebooks/ Optional research demonstration notebooks
src/quant_research_lab/ Reusable Python package
tests/ Pytest regression tests
data/ Raw, processed, and cached local data
outputs/ Saved figures, reports, and backtest results
docs/ Methodology, assumptions, limitations, and API reference
cd Quant-Research-Lab
python -m venv .venvActivate the environment with the command for your operating system:
# macOS / Linux
source .venv/bin/activate
# Windows PowerShell
.venv\Scripts\Activate.ps1The package requires Python 3.11 or newer, and the CI workflow verifies Python 3.11 and 3.12.
Install the runtime dependencies:
pip install -r requirements.txtFor editable package development:
pip install -e .Development tooling:
pip install -r requirements-dev.txt
pre-commit install
ruff check src tests scripts
black --check src tests scripts
mypy src --ignore-missing-importsCopy .env.example to .env if you have optional API keys:
# macOS / Linux
cp .env.example .env
# Windows PowerShell
Copy-Item .env.example .envFRED can be accessed through a public CSV endpoint without a key, but FRED_API_KEY is supported. Yahoo Finance access is handled through yfinance. If a provider fails or no key is present, the scripts use deterministic sample data and log the fallback.
python scripts/run_risk_dashboard.py
python scripts/run_pairs_trading.py
python scripts/run_macro_regime_model.py
python scripts/run_vol_surface.py
python scripts/run_backtest.py
pytestAfter pip install -e ., the same workflows are available as console commands:
qrl-risk
qrl-pairs
qrl-macro
qrl-vol
qrl-backtestOutputs are written to:
outputs/figures/
outputs/reports/
outputs/backtests/
Downloads prices, calculates simple and log returns, creates a weighted multi-asset portfolio, compares it against a benchmark, and saves figures and CSV summaries. Metrics include annualized return, volatility, Sharpe, Sortino, max drawdown, Calmar, beta, alpha, rolling volatility, rolling beta, rolling correlation, and rolling Sharpe.
Tests all possible stock pairs for cointegration, ranks pairs by p-value, estimates hedge ratios with OLS, builds spreads, generates z-score entry and exit signals, deducts transaction costs, and saves strategy diagnostics.
Pulls FRED macro data, builds monthly macro features, standardizes them, applies PCA, clusters regimes, labels regimes with economic descriptions, and compares asset returns by regime.
Loads options chains from yfinance or manual CSV, cleans quotes, computes Black-Scholes implied volatility, calculates Greeks, creates smiles, term structure, and a 3D interpolated volatility surface.
Tracks cash, holdings, target weights, transaction costs, slippage, turnover, exposure, drawdowns, and benchmark-relative performance. Includes buy-and-hold, momentum rotation, and pairs trading examples. Signals are shifted before execution to avoid same-close lookahead bias.
The repository includes GitHub Actions CI, ruff, black, mypy, pre-commit, a Dockerfile, a VS Code dev container, package console commands, MkDocs documentation, and tracked example images for README/docs presentation.
The professionalization pass adds:
- Ledoit-Wolf covariance shrinkage and exponentially weighted covariance
- Minimum-variance, mean-variance, and risk-parity portfolio optimization
- Linear factor risk model estimation
- EWMA volatility and correlation
- Historical VaR/CVaR tail-risk reports
- Deterministic stress testing
- Monte Carlo portfolio path simulation
- Regime-aware allocation helpers
- Order/fill objects, rebalance calendars, position constraints, walk-forward splits, parameter sweeps, borrow costs, and cash financing hooks for backtesting
- Yahoo Finance through
yfinance - FRED through
fredapior direct public CSV requests - Manual options-chain CSV uploads
- Optional future support for Polygon and Alpha Vantage keys
- Deterministic local fallback data for reproducible offline runs
Portfolio analytics use geometric compounding, annualized volatility, drawdown from high-water marks, downside volatility, and benchmark covariance estimates. Pairs trading uses Engle-Granger cointegration, OLS hedge ratios, rolling z-scores, and cost-adjusted close-to-close backtests. Macro regimes use engineered FRED features, PCA, and KMeans clustering. Options analytics use Black-Scholes pricing, numerical implied-volatility solving, Greeks, and surface interpolation. Backtests explicitly track costs, slippage, turnover, exposure, and benchmark alpha/beta.
- Portfolio equity curve and drawdown chart
- Correlation heatmap and allocation chart
- Cointegrated pair ranking table
- Pair spread, z-score, trade marker, and equity charts
- Macro regime timeline and PCA scatter
- Regime transition matrix and returns by regime
- IV smile, term structure, 3D surface, Greeks chart
- Strategy comparison table and monthly returns heatmap
Selected tracked examples are available in docs/assets/ and on the MkDocs site:
Free market data can contain survivorship bias, stale quotes, adjusted-price quirks, missing delistings, and delayed data. Transaction costs are simplified bps assumptions, not broker-specific fills. Options surfaces depend heavily on quote quality. Macro regimes are descriptive research tools, not causal forecasts. See docs/limitations.md and docs/assumptions.md.
- Add broker-grade corporate action handling
- Add event-driven intraday backtesting
- Add richer options no-arbitrage checks
- Add Polygon/Alpha Vantage adapters
- Add live data adapters behind a strict research/production boundary
This repository is research software for education and portfolio analytics demonstration. It is not investment advice, a trading recommendation, or a production trading system.