# jo-marcel/spy-volatility-research architecture

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

- Interactive diagram: https://gitdiagram.com/jo-marcel/spy-volatility-research
- Repository: https://github.com/jo-marcel/spy-volatility-research

## Overview

This is a quantitative research workflow studying whether trailing SPY volatility predicts next-day absolute-return magnitude—not a trading system. The principal run loads prices, builds features, analyzes full-sample association, evaluates fixed holdout and yearly walk-forward predictions, analyzes volatility regimes, then produces charts and a summary. The graph preserves documented model, baseline, metrics, visualization, and regime stages. Edges follow the main and sampled module calls; some documented capabilities have unsampled implementations, so their internal links are omitted.

Main entry points: [`main.py`](https://github.com/jo-marcel/spy-volatility-research/blob/main/main.py) (Study Runner), [`holdout.py`](https://github.com/jo-marcel/spy-volatility-research/blob/main/holdout.py) (Fixed Holdout), [`walk_forward.py`](https://github.com/jo-marcel/spy-volatility-research/blob/main/walk_forward.py) (Walk-Forward Evaluation), [`predict.py`](https://github.com/jo-marcel/spy-volatility-research/blob/main/predict.py) (Model Predictions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data and Features"]
  node_config["Shared Settings<br/>[config.py]"]
  node_prices["SPY Prices<br/>[SPY_2015_2025.csv]"]
  node_loader["Price Loader<br/>[data_loader.py]"]
  node_features["Feature Builder<br/>[features.py]"]
end

subgraph group_analysis["Analysis and Evaluation"]
  node_main["Study Runner<br/>[main.py]"]
  node_inference["Association Analysis<br/>[inference.py]"]
  node_holdout["Fixed Holdout<br/>[holdout.py]"]
  node_split["Chronological Splits<br/>[split_data.py]"]
  node_predict["Model Predictions<br/>[predict.py]"]
  node_models["Regression Models<br/>[models.py]"]
  node_baselines["Mean Median Baselines<br/>[baselines.py]"]
  node_metrics["Error Metrics<br/>[metrics.py]"]
  node_walkforward["Walk-Forward Evaluation<br/>[walk_forward.py]"]
  node_regimes["Volatility Regimes<br/>[regimes.py]"]
end

subgraph group_reporting["Research Outputs"]
  node_historyplots["Historical Charts<br/>[plots_history.py]"]
  node_modelplots["Model Charts<br/>[plots_models.py]"]
  node_summary["Summary Export<br/>[export_summary.py]"]
  node_figures["Research Figures"]
  node_results["Research Results<br/>[summary.json]"]
end

node_researcher(("Researcher"))

node_researcher -->|"runs"| node_main
node_main -->|"loads prices"| node_loader
node_loader -->|"reads"| node_prices
node_loader -->|"uses path"| node_config
node_main -->|"builds features"| node_features
node_features -->|"uses settings"| node_config
node_main -->|"analyzes association"| node_inference
node_inference -->|"uses design matrix"| node_models
node_main -->|"runs holdout"| node_holdout
node_holdout -->|"splits data"| node_split
node_holdout -->|"predicts"| node_predict
node_holdout -->|"scores"| node_metrics
node_holdout -->|"writes predictions and metrics"| node_results
node_predict -->|"fits and predicts"| node_models
node_predict -->|"adds baselines"| node_baselines
node_main -->|"runs yearly evaluation"| node_walkforward
node_walkforward -->|"splits by year"| node_split
node_walkforward -->|"predicts yearly"| node_predict
node_walkforward -->|"scores yearly"| node_metrics
node_walkforward -->|"writes predictions and metrics"| node_results
node_main -->|"analyzes regimes"| node_regimes
node_main -->|"plots history"| node_historyplots
node_main -->|"plots model results"| node_modelplots
node_historyplots -->|"uses figure path"| node_config
node_historyplots -->|"writes charts"| node_figures
node_main -->|"exports summary"| node_summary
node_summary -->|"uses results path"| node_config
node_summary -->|"writes summary"| node_results

click node_main "https://github.com/jo-marcel/spy-volatility-research/blob/main/main.py"
click node_config "https://github.com/jo-marcel/spy-volatility-research/blob/main/config.py"
click node_prices "https://github.com/jo-marcel/spy-volatility-research/blob/main/SPY_2015_2025.csv"
click node_loader "https://github.com/jo-marcel/spy-volatility-research/blob/main/data_loader.py"
click node_features "https://github.com/jo-marcel/spy-volatility-research/blob/main/features.py"
click node_inference "https://github.com/jo-marcel/spy-volatility-research/blob/main/inference.py"
click node_holdout "https://github.com/jo-marcel/spy-volatility-research/blob/main/holdout.py"
click node_split "https://github.com/jo-marcel/spy-volatility-research/blob/main/split_data.py"
click node_predict "https://github.com/jo-marcel/spy-volatility-research/blob/main/predict.py"
click node_models "https://github.com/jo-marcel/spy-volatility-research/blob/main/models.py"
click node_baselines "https://github.com/jo-marcel/spy-volatility-research/blob/main/baselines.py"
click node_metrics "https://github.com/jo-marcel/spy-volatility-research/blob/main/metrics.py"
click node_walkforward "https://github.com/jo-marcel/spy-volatility-research/blob/main/walk_forward.py"
click node_regimes "https://github.com/jo-marcel/spy-volatility-research/blob/main/regimes.py"
click node_historyplots "https://github.com/jo-marcel/spy-volatility-research/blob/main/plots_history.py"
click node_modelplots "https://github.com/jo-marcel/spy-volatility-research/blob/main/plots_models.py"
click node_summary "https://github.com/jo-marcel/spy-volatility-research/blob/main/export_summary.py"
click node_figures "https://github.com/jo-marcel/spy-volatility-research/tree/main/figures"
click node_results "https://github.com/jo-marcel/spy-volatility-research/blob/main/results/summary.json"

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_config,node_prices,node_loader,node_features toneBlue
class node_main,node_inference,node_holdout,node_split,node_predict,node_models,node_baselines,node_metrics,node_walkforward,node_regimes toneAmber
class node_historyplots,node_modelplots,node_summary,node_figures,node_results toneMint
class node_researcher toneIndigo
```

## Components

### Data and Features

- [Shared Settings](https://github.com/jo-marcel/spy-volatility-research/blob/main/config.py): `config.py`
- [SPY Prices](https://github.com/jo-marcel/spy-volatility-research/blob/main/SPY_2015_2025.csv): `SPY_2015_2025.csv`
- [Price Loader](https://github.com/jo-marcel/spy-volatility-research/blob/main/data_loader.py): `data_loader.py`
- [Feature Builder](https://github.com/jo-marcel/spy-volatility-research/blob/main/features.py): `features.py`

### Analysis and Evaluation

- [Study Runner](https://github.com/jo-marcel/spy-volatility-research/blob/main/main.py): `main.py`
- [Association Analysis](https://github.com/jo-marcel/spy-volatility-research/blob/main/inference.py): `inference.py`
- [Fixed Holdout](https://github.com/jo-marcel/spy-volatility-research/blob/main/holdout.py): `holdout.py`
- [Chronological Splits](https://github.com/jo-marcel/spy-volatility-research/blob/main/split_data.py): `split_data.py`
- [Model Predictions](https://github.com/jo-marcel/spy-volatility-research/blob/main/predict.py): `predict.py`
- [Regression Models](https://github.com/jo-marcel/spy-volatility-research/blob/main/models.py): `models.py`
- [Mean Median Baselines](https://github.com/jo-marcel/spy-volatility-research/blob/main/baselines.py): `baselines.py`
- [Error Metrics](https://github.com/jo-marcel/spy-volatility-research/blob/main/metrics.py): `metrics.py`
- [Walk-Forward Evaluation](https://github.com/jo-marcel/spy-volatility-research/blob/main/walk_forward.py): `walk_forward.py`
- [Volatility Regimes](https://github.com/jo-marcel/spy-volatility-research/blob/main/regimes.py): `regimes.py`

### Research Outputs

- [Historical Charts](https://github.com/jo-marcel/spy-volatility-research/blob/main/plots_history.py): `plots_history.py`
- [Model Charts](https://github.com/jo-marcel/spy-volatility-research/blob/main/plots_models.py): `plots_models.py`
- [Summary Export](https://github.com/jo-marcel/spy-volatility-research/blob/main/export_summary.py): `export_summary.py`
- [Research Figures](https://github.com/jo-marcel/spy-volatility-research/tree/main/figures): `figures`
- [Research Results](https://github.com/jo-marcel/spy-volatility-research/blob/main/results/summary.json): `results/summary.json`

### Other components

- **Researcher**

## Connections

- Researcher → Study Runner: runs (evidence: `README.md`)
- Study Runner → Price Loader: loads prices (evidence: `main.py`)
- Price Loader → SPY Prices: reads (evidence: `data_loader.py`)
- Price Loader → Shared Settings: uses path (evidence: `data_loader.py`)
- Study Runner → Feature Builder: builds features (evidence: `main.py`)
- Feature Builder → Shared Settings: uses settings (evidence: `features.py`)
- Study Runner → Association Analysis: analyzes association (evidence: `main.py`)
- Association Analysis → Regression Models: uses design matrix (evidence: `inference.py`)
- Study Runner → Fixed Holdout: runs holdout (evidence: `main.py`)
- Fixed Holdout → Chronological Splits: splits data (evidence: `holdout.py`)
- Fixed Holdout → Model Predictions: predicts (evidence: `holdout.py`)
- Fixed Holdout → Error Metrics: scores (evidence: `holdout.py`)
- Fixed Holdout → Research Results: writes predictions and metrics (evidence: `holdout.py`)
- Model Predictions → Regression Models: fits and predicts (evidence: `predict.py`)
- Model Predictions → Mean Median Baselines: adds baselines (evidence: `predict.py`)
- Study Runner → Walk-Forward Evaluation: runs yearly evaluation (evidence: `main.py`)
- Walk-Forward Evaluation → Chronological Splits: splits by year (evidence: `walk_forward.py`)
- Walk-Forward Evaluation → Model Predictions: predicts yearly (evidence: `walk_forward.py`)
- Walk-Forward Evaluation → Error Metrics: scores yearly (evidence: `walk_forward.py`)
- Walk-Forward Evaluation → Research Results: writes predictions and metrics (evidence: `walk_forward.py`)
- Study Runner → Volatility Regimes: analyzes regimes (evidence: `main.py`)
- Study Runner → Historical Charts: plots history (evidence: `main.py`)
- Study Runner → Model Charts: plots model results (evidence: `main.py`)
- Historical Charts → Shared Settings: uses figure path (evidence: `plots_history.py`)
- Historical Charts → Research Figures: writes charts (evidence: `plots_history.py`)
- Study Runner → Summary Export: exports summary (evidence: `main.py`)
- Summary Export → Shared Settings: uses results path (evidence: `export_summary.py`)
- Summary Export → Research Results: writes summary (evidence: `export_summary.py`)