# logandeboo/pairs_trading architecture

> Architecture diagram of the GitHub repository logandeboo/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/logandeboo/pairs_trading
- Repository: https://github.com/logandeboo/pairs_trading

## Overview

This repository is a Python research and backtesting system for US equity pairs trading. Its main workflow loads price history, selects candidate pairs using return history and statistical filters, simulates spread-based positions, and calculates portfolio performance after transaction costs. The tree and sampled code also show universe and risk-factor support. The README is empty, and some implementation excerpts are partial, so the graph omits uncertain internal wiring and does not imply that the separate backtesting implementation is complete.

Main entry points: [`src/backtest/backtest.py`](https://github.com/logandeboo/pairs_trading/blob/main/src/backtest/backtest.py) (Backtest engine), [`src/pair_selection.py`](https://github.com/logandeboo/pairs_trading/blob/main/src/pair_selection.py) (Pair selection), [`src/strategy_pipeline.py`](https://github.com/logandeboo/pairs_trading/blob/main/src/strategy_pipeline.py) (Strategy pipeline), [`src/data_loader.py`](https://github.com/logandeboo/pairs_trading/blob/main/src/data_loader.py) (Data loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Market data"]
  node_price_data[("Price history")]
  node_risk_data[("Risk returns")]
  node_loader["Data loader<br/>[data_loader.py]"]
end

subgraph group_selection["Universe and selection"]
  node_universe["US universe<br/>[universe.py]"]
  node_stock["Stock model<br/>[stock.py]"]
  node_pair["Stock pair<br/>[pair.py]"]
  node_selection["Pair selection<br/>[pair_selection.py]"]
end

subgraph group_simulation["Trading simulation"]
  node_pipeline["Strategy pipeline"]
  node_stats["Statistical utilities"]
  node_backtest["Backtest engine<br/>[backtest.py]"]
  node_config["Backtest config<br/>[backtest_config.py]"]
  node_result["Backtest result<br/>[backtest_result.py]"]
end

subgraph group_analysis["Risk and performance"]
  node_risk_factor["Risk factor<br/>[risk_factor.py]"]
  node_risk_factors["Risk factor set<br/>[risk_factors.py]"]
  node_performance["Performance analysis<br/>[performance.py]"]
  node_visualization["Visualization<br/>[visualization.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"runs workflow"| node_pipeline
node_pipeline -->|"loads prices"| node_loader
node_loader -->|"reads prices"| node_price_data
node_pipeline -->|"selects pairs"| node_selection
node_selection -->|"tests statistics"| node_stats
node_selection -->|"creates pairs"| node_pair
node_universe -->|"loads stock prices"| node_loader
node_universe -->|"creates stocks"| node_stock
node_universe -->|"reads constituents data"| node_price_data
node_selection -->|"uses risk factors"| node_risk_factors
node_risk_factors -->|"creates factors"| node_risk_factor
node_risk_factor -->|"reads returns"| node_risk_data
node_pipeline -->|"simulates pairs"| node_backtest
node_backtest -->|"requests pairs"| node_selection
node_backtest -->|"calculates spreads"| node_stats
node_backtest -->|"filters price history"| node_loader
node_backtest -->|"uses settings"| node_config
node_performance -->|"requests returns"| node_backtest
node_performance -->|"builds metrics"| node_result
node_researcher -->|"requests analysis"| node_performance
node_researcher -->|"views results"| node_visualization

click node_pipeline "https://github.com/logandeboo/pairs_trading/blob/main/src/strategy_pipeline.py"
click node_price_data "https://github.com/logandeboo/pairs_trading/tree/main/data/adj_close_price_data"
click node_risk_data "https://github.com/logandeboo/pairs_trading/tree/main/data/risk_factor_returns"
click node_loader "https://github.com/logandeboo/pairs_trading/blob/main/src/data_loader.py"
click node_universe "https://github.com/logandeboo/pairs_trading/blob/main/src/universe/universe.py"
click node_stock "https://github.com/logandeboo/pairs_trading/blob/main/src/stock.py"
click node_pair "https://github.com/logandeboo/pairs_trading/blob/main/src/pair.py"
click node_selection "https://github.com/logandeboo/pairs_trading/blob/main/src/pair_selection.py"
click node_risk_factor "https://github.com/logandeboo/pairs_trading/blob/main/src/risk/risk_factor.py"
click node_risk_factors "https://github.com/logandeboo/pairs_trading/blob/main/src/risk/risk_factors.py"
click node_stats "https://github.com/logandeboo/pairs_trading/blob/main/src/statistical_utils.py"
click node_backtest "https://github.com/logandeboo/pairs_trading/blob/main/src/backtest/backtest.py"
click node_config "https://github.com/logandeboo/pairs_trading/blob/main/src/backtest/backtest_config.py"
click node_result "https://github.com/logandeboo/pairs_trading/blob/main/src/backtest/backtest_result.py"
click node_performance "https://github.com/logandeboo/pairs_trading/blob/main/src/performance.py"
click node_visualization "https://github.com/logandeboo/pairs_trading/blob/main/src/visualization.py"

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_price_data,node_risk_data,node_loader toneBlue
class node_universe,node_stock,node_pair,node_selection toneAmber
class node_pipeline,node_stats,node_backtest,node_config,node_result toneMint
class node_risk_factor,node_risk_factors,node_performance,node_visualization toneRose
class node_researcher toneIndigo
```

## Components

### Market data

- [Price history](https://github.com/logandeboo/pairs_trading/tree/main/data/adj_close_price_data): `data/adj_close_price_data`
- [Risk returns](https://github.com/logandeboo/pairs_trading/tree/main/data/risk_factor_returns): `data/risk_factor_returns`
- [Data loader](https://github.com/logandeboo/pairs_trading/blob/main/src/data_loader.py): `src/data_loader.py`

### Universe and selection

- [US universe](https://github.com/logandeboo/pairs_trading/blob/main/src/universe/universe.py): `src/universe/universe.py`
- [Stock model](https://github.com/logandeboo/pairs_trading/blob/main/src/stock.py): `src/stock.py`
- [Stock pair](https://github.com/logandeboo/pairs_trading/blob/main/src/pair.py): `src/pair.py`
- [Pair selection](https://github.com/logandeboo/pairs_trading/blob/main/src/pair_selection.py): `src/pair_selection.py`

### Trading simulation

- [Strategy pipeline](https://github.com/logandeboo/pairs_trading/blob/main/src/strategy_pipeline.py): `src/strategy_pipeline.py`
- [Statistical utilities](https://github.com/logandeboo/pairs_trading/blob/main/src/statistical_utils.py): `src/statistical_utils.py`
- [Backtest engine](https://github.com/logandeboo/pairs_trading/blob/main/src/backtest/backtest.py): `src/backtest/backtest.py`
- [Backtest config](https://github.com/logandeboo/pairs_trading/blob/main/src/backtest/backtest_config.py): `src/backtest/backtest_config.py`
- [Backtest result](https://github.com/logandeboo/pairs_trading/blob/main/src/backtest/backtest_result.py): `src/backtest/backtest_result.py`

### Risk and performance

- [Risk factor](https://github.com/logandeboo/pairs_trading/blob/main/src/risk/risk_factor.py): `src/risk/risk_factor.py`
- [Risk factor set](https://github.com/logandeboo/pairs_trading/blob/main/src/risk/risk_factors.py): `src/risk/risk_factors.py`
- [Performance analysis](https://github.com/logandeboo/pairs_trading/blob/main/src/performance.py): `src/performance.py`
- [Visualization](https://github.com/logandeboo/pairs_trading/blob/main/src/visualization.py): `src/visualization.py`

### Other components

- **Researcher**

## Connections

- Researcher → Strategy pipeline: runs workflow
- Strategy pipeline → Data loader: loads prices
- Data loader → Price history: reads prices
- Strategy pipeline → Pair selection: selects pairs
- Pair selection → Statistical utilities: tests statistics
- Pair selection → Stock pair: creates pairs
- US universe → Data loader: loads stock prices
- US universe → Stock model: creates stocks
- US universe → Price history: reads constituents data
- Pair selection → Risk factor set: uses risk factors
- Risk factor set → Risk factor: creates factors
- Risk factor → Risk returns: reads returns
- Strategy pipeline → Backtest engine: simulates pairs
- Backtest engine → Pair selection: requests pairs
- Backtest engine → Statistical utilities: calculates spreads
- Backtest engine → Data loader: filters price history
- Backtest engine → Backtest config: uses settings
- Performance analysis → Backtest engine: requests returns
- Performance analysis → Backtest result: builds metrics
- Researcher → Performance analysis: requests analysis
- Researcher → Visualization: views results