# rsingh1010/mean-reversion-pairs-trading architecture

> Architecture diagram of the GitHub repository rsingh1010/mean-reversion-pairs-trading, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rsingh1010/mean-reversion-pairs-trading
- Repository: https://github.com/rsingh1010/mean-reversion-pairs-trading

## Overview

This repository is a Jupyter-based quantitative research project evaluating a cointegration mean-reversion strategy against an independent SPY benchmark. The documented workflow separates training and test periods, screens economically selected pairs, tests cointegration with multiple-testing correction, builds and evaluates a strategy, and reports diagnostics. The only source path in the tree is the notebook; its contents were not sampled, so components use that path and links follow the README’s stated methodology rather than verified notebook calls.

Main entry points: [`notebooks/mean_reversion_trading_system.ipynb`](https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb) (Reported Results)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_research["Pair Research"]
  node_notebook["Research Notebook"]
  node_market_data["Price Data"]
  node_split["Train/Test Split"]
  node_pair_selection["Candidate Selection"]
  node_correlation["Correlation Filter"]
  node_cointegration["Cointegration Test"]
  node_fdr["FDR Correction"]
end

subgraph group_strategy["Strategy Evaluation"]
  node_hedge_spread["Hedge and Spread"]
  node_signals["Trading Signals"]
  node_backtest["Costed Backtest"]
  node_oos_evaluation["Out-of-Sample Evaluation"]
  node_spy_benchmark["SPY Benchmark"]
end

subgraph group_findings["Results and Diagnostics"]
  node_results["Reported Results"]
  node_cost_sensitivity["Cost Sensitivity"]
  node_fdr_fragility["FDR Fragility"]
  node_yearly_stability["Yearly Stability"]
end

node_researcher(("Researcher"))
node_yfinance["yfinance"]

node_researcher -->|"runs"| node_notebook
node_notebook -->|"requests prices"| node_yfinance
node_yfinance -->|"provides prices"| node_market_data
node_market_data -->|"separates periods"| node_split
node_split -->|"supplies training data"| node_pair_selection
node_pair_selection -->|"screens pairs"| node_correlation
node_correlation -->|"filters candidates"| node_cointegration
node_cointegration -->|"supplies p-values"| node_fdr
node_fdr -->|"selects pair"| node_hedge_spread
node_hedge_spread -->|"defines spread"| node_signals
node_signals -->|"generates trades"| node_backtest
node_backtest -->|"evaluates test window"| node_oos_evaluation
node_split -->|"supplies test window"| node_spy_benchmark
node_oos_evaluation -->|"reports metrics"| node_results
node_spy_benchmark -->|"reports comparison"| node_results
node_backtest -->|"varies costs"| node_cost_sensitivity
node_fdr -->|"assesses test count"| node_fdr_fragility
node_oos_evaluation -->|"compares yearly returns"| node_yearly_stability
node_cost_sensitivity -->|"informs findings"| node_results
node_fdr_fragility -->|"informs findings"| node_results
node_yearly_stability -->|"informs findings"| node_results

click node_notebook "https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb"
click node_market_data "https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb"
click node_split "https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb"
click node_pair_selection "https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb"
click node_correlation "https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb"
click node_cointegration "https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb"
click node_fdr "https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb"
click node_hedge_spread "https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb"
click node_signals "https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb"
click node_backtest "https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb"
click node_oos_evaluation "https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb"
click node_spy_benchmark "https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb"
click node_results "https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb"
click node_cost_sensitivity "https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb"
click node_fdr_fragility "https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb"
click node_yearly_stability "https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_notebook,node_market_data,node_split,node_pair_selection,node_correlation,node_cointegration,node_fdr toneBlue
class node_hedge_spread,node_signals,node_backtest,node_oos_evaluation,node_spy_benchmark toneAmber
class node_results,node_cost_sensitivity,node_fdr_fragility,node_yearly_stability toneMint
class node_researcher,node_yfinance toneIndigo
```

## Components

### Pair Research

- [Research Notebook](https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb): `notebooks/mean_reversion_trading_system.ipynb`
- [Price Data](https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb): `notebooks/mean_reversion_trading_system.ipynb`
- [Train/Test Split](https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb): `notebooks/mean_reversion_trading_system.ipynb`
- [Candidate Selection](https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb): `notebooks/mean_reversion_trading_system.ipynb`
- [Correlation Filter](https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb): `notebooks/mean_reversion_trading_system.ipynb`
- [Cointegration Test](https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb): `notebooks/mean_reversion_trading_system.ipynb`
- [FDR Correction](https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb): `notebooks/mean_reversion_trading_system.ipynb`

### Strategy Evaluation

- [Hedge and Spread](https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb): `notebooks/mean_reversion_trading_system.ipynb`
- [Trading Signals](https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb): `notebooks/mean_reversion_trading_system.ipynb`
- [Costed Backtest](https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb): `notebooks/mean_reversion_trading_system.ipynb`
- [Out-of-Sample Evaluation](https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb): `notebooks/mean_reversion_trading_system.ipynb`
- [SPY Benchmark](https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb): `notebooks/mean_reversion_trading_system.ipynb`

### Results and Diagnostics

- [Reported Results](https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb): `notebooks/mean_reversion_trading_system.ipynb`
- [Cost Sensitivity](https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb): `notebooks/mean_reversion_trading_system.ipynb`
- [FDR Fragility](https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb): `notebooks/mean_reversion_trading_system.ipynb`
- [Yearly Stability](https://github.com/rsingh1010/mean-reversion-pairs-trading/blob/main/notebooks/mean_reversion_trading_system.ipynb): `notebooks/mean_reversion_trading_system.ipynb`

### Other components

- **Researcher**
- **yfinance**

## Connections

- Researcher → Research Notebook: runs
- Research Notebook → yfinance: requests prices
- yfinance → Price Data: provides prices
- Price Data → Train/Test Split: separates periods
- Train/Test Split → Candidate Selection: supplies training data
- Candidate Selection → Correlation Filter: screens pairs
- Correlation Filter → Cointegration Test: filters candidates
- Cointegration Test → FDR Correction: supplies p-values
- FDR Correction → Hedge and Spread: selects pair
- Hedge and Spread → Trading Signals: defines spread
- Trading Signals → Costed Backtest: generates trades
- Costed Backtest → Out-of-Sample Evaluation: evaluates test window
- Train/Test Split → SPY Benchmark: supplies test window
- Out-of-Sample Evaluation → Reported Results: reports metrics
- SPY Benchmark → Reported Results: reports comparison
- Costed Backtest → Cost Sensitivity: varies costs
- FDR Correction → FDR Fragility: assesses test count
- Out-of-Sample Evaluation → Yearly Stability: compares yearly returns
- Cost Sensitivity → Reported Results: informs findings
- FDR Fragility → Reported Results: informs findings
- Yearly Stability → Reported Results: informs findings