# chrisconlan/algorithmic-trading-with-python architecture

> Architecture diagram of the GitHub repository chrisconlan/algorithmic-trading-with-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chrisconlan/algorithmic-trading-with-python
- Repository: https://github.com/chrisconlan/algorithmic-trading-with-python

## Overview

This project is a companion code repository for "Algorithmic Trading with Python" by Chris Conlan. Its purpose is to illustrate various techniques and methodologies for algorithmic trading, including performance metrics, technical indicators, labeling, portfolio simulation, optimization, and even some machine learning components tailored to trading. The repository is structured to provide both a reusable codebase (in the src folder) and numerous example scripts (in the listings folder) that walk through the concepts described in the book.

##### Main Components
- Data Layer:
- The “data” directory holds the input files. It includes EOD (end-of-day) data, alternative data streams, and CSV files (like SPY.csv) that act as the historical market data used throughout the code.
- Example Scripts:
- The “listings” directory is organized by chapters, each demonstrating specific analytical or simulation techniques (e.g., computing moving averages, simulating portfolio behavior, grid search optimizations, etc.). These are there to exemplify how to use the library for various trading tasks.
- Core Python Library (“src”):
- The main source code is in the “src” folder. It includes bootstrapping scripts (like bootstrap_portfolio.py) and key analytical modules.
▪ Data Input/Output (data_io.py)
▪ Technical Analysis (indicators.py, signals.py)
▪ Portfolio Management (portfolio.py, simulation.py, weights.py)
▪ Performance and Risk Metrics (metrics.py)
▪ Optimization routines (optimization.py)
- Additionally, the “ml_model” sub-package under pypm contains modules for machine learning aspects such as data handling (data_io.py), event detection, feature extraction, label generation, model building, and signal generation.

##### Relationships and Interactions
- Data flows from the raw CSV files (data layer) into the processing modules within pypm, where they are ingested and transformed.
- Technical indicators and signals are computed using functions from “indicators.py” and “signals.py”, which can then feed into both portfolio simulation and trading signal generation.
- Optimization routines (“optimization.py”) and performance evaluation (“metrics.py”) operate on portfolio and trading output to scan through parameters (e.g., via grid search in chapter 5).
- The simulation modules handle portfolio-level studies, while machine learning pipelines use modules from the ml_model sub-package to process data, generate features, and train models.
- The various “listings” scripts reference these core modules, demonstrating practical use cases and integrations between data ingestion, indicator calculations, simulation, and optimization.

##### Architectural Patterns and Design Principles
- Modular Design: The project is clearly divided into reusable components (data handling, analytics, simulation, etc.) which help in isolating functionalities and improving testability.
- Separation of Concerns: There is a clean separation between the raw data (in the data directory), utility functions and modules (in src/pypm), and the user-facing examples (in listings).
- Extendability: The library has a plugin-like feel, especially with the machine learning components organized separately, suggesting that extending or substituting one module (for example, swapping out an indicator function) is straightforward.
- Object-Oriented Elements: Several chapters (e.g., chapter 4) introduce classes that encapsulate behaviors for portfolio management and simulation.

##### Relevant Technologies, Frameworks, or Libraries
- Python (with heavy use of Pandas for data manipulation)
- Custom implementations of technical indicators, risk metrics, and optimization routines.
- Machine Learning workflows, likely using scikit-learn or similar packages, are hinted at in the ml_model directory.
- The overall structure supports a notebook/script-based exploration which complements the explanations in the book.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        DL["Data Layer"]:::data
    end

    %% Core Library
    subgraph "Core Library"
        %% Data Ingestion
        subgraph "Data Ingestion"
            DIO["Data I/O (data_io.py)"]:::core
        end
        %% Technical Analysis
        subgraph "Technical Analysis"
            IND["Indicators (indicators.py)"]:::core
            SIG["Signals (signals.py)"]:::core
        end
        %% Portfolio Management
        subgraph "Portfolio Management"
            PORT["Portfolio (portfolio.py)"]:::core
            SIM["Simulation (simulation.py)"]:::core
            WGT["Weights (weights.py)"]:::core
        end
        %% Performance & Optimization
        subgraph "Performance & Optimization"
            MET["Performance Metrics (metrics.py)"]:::core
            OPT["Optimization (optimization.py)"]:::core
        end
        %% Machine Learning Pipeline
        ML["Machine Learning Pipeline (ml_model)"]:::core
    end

    %% Application Layer
    subgraph "Application Layer"
        subgraph "Entry Scripts"
            BS["Bootstrap (bootstrap_portfolio.py)"]:::app
            OP["Optimize (optimize_portfolio.py)"]:::app
            SP["Simulate (simulate_portfolio.py)"]:::app
            FA["Fit Model (fit_alternative_data_model.py)"]:::app
            SA["Simulate Alternative (simulate_alternative_data_portfolio.py)"]:::app
            WN["White Noise (white_noise_portfolio.py)"]:::app
        end
        EX["Example Scripts (listings)"]:::example
    end

    %% Data Flow Connections
    DL -->|"CSV Input"| DIO
    DIO -->|"Data Transformation"| IND
    DIO -->|"Data Preparation"| SIG
    DIO -->|"ML Data Ingestion"| ML

    IND -->|"Compute Indicators"| PORT
    SIG -->|"Generate Signals"| PORT
    IND -->|"Feature Extraction"| ML
    SIG -->|"Signal Processing"| ML

    PORT -->|"Simulate Portfolio"| SIM
    PORT -->|"Determine Weights"| WGT

    SIM -->|"Evaluate Performance"| MET
    SIM -->|"Optimize Parameters"| OPT

    %% Application Scripts Connections
    BS -->|"Initializes"| DIO
    OP -->|"Triggers Optimization"| OPT
    SP -->|"Executes Simulation"| SIM
    FA -->|"Feeds ML Pipeline"| ML
    SA -->|"Runs Alternative Simulation"| SIM
    WN -->|"Executes Simulation"| SIM

    EX -->|"Demonstrates Ingestion"| DIO
    EX -->|"Demonstrates Analysis"| IND
    EX -->|"Demonstrates Signal Generation"| SIG
    EX -->|"Demonstrates Portfolio Management"| PORT

    %% Legend
    subgraph "Legend"
        L1["Data Layer (Blue)"]:::data
        L2["Core Library (Orange)"]:::core
        L3["Entry Scripts (Red)"]:::app
        L4["Example Scripts (Green)"]:::example
    end

    %% Click Events for Component Mapping
    click DL "https://github.com/chrisconlan/algorithmic-trading-with-python/tree/master/data/"
    click EX "https://github.com/chrisconlan/algorithmic-trading-with-python/tree/master/listings/"
    click DIO "https://github.com/chrisconlan/algorithmic-trading-with-python/blob/master/src/pypm/data_io.py"
    click IND "https://github.com/chrisconlan/algorithmic-trading-with-python/blob/master/src/pypm/indicators.py"
    click SIG "https://github.com/chrisconlan/algorithmic-trading-with-python/blob/master/src/pypm/signals.py"
    click PORT "https://github.com/chrisconlan/algorithmic-trading-with-python/blob/master/src/pypm/portfolio.py"
    click SIM "https://github.com/chrisconlan/algorithmic-trading-with-python/blob/master/src/pypm/simulation.py"
    click WGT "https://github.com/chrisconlan/algorithmic-trading-with-python/blob/master/src/pypm/weights.py"
    click MET "https://github.com/chrisconlan/algorithmic-trading-with-python/blob/master/src/pypm/metrics.py"
    click OPT "https://github.com/chrisconlan/algorithmic-trading-with-python/blob/master/src/pypm/optimization.py"
    click ML "https://github.com/chrisconlan/algorithmic-trading-with-python/tree/master/src/pypm/ml_model/"
    click BS "https://github.com/chrisconlan/algorithmic-trading-with-python/blob/master/src/bootstrap_portfolio.py"
    click OP "https://github.com/chrisconlan/algorithmic-trading-with-python/blob/master/src/optimize_portfolio.py"
    click SP "https://github.com/chrisconlan/algorithmic-trading-with-python/blob/master/src/simulate_portfolio.py"
    click FA "https://github.com/chrisconlan/algorithmic-trading-with-python/blob/master/src/fit_alternative_data_model.py"
    click SA "https://github.com/chrisconlan/algorithmic-trading-with-python/blob/master/src/simulate_alternative_data_portfolio.py"
    click WN "https://github.com/chrisconlan/algorithmic-trading-with-python/blob/master/src/white_noise_portfolio.py"

    %% Styles
    classDef data fill:#b3d9ff,stroke:#333,stroke-width:2px;
    classDef core fill:#ffd699,stroke:#333,stroke-width:2px;
    classDef app fill:#ffb3b3,stroke:#333,stroke-width:2px;
    classDef example fill:#ccffcc,stroke:#333,stroke-width:2px;
```
