# ayushbaral/s_score architecture

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

- Interactive diagram: https://gitdiagram.com/ayushbaral/s_score
- Repository: https://github.com/ayushbaral/s_score

## Overview

##### Project type and purpose
- This is a data-analysis/algorithmic-trading toolkit implemented as a pair of Jupyter notebooks.
- Its purpose is to download 1-year historical price data for 508 stocks + SPY, compute an S-Score via a PCA-based statistical arbitrage model (Avellaneda & Lee), and emit buy/sell signals.

##### File structure
- Top-level files:
- download_data.ipynb – data ingestion notebook
- signals.ipynb – core algorithm and signal generation notebook
- 500_stocks_1yr.csv, SPY_1yr.csv – raw data outputs
- requirements.txt – Python deps (pandas, numpy, scikit-learn, statsmodels, etc.)
- README.md – project overview & algorithm steps
- No frontend/backend split; it’s a linear data pipeline orchestrated in notebooks.

##### README for additional insights
- Algorithm stages enumerated: return computation → standardization → covariance matrix → PCA → eigenportfolio returns → regression residuals → OU process test & AR(1) → S-Score → trading signals.

##### Detail without over-splitting
- Dependencies (e.g., PCA module depends on covariance matrix).
- Environment/dependency management is shown (virtual environment → requirements.txt → runs notebooks).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data Source
    API["Yahoo Finance API"]:::storage

    %% Data Ingestion Notebook
    DL["download_data.ipynb"]:::notebook

    %% Raw Data Store
    subgraph "Raw Data Store" 
        direction TB
        CSV1["500_stocks_1yr.csv"]:::storage
        CSV2["SPY_1yr.csv"]:::storage
    end

    %% Analysis Notebook and Modules
    subgraph "signals.ipynb" 
        direction TB
        RC["Returns Calculator"]:::module
        SD["Standardizer"]:::module
        PCA["Covariance Matrix & PCA Engine"]:::module
        EP["Eigenportfolio Generator"]:::module
        RR["Regression & Residual Calculator"]:::module
        OU["OU-Process Validator & AR(1) Module"]:::module
        SS["S-Score Computation & Signal Logic"]:::module
    end

    %% Output
    OUT["Trading Signals & Charts"]:::output

    %% Environment
    ENV["Python Virtualenv\n(requirements.txt)"]:::env
    DOC["Project Docs\n(README.md)"]:::env

    %% Flow
    API -->|"price history request"| DL
    DL -->|"writes CSVs"| CSV1
    DL -->|"writes CSVs"| CSV2
    CSV1 -->|"reads data"| RC
    CSV2 -->|"reads data"| RC
    RC --> SD
    SD --> PCA
    PCA --> EP
    EP --> RR
    RR --> OU
    OU --> SS
    SS -->|"signals output"| OUT

    ENV --> DL
    ENV --> RC
    ENV --> SD
    ENV --> PCA
    ENV --> EP
    ENV --> RR
    ENV --> OU
    ENV --> SS
    DOC -.->|"documentation"| DL
    DOC -.->|"documentation"| RC

    %% Click Events
    click DL "https://github.com/ayushbaral/s_score/blob/main/download_data.ipynb"
    click CSV1 "https://github.com/ayushbaral/s_score/blob/main/500_stocks_1yr.csv"
    click CSV2 "https://github.com/ayushbaral/s_score/blob/main/SPY_1yr.csv"
    click RC "https://github.com/ayushbaral/s_score/blob/main/signals.ipynb"
    click SD "https://github.com/ayushbaral/s_score/blob/main/signals.ipynb"
    click PCA "https://github.com/ayushbaral/s_score/blob/main/signals.ipynb"
    click EP "https://github.com/ayushbaral/s_score/blob/main/signals.ipynb"
    click RR "https://github.com/ayushbaral/s_score/blob/main/signals.ipynb"
    click OU "https://github.com/ayushbaral/s_score/blob/main/signals.ipynb"
    click SS "https://github.com/ayushbaral/s_score/blob/main/signals.ipynb"
    click ENV "https://github.com/ayushbaral/s_score/blob/main/requirements.txt"
    click DOC "https://github.com/ayushbaral/s_score/blob/main/README.md"

    %% Styles
    classDef storage fill:#cce5ff,stroke:#004085;
    classDef notebook fill:#d4edda,stroke:#155724;
    classDef module fill:#fff3cd,stroke:#856404;
    classDef output fill:#f5c6cb,stroke:#721c24;
    classDef env fill:#e2e3e5,stroke:#6c757d;
```
