ml-quant-trading

From 213 mask-aware PyTorch factors to cost-aware portfolios and backtests — one reproducible research stack.

Run the whole path on synthetic or public market data: panel construction, factor computation, bias correction, ML baselines, portfolio optimization, vectorized backtesting, and auditable reports.

Languages: English | 简体中文 | 繁體中文

Run in Colab · Run the 30–90 second demo · See cost-aware results · Read the paper

New in v0.2.5 — install the release wheel and run from any directory. The wheel is available directly from GitHub Releases while the mlquant project name awaits PyPI approval. mlquant demo ships with its deterministic configuration, preserving the zero-account factor-to-backtest path.

---

Why this repository?

| You get | Why it matters | |---|---| | 213 factor dimensions | Mask-aware PyTorch factors with documented families and tensor primitives | | One end-to-end path | Data → factors → models → portfolio → cost-aware backtest → report | | Public and synthetic data | Start without proprietary data or an API key, then move to AkShare, Baostock, or yfinance | | Evidence, including failures | Costs, turnover, baselines, caveats, and negative results stay visible | | A contribution path | CI, tests, report templates, Colab, and newcomer-sized research tasks |

Try the live Hugging Face artifacts: the 100,000-row synthetic dataset and 213-input MLP checkpoint. Both come from the deterministic quick start and explicitly exclude real and proprietary market data; see the artifact guide.

Quick Start

python -m pip install https://github.com/initial-d/ml-quant-trading/releases/download/v0.2.5/mlquant-0.2.5-py3-none-any.whl
mlquant demo

No market-data account is required. The deterministic demo prints each pipeline stage and writes a shareable Markdown/JSON report.

Fast Path

| If you want to... | Start here | What you get | |---|---|---| | See the project run | mlquant demo | A 30–90 second synthetic end-to-end smoke test | | Understand the claims | Research Card | Intended use, non-goals, validation status, and data caveats | | Try public data | Public-Data Mini Reproduction | A small yfinance factor-IC check with documented outputs | | Run a larger validation | Public-Data Validation | Walk-forward baselines, costs, turnover, bootstrap CIs, and report artifacts | | Run A-share validation | AkShare CSI 300 Report | Zero-auth A-share validation on the current CSI 300 public universe | | Run paper-style public validation | AkShare CSI 300 Daily 213-Factor Report | Daily 213-factor public-data approximation with turnover control | | Contribute one run | Reproduction report form | Run Colab, submit the generated report, and receive README credit |

Validation Dashboard

Latest maintained public-data snapshot: AkShare CSI 300 Daily 213-Factor Validation. The detailed dashboard includes cost-sensitivity charts, caveats, and reproduction commands.

| Run | Universe | Frequency | Factor set | Main result at 7 bps effective cost | |---|---|---:|---:|---| | Daily 213-factor public approximation | Current CSI 300, 2021-01-04 to 2024-12-31 | Daily | 213 | Buffered factor portfolio: 22.20% ann. return, 0.919 Sharpe, 2.1616 final equity | | Equal-weight baseline | Same panel | Daily | n/a | 17.75% ann. return, 0.882 Sharpe, 1.8744 final equity | | Naive daily factor selection | Same panel | Daily | 213 | Positive gross edge, but high turnover reduces net performance |

The dashboard is intentionally cost-aware: daily factor selection is evaluated with turnover and transaction costs, not just gross returns. The run is a public-data approximation, not an exact paper reproduction or investment claim.

Acknowledgement: the AkShare zero-auth A-share data path was added through contributor work from @redamancy231-create in PR #42.

Community Evidence

| External contribution | What it added | |---|---| | PR #18 | ETF cross-asset public-data reproduction | | PR #34 | Windows/Baostock A-share validation on 25 stocks | | PR #35 | Neutralization and Baostock robustness fixes | | PR #36 | English handbook for all factor families | | PR #42 | Zero-account AkShare loader enabling CSI 300 validation | | PR #47 | Clarified cumulative cost-drag units across code, reports, tests, and documentation |

Independent results are linked to their pull requests so the environment, commands, limitations, and review history remain inspectable. Want to add another machine or universe? Run the zero-account Colab and submit the generated report.

This repository is validation-first: simple baselines, transaction costs, public-data failure modes, and negative results are documented alongside the research pipeline.

One useful contribution takes about ten minutes: run the zero-account Colab, then submit the generated report through the structured form. Successful and failed runs are both useful and credited.

Other current calls for contributors

• Join the August 2026 reproduction challenge: run Colab once, then use the structured report form, whether it succeeds or fails.
• Try the v0.2.5 release.
• Read the Research Card for intended use, current evidence, and non-goals.
• Read the public-data mini reproduction.
• Share benchmark or public-data results in Discussions #13.
• Pick up a newcomer task: more benchmark reports or a paired public-data validation or benchmark contribution.
• Read the Reality Check and Validation Status before interpreting any backtest as evidence of deployable alpha.

Research and educational use only. This project is not investment advice and is not production-ready. Backtest results do not represent live trading performance; they depend on data quality, transaction costs, slippage, and modeling assumptions that differ from real markets. Treat all results as research validation, not verified out-of-sample performance claims. See Reality Check for known limitations.

<details> <summary>中文说明</summary>

仅用于研究和教学。 本项目不构成投资建议，也不是可直接用于实盘交易的 生产系统。回测结果会受到数据质量、交易成本、滑点和建模假设影响，不代表 真实交易表现。请先阅读 Reality Check 中的限制说明。

</details>

| Module | What it does | |--------|-------------| | features.tensor_factors | GPU-vectorised masked primitives (rank, corr, ewma, ts_*) | | features.legacy_factors | 204 hand-crafted alpha factors (English handbook · 中文) | | features.alpha101 | Alpha101-style formulaic factors | | features.neutralize | Cross-sectional & industry neutralisation | | features.bias | Limit-up / limit-down / halt bias correction | | training.augment | GBM data augmentation | | models.nets | MLP / Transformer | | models.losses | AdjMSE, IC, RankIC losses | | portfolio.markowitz | Cross-sectional Markowitz (shrunk cov, no-short) | | backtest.engine | Vectorised backtest → Sharpe / IC / IR / DD |

Data Sources

| Source | Market | Access | Notes | |--------|--------|--------|-------| | AkShare | A-shares | Public, no API key | Zero-auth loader backed by public upstream int