# alfred-021/sp500_honest_backtest architecture

> Architecture diagram of the GitHub repository alfred-021/sp500_honest_backtest, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alfred-021/sp500_honest_backtest
- Repository: https://github.com/alfred-021/sp500_honest_backtest

## Overview

This repository is a reproducible S&P 500 classification experiment: load real or synthetic prices, derive past-only features and a five-day direction target, then compare shuffled and time-ordered validation against an always-up baseline. The main runner reports scores and saves results; a second runner compares several algorithms under the same protocol. A from-scratch NumPy neuron is included as an experimental classifier. The README also describes planned extensions, but they are not represented as implemented components. Edges reflect the shown calls and README; source outside the excerpts was not inspected.

Main entry points: [`compare_models.py`](https://github.com/alfred-021/sp500_honest_backtest/blob/main/compare_models.py) (Model comparison), [`run_backtest.py`](https://github.com/alfred-021/sp500_honest_backtest/blob/main/run_backtest.py) (Backtest runner), [`src/evaluate.py`](https://github.com/alfred-021/sp500_honest_backtest/blob/main/src/evaluate.py) (Validation protocols), [`src/data.py`](https://github.com/alfred-021/sp500_honest_backtest/blob/main/src/data.py) (Real data loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experiment["Experiment runners"]
  node_backtest_runner["Backtest runner<br/>[run_backtest.py]"]
  node_comparison_runner["Model comparison<br/>[compare_models.py]"]
end

subgraph group_market_data["Market data"]
  node_real_data["Real data loader<br/>[data.py]"]
  node_synthetic_data["Synthetic generator<br/>[data.py]"]
  node_price_cache[("Price cache")]
  node_yfinance["Yahoo Finance"]
end

subgraph group_modeling["Features and models"]
  node_feature_target["Features and target<br/>[features.py]"]
  node_random_forest["Random forest<br/>[run_backtest.py]"]
  node_model_suite["Comparison model suite<br/>[compare_models.py]"]
  node_neuron["NumPy neuron<br/>[neuron.py]"]
end

subgraph group_evaluation_output["Evaluation and output"]
  node_validation["Validation protocols<br/>[evaluate.py]"]
  node_results["Score reports<br/>[results_sp500.csv]"]
end

node_user(("User"))

node_user -->|"runs"| node_backtest_runner
node_user -->|"runs"| node_comparison_runner
node_backtest_runner -->|"loads prices"| node_real_data
node_backtest_runner -->|"generates prices"| node_synthetic_data
node_comparison_runner -->|"loads prices"| node_real_data
node_comparison_runner -->|"generates prices"| node_synthetic_data
node_real_data -->|"reads and writes"| node_price_cache
node_real_data -->|"downloads prices"| node_yfinance
node_backtest_runner -->|"builds inputs"| node_feature_target
node_comparison_runner -->|"builds inputs"| node_feature_target
node_backtest_runner -->|"configures"| node_random_forest
node_comparison_runner -->|"configures"| node_model_suite
node_comparison_runner -->|"includes classifier"| node_neuron
node_backtest_runner -->|"evaluates"| node_validation
node_comparison_runner -->|"evaluates"| node_validation
node_validation -->|"fits and predicts"| node_random_forest
node_validation -->|"fits and predicts"| node_model_suite
node_validation -->|"fits and predicts"| node_neuron
node_backtest_runner -->|"writes scores"| node_results
node_comparison_runner -->|"writes scores"| node_results

click node_backtest_runner "https://github.com/alfred-021/sp500_honest_backtest/blob/main/run_backtest.py"
click node_comparison_runner "https://github.com/alfred-021/sp500_honest_backtest/blob/main/compare_models.py"
click node_real_data "https://github.com/alfred-021/sp500_honest_backtest/blob/main/src/data.py"
click node_synthetic_data "https://github.com/alfred-021/sp500_honest_backtest/blob/main/src/data.py"
click node_feature_target "https://github.com/alfred-021/sp500_honest_backtest/blob/main/src/features.py"
click node_random_forest "https://github.com/alfred-021/sp500_honest_backtest/blob/main/run_backtest.py"
click node_model_suite "https://github.com/alfred-021/sp500_honest_backtest/blob/main/compare_models.py"
click node_neuron "https://github.com/alfred-021/sp500_honest_backtest/blob/main/src/neuron.py"
click node_validation "https://github.com/alfred-021/sp500_honest_backtest/blob/main/src/evaluate.py"
click node_results "https://github.com/alfred-021/sp500_honest_backtest/blob/main/results/results_sp500.csv"

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_backtest_runner,node_comparison_runner,node_user toneBlue
class node_real_data,node_synthetic_data,node_price_cache,node_yfinance toneAmber
class node_feature_target,node_random_forest,node_model_suite,node_neuron toneMint
class node_validation,node_results toneRose
```

## Components

### Experiment runners

- [Backtest runner](https://github.com/alfred-021/sp500_honest_backtest/blob/main/run_backtest.py): `run_backtest.py`
- [Model comparison](https://github.com/alfred-021/sp500_honest_backtest/blob/main/compare_models.py): `compare_models.py`

### Market data

- [Real data loader](https://github.com/alfred-021/sp500_honest_backtest/blob/main/src/data.py): `src/data.py`
- [Synthetic generator](https://github.com/alfred-021/sp500_honest_backtest/blob/main/src/data.py): `src/data.py`
- **Price cache**
- **Yahoo Finance**

### Features and models

- [Features and target](https://github.com/alfred-021/sp500_honest_backtest/blob/main/src/features.py): `src/features.py`
- [Random forest](https://github.com/alfred-021/sp500_honest_backtest/blob/main/run_backtest.py): `run_backtest.py`
- [Comparison model suite](https://github.com/alfred-021/sp500_honest_backtest/blob/main/compare_models.py): `compare_models.py`
- [NumPy neuron](https://github.com/alfred-021/sp500_honest_backtest/blob/main/src/neuron.py): `src/neuron.py`

### Evaluation and output

- [Validation protocols](https://github.com/alfred-021/sp500_honest_backtest/blob/main/src/evaluate.py): `src/evaluate.py`
- [Score reports](https://github.com/alfred-021/sp500_honest_backtest/blob/main/results/results_sp500.csv): `results/results_sp500.csv`

### Other components

- **User**

## Connections

- User → Backtest runner: runs (evidence: `README.md`)
- User → Model comparison: runs (evidence: `README.md`)
- Backtest runner → Real data loader: loads prices (evidence: `run_backtest.py`)
- Backtest runner → Synthetic generator: generates prices (evidence: `run_backtest.py`)
- Model comparison → Real data loader: loads prices (evidence: `compare_models.py`)
- Model comparison → Synthetic generator: generates prices (evidence: `compare_models.py`)
- Real data loader → Price cache: reads and writes (evidence: `src/data.py`)
- Real data loader → Yahoo Finance: downloads prices (evidence: `src/data.py`)
- Backtest runner → Features and target: builds inputs (evidence: `run_backtest.py`)
- Model comparison → Features and target: builds inputs (evidence: `compare_models.py`)
- Backtest runner → Random forest: configures (evidence: `run_backtest.py`)
- Model comparison → Comparison model suite: configures (evidence: `compare_models.py`)
- Model comparison → NumPy neuron: includes classifier (evidence: `compare_models.py`)
- Backtest runner → Validation protocols: evaluates (evidence: `run_backtest.py`)
- Model comparison → Validation protocols: evaluates (evidence: `compare_models.py`)
- Validation protocols → Random forest: fits and predicts (evidence: `src/evaluate.py`)
- Validation protocols → Comparison model suite: fits and predicts (evidence: `src/evaluate.py`)
- Validation protocols → NumPy neuron: fits and predicts (evidence: `src/evaluate.py`)
- Backtest runner → Score reports: writes scores (evidence: `run_backtest.py`)
- Model comparison → Score reports: writes scores (evidence: `compare_models.py`)
