# melaz2888/stat_arb_pair_kalman architecture

> Architecture diagram of the GitHub repository melaz2888/stat_arb_pair_kalman, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/melaz2888/stat_arb_pair_kalman
- Repository: https://github.com/melaz2888/stat_arb_pair_kalman

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    Notebook["Jupyter Notebook\n(notebook_corr.ipynb)"]:::orchestration
    YF["Yahoo Finance API"]:::external
    Ingest["Data-Ingestion\n(fetch_prices)"]:::processing
    Stats["Statistical Analysis\n(compute_adf,\ncompute_ols_beta)"]:::processing
    Model["Modeling\n(compute_kalman_beta)"]:::processing
    Backtest["Back-Testing\n(backtest_static,\nbacktest_kalman)"]:::processing
    Visual["Visualization\n(matplotlib,\nseaborn)"]:::processing
    Env["Local Environment & Dependencies\n(requirements.txt)"]:::environment
    Readme["Project Documentation\n(README.md)"]:::environment

    Notebook -->|"orchestrates"| Ingest
    YF -->|"price DataFrame"| Ingest
    Ingest -->|"price DataFrame"| Stats
    Stats -->|"static β estimates"| Backtest
    Stats -->|"β estimates"| Model
    Model -->|"dynamic β estimates"| Backtest
    Backtest -->|"P&L series"| Visual
    Visual -->|"renders charts & tables"| Notebook
    Env --> Notebook
    Readme --> Notebook

    click Ingest "https://github.com/melaz2888/stat_arb_pair_kalman/blob/main/trading_utils_corr.py"
    click Stats "https://github.com/melaz2888/stat_arb_pair_kalman/blob/main/trading_utils_corr.py"
    click Model "https://github.com/melaz2888/stat_arb_pair_kalman/blob/main/trading_utils_corr.py"
    click Backtest "https://github.com/melaz2888/stat_arb_pair_kalman/blob/main/trading_utils_corr.py"
    click Visual "https://github.com/melaz2888/stat_arb_pair_kalman/blob/main/notebook_corr.ipynb"
    click Notebook "https://github.com/melaz2888/stat_arb_pair_kalman/blob/main/notebook_corr.ipynb"
    click Env "https://github.com/melaz2888/stat_arb_pair_kalman/blob/main/requirements.txt"
    click Readme "https://github.com/melaz2888/stat_arb_pair_kalman/blob/main/README.md"

    classDef external fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef processing fill:#90EE90,stroke:#333,stroke-width:1px
    classDef orchestration fill:#FFA500,stroke:#333,stroke-width:1px
    classDef environment fill:#D3D3D3,stroke:#333,stroke-width:1px
```
