This card summarizes what ml-quant-trading is meant to support today, what it
does not claim, and how to interpret the repository's validation artifacts.
Use this repository as a reproducible research-engineering baseline for multi-factor equity experiments:
- compute mask-aware cross-sectional and time-series factors
- train simple ML baselines on factor panels
- run portfolio construction and vectorized backtests
- compare results against equal-weight and momentum baselines
- document public-data, synthetic-data, and benchmark reports in a reviewable way
The project is designed for students, researchers, and engineers who want a clean starting point for audited experiments rather than a black-box trading system.
This repository is not:
- investment advice
- a production trading engine
- a claim of live deployable alpha
- a substitute for licensed point-in-time market data
- a broker-, exchange-, or order-book-aware execution simulator
Backtest results are research diagnostics. They should not be read as live performance promises.
| Level | Artifact | What it proves | What it does not prove |
|---|---|---|---|
| Synthetic smoke test | make paper CONFIG=configs/small.yaml |
The end-to-end pipeline runs on a local machine | Strategy profitability |
| Public IC mini check | docs/public_data_mini_reproduction.md |
Public-data loading and factor-IC plumbing work | Robust trading performance |
| Public validation run | docs/public_data_validation.md |
Walk-forward baselines, costs, turnover, and reports are reproducible | Institutional data quality or live execution quality |
| Benchmark report | docs/benchmark_board.md |
Runtime and environment characteristics are documented | Predictive power |
| Paper-style reproduction | docs/reproducing_paper.md |
How code maps to the paper-shaped experiment path | Redistribution of restricted data |
The repository supports three practical data paths:
- Synthetic: deterministic GBM panels for smoke tests and CI.
- yfinance: public US equity and ETF examples, subject to provider changes, missing data, and rate limits.
- Baostock: A-share loader support for users with a registered account.
The repository does not redistribute market data. Any serious empirical claim requires point-in-time data, delisting coverage, corporate-action handling, universe membership controls, and lookahead-bias checks.
The current evidence is infrastructure evidence:
- the factor engine, model baselines, portfolio construction, and backtest path are implemented as auditable Python modules
- CI runs tests and a CLI smoke test
- public-data notes document exact commands, universes, dates, and outputs
- validation docs include transaction costs, slippage, turnover, bootstrap intervals, and failure modes such as yfinance rate limiting
This is enough to support reproducible research iteration. It is not enough to support a live trading claim.
- Public-data vendors can revise history, throttle requests, or return partial panels.
- Short public-data windows make Sharpe and IC estimates noisy.
- High-turnover strategies can look promising before costs and deteriorate after realistic cost assumptions.
- Synthetic data validates the pipeline but contains no intended predictive signal.
- A-share research needs careful handling of halts, limit-up/down days, survivorship bias, and historical universe membership.
When sharing a benchmark or validation result, include:
- exact command
- commit SHA
- OS, Python, PyTorch, CPU/GPU, and CUDA availability
- data source, date range, ticker universe, and failed tickers
- cost and slippage assumptions
- whether the result is synthetic, public-data validation, or restricted-data reproduction
- any warnings, rate limits, solver issues, or missing artifacts
Prefer small, reproducible reports over broad performance claims.