How rubenke/indicator-stock-prediction-study works
1. Overall shape
- This repo is an offline research harness for algorithmic trading experiments.
- It has two largely separate experiment tracks: rule-based strategy backtests and supervised ML prediction/backtests.
- Both tracks consume the same historical OHLCV market data and share the same config-driven cost/risk assumptions.
2. Configuration as the control plane
- config/config.yaml is the main source of truth for instruments, intervals, parameter grids, commissions, slippage, risk sizing, and ML settings.
- Most scripts read from this file rather than hardcoding symbols or tuning values, which keeps experiments reproducible and diagram-friendly as a single upstream dependency.
3. Market data ingestion boundary
- utils/data_loader.py downloads OHLCV data from yfinance and stores it as Parquet in data/raw/.
- The loader truncates datasets to a bounded recent window, so the raw-data layer is a curated local cache rather than a full market history warehouse.
- This raw dataset is the shared input for both the classic backtesting pipeline and ML feature generation.
4. Classic strategy subsystem
- strategies/ contains the rule-based trading logic: breakout, mean reversion, trend-following, VWAP, RSI, DMAC, SMC-style structure sweep, and risk-managed variants.
- run_all.py orchestrates batch backtests across strategy definitions, instruments, intervals, and parameter grids from config.
- The output is aggregated experiment rows in database/results.parquet, one row per strategy/asset/interval/parameter combination.
5. Single-strategy execution path
- utils/single_strategy_runner.py provides a focused entry point for running one strategy with full per-bar outputs.
- This is a diagnostic boundary: it returns summary stats, equity curve, input price data, and the underlying strategy result object for deeper inspection.
- It uses the same cost/risk settings as the batch runner unless overridden.
6. ML feature and dataset subsystem
- ml/features.py and ml/datasets.py build the supervised learning view from raw OHLCV data.
- The ML target is next-candle direction, and the pipeline keeps per-dataset caches under data/features/, including a manifest of usable datasets.
- This layer is explicitly separate from the rule-based strategies: it transforms market data into model-ready tabular features and labels.
7. ML model training and evaluation flow
- run_ml.py is the ML orchestration entry point, supporting feature preparation, single-dataset runs, quick runs, and full leave-one-dataset-out evaluation.
- ml/train_eval.py, ml/models.py, ml/persistence.py, ml/utils.py, and ml/types.py together handle model training, scoring, signal generation, artifact saving, and typed experiment metadata.
- The evaluation design is group-based by dataset: train on all but one dataset, then test on the held-out dataset, so the test boundary is by symbol/interval dataset rather than random candles.
8. ML artifact and results layout
- Trained models and run metadata are stored under models/ml_registry/{run_id}/....
- Per-candle predictions and signals are written to analysis/results/ml/{run_id}/....
- Aggregate ML metrics land in database/ml_results.csv, making the ML outputs split across three layers: model registry, detailed run outputs, and summary database.
9. Analysis and reporting subsystem
- analysis/ml_results_analyzer.py is a CLI reporting tool that reads the ML summary table, ranks runs, exports tables/plots, and produces a markdown report.
- The notebooks in analysis/ and utils/ are exploratory consumers of the same saved artifacts, not part of the production pipeline.
- This creates a clear downstream analysis boundary: both strategy families write durable results, and analysis tools read those results without rerunning experiments.
10. Risk optimization loop
- optimize_risk_params.py is a separate experimental loop that searches over risk-sizing settings.
- It writes outcomes to analysis/results/risk_optimization.csv and can optionally update config/config.yaml.
- In architecture terms, this is a feedback path from analysis back into the central config, affecting both classic and ML backtests.
11. Persistence and storage boundaries
- The repo uses local files as its main persistence mechanism: Parquet for raw and classic results, CSV for summary tables, JSON for manifests/metadata, and joblib-style model artifacts inside the ML registry.
- database/ is the result store for aggregated experiment tables, while analysis/results/ holds exported analysis artifacts and detailed ML predictions.
- The separation between raw data, feature cache, model registry, and analysis outputs is important for drawing accurate storage boundaries.
12. Tests and validation
- tests/test_ml_pipeline.py and tests/test_ml_results_analyzer.py validate the ML pipeline and reporting path.
- These tests suggest the most important contract surfaces are: feature preparation/training correctness and the ability to parse and summarize experiment outputs.
13. What to show in a diagram
- A clean architecture diagram should center on three main flows:
- yfinance -> data/raw -> classic strategies -> database/results.parquet
- yfinance -> data/raw -> ml feature cache -> model training/eval -> models/ml_registry + analysis/results/ml + database/ml_results.csv
- results databases -> analysis notebooks/CLI analyzers
- config/config.yaml should sit above both pipelines as the shared control input, with optimize_risk_params.py feeding back into it.
Main entry points: train_eval.py Train/eval core · config.yaml Config · ml_results.csv ML summary · atr_volatility_breakout.py Strategies
Components 20
Control plane
Shared configuration and feedback loops that steer experiments.
- Config · Main source of truth for instruments, intervals, costs, risk sizing, and ML settings.
config/config.yaml - Risk optimizer · Searches risk-sizing settings and can feed updates back into the config.
optimize_risk_params.py
Market data
Raw data ingestion and cached feature datasets.
- Data loader · Downloads OHLCV data from yfinance and stores bounded recent windows as local Parquet cache.
utils/data_loader.py - Raw cache · Curated local OHLCV dataset used by both strategy and ML pipelines.
Classic strategies
Rule-based strategy backtesting and single-run diagnostics.
- Strategies · Collection of breakout, mean reversion, trend, VWAP, RSI, DMAC, and structure-based strategies.
strategies/atr_volatility_breakout.py - Batch runner · Runs strategy backtests across instruments, intervals, and parameter grids from config.
run_all.py - Single runner · Executes one strategy and returns detailed per-bar outputs and summary stats.
utils/single_strategy_runner.py - Strategy results · Aggregated experiment rows for classic strategy runs.
database/ml_results.parquet
ML pipeline
Supervised feature generation, model training, and evaluation.
- Feature builder · Builds supervised features and next-candle labels from raw OHLCV data.
ml/features.py - Dataset cache · Stores reusable ML datasets, manifests, and prepared tabular inputs.
ml/datasets.py - ML runner · Coordinates feature preparation, quick runs, single-dataset runs, and leave-one-dataset-out evaluation.
run_ml.py - Train/eval core · Model training, scoring, signal generation, persistence, utilities, and typed metadata.
ml/train_eval.py - Model registry · Stored models and run metadata under per-run directories.
- ML outputs · Per-candle predictions and signals written for each ML run.
- ML summary · Aggregate ML metrics for ranking and reporting.
database/ml_results.csv
Analysis
Reporting, notebooks, and downstream consumers of saved results.
- ML analyzer · Ranks runs, exports tables and plots, and writes markdown reports from ML summary results.
analysis/ml_results_analyzer.py - ML notebooks · Exploratory consumers of saved ML artifacts and summary tables.
analysis/ml_results_analysis.ipynb - Non-ML analysis · Exploratory consumers of classic strategy outputs and broader offline analysis.
analysis/non_ml_full_analysis.ipynb - Pipeline test · Validates feature preparation and training pipeline contracts.
tests/test_ml_pipeline.py - Analyzer test · Validates parsing and summarization of experiment outputs.
tests/test_ml_results_analyzer.py
Connections 24
- Config → Batch runner: controls · Strategy universe, grids, and costs are read from config.
- Config → ML runner: controls · ML settings and dataset/evaluation options come from config.
- Config → Single runner: controls · Shares cost and risk assumptions with the focused runner.
- Config → Risk optimizer: searches · Risk optimization evaluates settings against the central config.
- Risk optimizer → Config: updates · Optional feedback path writes improved risk parameters back to config.
- Data loader → Raw cache: writes · Downloads and caches OHLCV data as local Parquet.
- Raw cache → Strategies: feeds · Classic strategies consume the shared historical market data.
- Raw cache → Feature builder: feeds · ML feature generation starts from the same raw OHLCV cache.
- Strategies → Batch runner: executes · Batch runner instantiates strategies across parameter grids.
- Batch runner → Strategy results: writes · Aggregated strategy experiment rows are persisted.
- Strategies → Single runner: executes · Single-run path uses the same strategy implementations for diagnostics.
- Single runner → Strategy results: inspects · Detailed outputs complement the aggregated results store.
- Feature builder → Dataset cache: builds · Prepared features and labels are cached as reusable datasets.
- Dataset cache → ML runner: consumed by · Prepared datasets drive the ML orchestration flow.
- ML runner → Train/eval core: orchestrates · Entry point delegates training, evaluation, and artifact persistence.
- Train/eval core → Model registry: writes · Trained models and run metadata are saved per run.
- Train/eval core → ML outputs: writes · Per-candle predictions and signals are exported.
- Train/eval core → ML summary: writes · Aggregate metrics are appended for reporting.
- ML summary → ML analyzer: reads · Analyzer ranks and summarizes runs from the summary table.
- Strategy results → Non-ML analysis: reads · Notebooks inspect classic experiment outputs.
- ML outputs → ML notebooks: reads · Notebooks explore detailed ML predictions and signals.
- ML summary → ML notebooks: reads · Analysis notebooks also consume summary metrics.
- ML summary → Analyzer test: validates · Tests the reporting contract against stored results.
- Train/eval core → Pipeline test: validates · Tests feature preparation and training behavior.