How melaz2888/stat_arb_pair_kalman works
Project Type & Purpose
• This is a data-science sandbox for pairs-trading research.
File Structure
• Top-level modules:
• trading_utils_corr.py – reusable library of helper functions (data fetch, ADF test, OLS β, Kalman β, back-test routines)
• notebook_corr.ipynb – orchestrates the research pipeline and renders charts/tables inline
• requirements.txt – external dependencies (yfinance, pandas, numpy, statsmodels, matplotlib, seaborn, tqdm)
• No separate “frontend” or “backend”—everything runs in a single Python process, orchestrated by Jupyter.
Extract Architecture Insights from README
• Data source: Yahoo Finance API (via yfinance)
• Processing pipeline: correlation scan → ADF cointegration check → static hedge (OLS) vs. dynamic hedge (Kalman filter)
• Visual output: charts of hedge ratios and equity curves in the notebook
Main Components & Their Responsibilities
a. Data Source
• External Service: Yahoo Finance
• Input: ticker symbols, date ranges
b. Data‐Ingestion Module
• fetch_prices() in trading_utils_corr.py
• Output: raw DataFrame of price series
c. Statistical Analysis Module
• compute_adf() for stationarity
• compute_ols_beta() for static hedge ratio
d. Modeling Module
• compute_kalman_beta() for dynamic hedge ratio
e. Back-Testing Module
• backtest_static() and backtest_kalman()
• Generates P&L timeseries
f. Visualization Module
• Matplotlib/Seaborn plotting functions called in the notebook
• Renders time-series charts and summary statistics
g. Orchestration Layer
• notebook_corr.ipynb
• Calls each utility in sequence, displays outputs
h. Local Environment
• requirements.txt → Python virtual environment (.venv)
• Ensures reproducible dependency management
Relationships & Data Flow
1. User opens notebook_corr.ipynb in Jupyter.
2. Notebook imports functions from trading_utils_corr.py.
3. Notebook calls fetch_prices() → raw data.
4. Data passed to ADF test → filter cointegrated pairs.
5. Filtered data flows to OLS and Kalman β functions.
6. Hedge ratios feed into back-test routines → P&L output.
7. Notebook visualizes all intermediate and final results.
Architectural Patterns & Principles
• Pipeline pattern: each processing stage feeds the next.
• Modular design: reusable functions in a single library.
• Orchestration via notebook: linear, literate-programming style.
• Separation of concerns: data fetch vs. stats vs. modeling vs. visualization.
Detail Without Overthinking
• Every distinct processing stage—don’t lump “stats” and “modeling” together if they’re separate functions.
• Both static and dynamic hedge‐ratio branches converging in the back-test stage.
• Local virtual environment and requirements to highlight reproducibility.