ml-quant-trading

A reproducible PyTorch stack for cross-sectional factor research — from 213 mask-aware factors to cost-aware portfolios, backtests, and auditable reports.

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

Run in Colab · Inspect the benchmark · See cost-aware results · Read the paper

Quick Start

python -m pip install mlquantx
mlquant demo

No market-data account or API key is required. In 30–90 seconds, the deterministic demo runs data → factors → model → portfolio → backtest and writes shareable Markdown and JSON reports.

See the benchmark board for complete environments, commands, and raw results. Cross-machine snapshots are reported separately and are not presented as controlled hardware rankings.

Why this repository?

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.

Ready to modify factors, models, data sources, or backtest assumptions? Install from a source checkout:

git clone https://github.com/initial-d/ml-quant-trading.git
cd ml-quant-trading
python -m pip install -e '.[dev]'

Fast Path

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.

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

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.6 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.

Data Sources

The repository does not redistribute market data. AkShare, Baostock, and yfinance data are downloaded on-demand by the loader scripts. Public upstream interfaces can change or rate-limit requests. Synthetic data is generated deterministically from a fixed seed.

Installation and Demos

python -m pip install mlquantx

# One-command smoke test (synthetic data; no API key required)
mlquant demo

The command prints a stage-by-stage run and writes shareable artifacts/small/summary.md and summary.json reports alongside the model and backtest artifacts. The demo is a deterministic engineering smoke test, not a performance claim.

For development or optional extras, install from a source checkout:

git clone https://github.com/initial-d/ml-quant-trading.git
cd ml-quant-trading
python -m pip install -e '.[dev]'  # add ,gpu for CUDA; add ,mosek for MOSEK solver

Google Colab Quick Start

Run the deterministic end-to-end pipeline in Google Colab without a market-data account or local setup:

The account-based Baostock A-share notebook remains available for users who want that data route.

Public-Data Factor IC Demo

For a lightweight public-data walkthrough, open notebooks/public_factor_ic.ipynb. It downloads a small yfinance universe, computes a factor subset, and plots one-day forward rank IC. If public data download fails, the notebook falls back to the synthetic panel so the workflow remains runnable.

For a larger public-data validation run with walk-forward baselines, costs, slippage, cost-sensitivity reports, optional bootstrap confidence intervals, turnover, drawdown, and equal-weight / momentum / Alpha101 / MLP / Transformer comparisons:

python scripts/public_data_validation.py \
  --source yfinance \
  --preset us-large-100 \
  --max-tickers 100

See docs/public_data_validation.md. Treat these runs as validation diagnostics, not trading recommendations. The script writes summary.md, summary.csv, summary.json, metadata.json, and a copy-ready submission.md for community reports. Add --cost-grid-bps 0,7,15,30 to generate cost_sensitivity.* files, and add --bootstrap-samples 500 to include return and Sharpe uncertainty intervals. Maintainers can aggregate multiple summary.json files with scripts/aggregate_validation_reports.py and audit individual reports with scripts/audit_validation_report.py.

Tensor Factor Benchmark

To benchmark core tensor primitives and a small factor subset on CPU/GPU, run:

make benchmark

See docs/benchmarking.md for larger-panel commands and reporting guidance. Benchmark reports from different machines are welcome through the Benchmark result issue template.

Reproducible Dev Environment

For a Docker-based CPU environment:

docker build -t ml-quant-trading .
docker run --rm ml-quant-trading make test

See docs/docker.md for Docker benchmark, synthetic pipeline, and public-data validation commands.

For VS Code or GitHub Codespaces, use the included Dev Container:

.devcontainer/devcontainer.json

It installs Python 3.11 and the project with python -m pip install -e '.[dev]'.

Factor Library (213 factors: 9 Alpha101 + 204 legacy)

The full feature set comprises 9 curated Alpha101 formulas (features.alpha101) plus 204 hand-crafted legacy factors (features.legacy_factors) for a total of 213 dimensions. All factors are mask-aware PyTorch tensors with signature Panel → (values[T,N], mask[T,N]).

📖 Factor Handbook: English · 中文 — design notes and implementation rationale for each factor.

add_001    add_002    add_003    add_004    add_005    add_006
add_007    add_008    add_009    add_010    add_011    add_012
add_013    add_014    add_015    add_016    add_017    add_018
add_019    add_020    add_021    add_022    add_023    add_024
add_025    add_026    add_027    add_028    add_029    add_030
best_001   best_002   best_003   best_004   best_005   best_006
best_007   best_008   best_009   best_010   best_011   best_012
best_013   best_014   best_015   best_016   best_017   best_018
best_019   best_020   best_021
change_001 change_002 change_003 change_004 change_005
extra_001  extra_002  extra_003  extra_004  extra_005  extra_006
extra_007  extra_008  extra_009  extra_010  extra_011  extra_012
extra_013  extra_014
old_027    old_028    old_029    old_030    old_031    old_032
old_033    old_034    old_035    old_036    old_037    old_038
old_039    old_040    old_041    old_042    old_043    old_044
old_045    old_046    old_047    old_048    old_049    old_050
old_051    old_052    old_053    old_054    old_055    old_056
old_057    old_058    old_059    old_060    old_061    old_062
old_063    old_064    old_065    old_066    old_067    old_068
old_069    old_070    old_071    old_072    old_073    old_074
old_075    old_076
original_001 original_002 original_003 original_004 original_005
original_006 original_007 original_008 original_009 original_010
original_011 original_012 original_013 original_014 original_015
original_016 original_017 original_018 original_019 original_020
original_021 original_022 original_023 original_024 original_025
original_026 original_027 original_028
stock_001  stock_002  stock_003  stock_004  stock_005  stock_006
stock_007  stock_008  stock_009  stock_010  stock_011  stock_012
stock_013  stock_014  stock_015  stock_016  stock_017  stock_018
stock_019  stock_020  stock_021  stock_022

Data Sources

You can directly fetch stock data from Yahoo Finance, Baostock, or AkShare.

yfinance:

from mlquant.data import make_panel

panel = make_panel(
    source="yfinance",
    tickers=["000001.SZ", "600000.SS"],
    start="2020-01-01",
    end="2023-12-31"
)

baostock:

from mlquant.data import make_panel

panel = make_panel(
    source="baostock",
    tickers=["sh.600000", "sz.000001"],
    start="2020-01-01",
    end="2023-12-31"
)

AkShare (A-shares, no API key):

from mlquant.data import make_panel

panel = make_panel(
    source="akshare",
    tickers=["600519", "000001"],
    start="2020-01-01",
    end="2023-12-31",
    adjust="qfq",
)

AkShare uses public upstream interfaces, so availability, schemas, and rate limits can change independently of this project.

Usage

from mlquant.features import compute_legacy_set, LEGACY_REGISTRY

# Compute all 213 factors (204 legacy + 9 Alpha101)
factors, mask, names = compute_legacy_set(panel)  # → [T, N, 213]

# Or a subset
factors, mask, names = compute_legacy_set(panel, names=("best_001", "add_015", "old_042"))

Architecture

flowchart LR
    subgraph Data["1. Data"]
        A[Raw OHLCV] --> B[loaders<br/>synthetic / yfinance / baostock / akshare]
    end
    subgraph Features["2. Features"]
        B --> C[tensor_factors<br/>GPU masked primitives]
        C --> D[bias<br/>limit-up/down/halt correction]
        D --> E[compute_legacy_set<br/>213-factor tensor<br/>204 legacy + 9 Alpha101]
    end
    subgraph Training["3. Training"]
        E --> F[FactorDataset<br/>forward returns + masks]
        F --> G[MLP Regressor]
        F -.->|optional| GBM[GBM augment]
        G -.->|alternative| T[Transformer]
        G --> H[losses<br/>AdjMSE / IC / RankIC]
    end
    subgraph Portfolio["4. Portfolio"]
        H --> I[Markowitz<br/>Ledoit-Wolf shrunk cov<br/>no-short constraint]
    end
    subgraph Backtest["5. Backtest"]
        I --> J[engine<br/>vectorized backtest]
        J --> K[Sharpe / IC / IR / DD]
    end

Solid = required in default pipeline. Dashed = optional / alternative module (not called by CLI).

Project Layout

ml-quant-trading/
├── src/mlquant/
│   ├── data/           # Panel dataclass, loaders, synthetic generator
│   ├── features/       # Factor engine + 204 legacy + Alpha101
│   ├── training/       # Dataset, augmentation, trainer
│   ├── models/         # MLP, Transformer, losses
│   ├── portfolio/      # Markowitz, frontier sweep
│   ├── backtest/       # Engine, metrics
│   └── cli/            # Command-line interface
├── configs/            # small.yaml (smoke) / paper.yaml (full)
├── tests/              # pytest suite
├── scripts/            # IC eval, frontier plot
├── legacy/             # Original research scripts (archival, unsupported)
└── docs/               # Architecture, factor docs, paper reproduction

Reproducing the Paper

See docs/reproducing_paper.md for table-by-table mapping.

Roadmap

See docs/roadmap.md for contributor-friendly tasks, research extensions, engineering extensions, and community milestones.

For announcements, release posts, and benchmark calls, see the Promotion Kit. For the maintainer growth loop, see docs/growth_plan.md.

Contributing

Contributions are welcome, especially docs, reproducibility notes, tests, data adapters, and small examples. See CONTRIBUTING.md for setup and pull request guidance.

Disclaimer

This repository is for research and engineering experimentation. It is not financial advice, investment advice, or a trading recommendation. Historical backtests and factor results do not guarantee future performance.

Citation

@article{du2025mlquant,
  title  = {Machine Learning Enhanced Multi-Factor Quantitative Trading:
            A Cross-Sectional Portfolio Optimization Approach with Bias Correction},
  author = {Du, Yimin},
  journal= {arXiv preprint arXiv:2507.07107},
  year   = {2025},
  url    = {https://arxiv.org/abs/2507.07107}
}

License

MIT — see LICENSE.