{"id":51997183,"url":"https://github.com/initial-d/ml-quant-trading","last_synced_at":"2026-08-01T18:00:28.178Z","repository":{"id":305880539,"uuid":"996777566","full_name":"initial-d/ml-quant-trading","owner":"initial-d","description":"PyTorch research stack for ML multi-factor trading: 213 factors, bias correction, portfolio optimization, and vectorized backtesting.","archived":false,"fork":false,"pushed_at":"2026-07-27T08:20:59.000Z","size":2127,"stargazers_count":54,"open_issues_count":3,"forks_count":28,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-07-27T10:10:05.367Z","etag":null,"topics":["a-shares","algorithmic-trading","alpha-factors","backtesting","china-stock-market","cross-sectional","data-augmentation","deep-learning","factor-investing","gpu-computing","machine-learning","multi-factor-model","portfolio-optimization","pytorch","quantitative-finance","quantitative-trading","reproducibility","research-software","stock-prediction","transformer"],"latest_commit_sha":null,"homepage":"https://initial-d.github.io/ml-quant-trading/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/initial-d.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":".zenodo.json","notice":"NOTICE.md","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-05T12:56:51.000Z","updated_at":"2026-07-27T08:22:27.000Z","dependencies_parsed_at":"2025-08-27T11:21:53.002Z","dependency_job_id":"61218b04-10a6-4a57-b1e4-95731eb444c1","html_url":"https://github.com/initial-d/ml-quant-trading","commit_stats":null,"previous_names":["initial-d/ml-quant-trading"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/initial-d/ml-quant-trading","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/initial-d%2Fml-quant-trading","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/initial-d%2Fml-quant-trading/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/initial-d%2Fml-quant-trading/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/initial-d%2Fml-quant-trading/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/initial-d","download_url":"https://codeload.github.com/initial-d/ml-quant-trading/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/initial-d%2Fml-quant-trading/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36165355,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-08-01T02:00:05.789Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a-shares","algorithmic-trading","alpha-factors","backtesting","china-stock-market","cross-sectional","data-augmentation","deep-learning","factor-investing","gpu-computing","machine-learning","multi-factor-model","portfolio-optimization","pytorch","quantitative-finance","quantitative-trading","reproducibility","research-software","stock-prediction","transformer"],"created_at":"2026-07-31T08:00:26.917Z","updated_at":"2026-08-01T18:00:28.172Z","avatar_url":"https://github.com/initial-d.png","language":"Python","funding_links":[],"categories":["回测","Strategies \u0026 Research","Backtest + live trading","Tools and Platforms","Research Frameworks","Machine Learning","Factor Analysis","Backtesting and Live Trading"],"sub_categories":["Portfolio Management","Machine Learning / Reinforcement Learning Focused","On-Chain / DeFi Quantitative Strategies","General - Vector Based Frameworks"],"readme":"# ml-quant-trading\n\n\u003e **Machine Learning Enhanced Multi-Factor Quantitative Trading**\n\u003e — A Cross-Sectional Portfolio Optimization Approach with Bias Correction\n\u003e\n\u003e [arXiv:2507.07107](https://arxiv.org/abs/2507.07107) \u0026nbsp;|\u0026nbsp;\n\u003e [Hugging Face Papers](https://huggingface.co/papers/2507.07107) \u0026nbsp;|\u0026nbsp; Yimin Du, 2025\n\n[![CI](https://github.com/initial-d/ml-quant-trading/actions/workflows/ci.yml/badge.svg)](https://github.com/initial-d/ml-quant-trading/actions/workflows/ci.yml)\n[![GitHub stars](https://img.shields.io/github/stars/initial-d/ml-quant-trading?style=flat\u0026logo=github\u0026label=Stars)](https://github.com/initial-d/ml-quant-trading/stargazers)\n[![GitHub forks](https://img.shields.io/github/forks/initial-d/ml-quant-trading?style=flat\u0026logo=github\u0026label=Forks)](https://github.com/initial-d/ml-quant-trading/forks)\n[![Release](https://img.shields.io/github/v/release/initial-d/ml-quant-trading?display_name=tag)](https://github.com/initial-d/ml-quant-trading/releases)\n[![Project site](https://img.shields.io/badge/project-site-0f7b63.svg)](https://initial-d.github.io/ml-quant-trading/)\n[![arXiv](https://img.shields.io/badge/arXiv-2507.07107-b31b1b.svg)](https://arxiv.org/abs/2507.07107)\n[![Hugging Face Papers](https://img.shields.io/badge/Hugging%20Face-Papers-ffcc4d.svg)](https://huggingface.co/papers/2507.07107)\n[![Awesome Quant](https://img.shields.io/badge/Awesome%20Quant-Factor%20Analysis-4c78a8.svg)](https://github.com/wilsonfreitas/awesome-quant#factor-analysis)\n[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)\n[![MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![ruff](https://img.shields.io/badge/style-ruff-000000.svg)](https://docs.astral.sh/ruff/)\n\nLanguages: [English](README.md) | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md)\n\n![ml-quant-trading social preview](docs/assets/readme-preview.png)\n\n[**Run in Colab**](https://colab.research.google.com/github/initial-d/ml-quant-trading/blob/main/notebooks/quickstart_colab.ipynb)\n· [**See validated results**](docs/validation_dashboard.md)\n· [**Read the paper**](https://arxiv.org/abs/2507.07107)\n· [**Submit one reproduction report**](https://github.com/initial-d/ml-quant-trading/issues/new?template=reproduction_report.yml)\n\n\u003e **August 2026 reproduction challenge:** run the zero-account Colab once and\n\u003e submit its generated report, environment, and commit SHA with the\n\u003e [structured report form](https://github.com/initial-d/ml-quant-trading/issues/new?template=reproduction_report.yml).\n\u003e Successful and failed runs are both useful. Verifiable reports will be credited\n\u003e in the Community Evidence section and summarized in [Discussion #43](https://github.com/initial-d/ml-quant-trading/discussions/43).\n\n---\n\n## What is this?\n\nA **clean, fork-friendly, end-to-end** A-share quantitative trading system:\n\n**In one clone, you get:** a tensor factor engine, 213 factor dimensions, bias correction,\nML baselines, Markowitz portfolio optimization, vectorized backtesting, synthetic/public-data\ndemos, CI, tests, and benchmark tooling.\n\n## Fast Path\n\n| If you want to... | Start here | What you get |\n|---|---|---|\n| See the project run | `mlquant demo` | A 30-90 second synthetic end-to-end smoke test |\n| Understand the claims | [Research Card](docs/research_card.md) | Intended use, non-goals, validation status, and data caveats |\n| Try public data | [Public-Data Mini Reproduction](docs/public_data_mini_reproduction.md) | A small yfinance factor-IC check with documented outputs |\n| Run a larger validation | [Public-Data Validation](docs/public_data_validation.md) | Walk-forward baselines, costs, turnover, bootstrap CIs, and report artifacts |\n| Run A-share validation | [AkShare CSI 300 Report](docs/validation_akshare_csi300_20260729.md) | Zero-auth A-share validation on the current CSI 300 public universe |\n| Run paper-style public validation | [AkShare CSI 300 Daily 213-Factor Report](docs/validation_akshare_csi300_full_pipeline_20260729.md) | Daily 213-factor public-data approximation with turnover control |\n| Contribute one run | [Reproduction report form](https://github.com/initial-d/ml-quant-trading/issues/new?template=reproduction_report.yml) | Run Colab, submit the generated report, and receive README credit |\n\n## Validation Dashboard\n\nLatest maintained public-data snapshot: [AkShare CSI 300 Daily 213-Factor Validation](docs/validation_dashboard.md).\nThe detailed dashboard includes cost-sensitivity charts, caveats, and reproduction commands.\n\n| Run | Universe | Frequency | Factor set | Main result at 7 bps effective cost |\n|---|---|---:|---:|---|\n| 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 |\n| Equal-weight baseline | Same panel | Daily | n/a | 17.75% ann. return, 0.882 Sharpe, 1.8744 final equity |\n| Naive daily factor selection | Same panel | Daily | 213 | Positive gross edge, but high turnover reduces net performance |\n\nThe dashboard is intentionally cost-aware: daily factor selection is evaluated\nwith turnover and transaction costs, not just gross returns. The run is a\npublic-data approximation, not an exact paper reproduction or investment claim.\n\nAcknowledgement: the AkShare zero-auth A-share data path was added through\ncontributor work from [@redamancy231-create](https://github.com/redamancy231-create)\nin [PR #42](https://github.com/initial-d/ml-quant-trading/pull/42).\n\n## Community Evidence\n\n| External contribution | What it added |\n|---|---|\n| [PR #18](https://github.com/initial-d/ml-quant-trading/pull/18) | ETF cross-asset public-data reproduction |\n| [PR #34](https://github.com/initial-d/ml-quant-trading/pull/34) | Windows/Baostock A-share validation on 25 stocks |\n| [PR #35](https://github.com/initial-d/ml-quant-trading/pull/35) | Neutralization and Baostock robustness fixes |\n| [PR #36](https://github.com/initial-d/ml-quant-trading/pull/36) | English handbook for all factor families |\n| [PR #42](https://github.com/initial-d/ml-quant-trading/pull/42) | Zero-account AkShare loader enabling CSI 300 validation |\n\nIndependent results are linked to their pull requests so the environment,\ncommands, limitations, and review history remain inspectable. Want to add\nanother machine or universe? [Run the zero-account Colab and submit the generated report](https://colab.research.google.com/github/initial-d/ml-quant-trading/blob/main/notebooks/quickstart_colab.ipynb).\n\nThis repository is validation-first: simple baselines, transaction costs,\npublic-data failure modes, and negative results are documented alongside the\nresearch pipeline.\n\n**Current calls for contributors**\n\n- Join the [August 2026 reproduction challenge](https://github.com/initial-d/ml-quant-trading/discussions/43): run Colab once, then use the [structured report form](https://github.com/initial-d/ml-quant-trading/issues/new?template=reproduction_report.yml), whether it succeeds or fails.\n- Try the [`v0.2.3` release](https://github.com/initial-d/ml-quant-trading/releases/tag/v0.2.3).\n- Read the [Research Card](docs/research_card.md) for intended use, current evidence, and non-goals.\n- Read the [public-data mini reproduction](docs/public_data_mini_reproduction.md).\n- Share benchmark or public-data results in [Discussions #13](https://github.com/initial-d/ml-quant-trading/discussions/13).\n- Pick up a newcomer task: [more benchmark reports](https://github.com/initial-d/ml-quant-trading/issues/7) or a [paired public-data validation or benchmark contribution](https://github.com/initial-d/ml-quant-trading/issues/22).\n- Read the [Reality Check and Validation Status](docs/reality_check.md) before interpreting any backtest as evidence of deployable alpha.\n\n\u003e **Research and educational use only.** This project is not investment\n\u003e advice and is not production-ready. Backtest results do not represent live\n\u003e trading performance; they depend on data quality, transaction costs,\n\u003e slippage, and modeling assumptions that differ from real markets. Treat all\n\u003e results as research validation, not verified out-of-sample performance\n\u003e claims. See [Reality Check](docs/reality_check.md) for known limitations.\n\n\u003cdetails\u003e\n\u003csummary\u003e中文说明\u003c/summary\u003e\n\n\u003e **仅用于研究和教学。** 本项目不构成投资建议，也不是可直接用于实盘交易的\n\u003e 生产系统。回测结果会受到数据质量、交易成本、滑点和建模假设影响，不代表\n\u003e 真实交易表现。请先阅读 [Reality Check](docs/reality_check.md) 中的限制说明。\n\n\u003c/details\u003e\n\n| Module | What it does |\n|--------|-------------|\n| `features.tensor_factors` | GPU-vectorised masked primitives (`rank`, `corr`, `ewma`, `ts_*`) |\n| `features.legacy_factors` | **204 hand-crafted alpha factors** ([English handbook](docs/factor_handbook_en.md) · [中文](docs/factor_handbook.md)) |\n| `features.alpha101` | Alpha101-style formulaic factors |\n| `features.neutralize` | Cross-sectional \u0026 industry neutralisation |\n| `features.bias` | Limit-up / limit-down / halt bias correction |\n| `training.augment` | GBM data augmentation |\n| `models.nets` | MLP / Transformer |\n| `models.losses` | AdjMSE, IC, RankIC losses |\n| `portfolio.markowitz` | Cross-sectional Markowitz (shrunk cov, no-short) |\n| `backtest.engine` | Vectorised backtest → Sharpe / IC / IR / DD |\n\n---\n\n## Why Star or Fork This Repository?\n\n- You want a runnable reference implementation for ML-enhanced multi-factor research.\n- You need a factor pipeline that handles masks, limit-up / limit-down events, halts, and cross-sectional operations.\n- You want to reproduce or extend the accompanying paper without rebuilding data, factor, model, portfolio, and backtest modules from scratch.\n- You are looking for a practical template for testing quantitative finance research code.\n\nIf you build on this work, please consider citing the paper and opening issues or pull requests for reproducibility notes, new examples, or benchmark results.\n\n---\n\n## Data Sources\n\n| Source | Market | Access | Notes |\n|--------|--------|--------|-------|\n| [AkShare](https://akshare.akfamily.xyz/) | A-shares | Public, no API key | Zero-auth loader backed by public upstream interfaces that may change or rate-limit |\n| [Baostock](http://baostock.com) | A-shares | Free registration | Supported A-share loader; requires account |\n| [yfinance](https://pypi.org/project/yfinance/) | US equities / ETFs | Public, rate-limited | Used for public-data validation and cross-market examples |\n| Synthetic | N/A | Zero-config | Deterministic GBM panel for smoke testing the pipeline |\n\nThe repository does not redistribute market data. AkShare, Baostock, and\nyfinance data are downloaded on-demand by the loader scripts. Public upstream\ninterfaces can change or rate-limit requests. Synthetic data is generated\ndeterministically from a fixed seed.\n\n## Quick Start\n\n```bash\ngit clone https://github.com/initial-d/ml-quant-trading.git\ncd ml-quant-trading\npip install -e .[dev]        # add ,gpu for CUDA; add ,mosek for MOSEK solver\n\n# One-command smoke test (synthetic data; no API key required)\nmlquant demo\n```\n\nThe command prints a stage-by-stage run and writes shareable\n`artifacts/small/summary.md` and `summary.json` reports alongside the model and\nbacktest artifacts. The demo is a deterministic engineering smoke test, not a\nperformance claim.\n\n### Google Colab Quick Start\n\nRun the deterministic end-to-end pipeline in Google Colab without a market-data\naccount or local setup:\n\n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/initial-d/ml-quant-trading/blob/main/notebooks/quickstart_colab.ipynb)\n\nThe account-based [Baostock A-share notebook](demo_baostock.ipynb) remains\navailable for users who want that data route.\n\n### Public-Data Factor IC Demo\n\nFor a lightweight public-data walkthrough, open [`notebooks/public_factor_ic.ipynb`](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.\n\nFor a larger public-data validation run with walk-forward baselines, costs,\nslippage, cost-sensitivity reports, optional bootstrap confidence intervals,\nturnover, drawdown, and equal-weight / momentum / Alpha101 / MLP / Transformer\ncomparisons:\n\n```bash\npython scripts/public_data_validation.py \\\n  --source yfinance \\\n  --preset us-large-100 \\\n  --max-tickers 100\n```\n\nSee [`docs/public_data_validation.md`](docs/public_data_validation.md). Treat\nthese runs as validation diagnostics, not trading recommendations. The script\nwrites `summary.md`, `summary.csv`, `summary.json`, `metadata.json`, and a\ncopy-ready `submission.md` for community reports. Add `--cost-grid-bps 0,7,15,30`\nto generate `cost_sensitivity.*` files, and add `--bootstrap-samples 500` to\ninclude return and Sharpe uncertainty intervals. Maintainers can aggregate\nmultiple `summary.json` files with `scripts/aggregate_validation_reports.py` and\naudit individual reports with `scripts/audit_validation_report.py`.\n\n### Tensor Factor Benchmark\n\nTo benchmark core tensor primitives and a small factor subset on CPU/GPU, run:\n\n```bash\nmake benchmark\n```\n\nSee [`docs/benchmarking.md`](docs/benchmarking.md) for larger-panel commands and reporting guidance.\nBenchmark reports from different machines are welcome through the\n[`Benchmark result`](.github/ISSUE_TEMPLATE/benchmark_result.yml) issue template.\n\n### Reproducible Dev Environment\n\nFor a Docker-based CPU environment:\n\n```bash\ndocker build -t ml-quant-trading .\ndocker run --rm ml-quant-trading make test\n```\n\nSee [`docs/docker.md`](docs/docker.md) for Docker benchmark, synthetic pipeline,\nand public-data validation commands.\n\nFor VS Code or GitHub Codespaces, use the included Dev Container:\n\n```text\n.devcontainer/devcontainer.json\n```\n\nIt installs Python 3.11 and the project with `pip install -e .[dev]`.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eMaintainer, launch, and community resources\u003c/b\u003e\u003c/summary\u003e\n\n- [`CHANGELOG.md`](CHANGELOG.md) summarizes the public baseline release.\n- [`docs/launch_playbook.md`](docs/launch_playbook.md) contains the launch checklist,\n  recommended repository topics, and social preview guidance.\n- [`docs/start_here.md`](docs/start_here.md) gives new users a fast path through the project.\n- [`docs/research_card.md`](docs/research_card.md) summarizes intended use, validation status, data assumptions, and known risks.\n- [`docs/architecture.md`](docs/architecture.md) shows the factor → model → portfolio → backtest pipeline.\n- [`docs/reality_check.md`](docs/reality_check.md) explains what is real, what is still a smoke test, and what is not claimed.\n- [`docs/faq.md`](docs/faq.md) answers common setup, data, and reproducibility questions.\n- [`docs/docker.md`](docs/docker.md) documents the Docker and Dev Container setup.\n- [`docs/benchmark_board.md`](docs/benchmark_board.md) tracks community benchmark reports.\n- [`docs/public_data_mini_reproduction.md`](docs/public_data_mini_reproduction.md) records a small yfinance factor IC reproduction.\n- [`docs/public_data_validation.md`](docs/public_data_validation.md) documents larger public-data walk-forward validation runs.\n- [`docs/validation_akshare_csi300_20260729.md`](docs/validation_akshare_csi300_20260729.md) records the AkShare CSI 300 public A-share validation run for `v0.2.2`.\n- [`docs/validation_akshare_csi300_full_pipeline_20260729.md`](docs/validation_akshare_csi300_full_pipeline_20260729.md) records the daily 213-factor AkShare CSI 300 public-data approximation.\n- [`docs/validation_digest_20260727.md`](docs/validation_digest_20260727.md) summarizes the current public validation and discovery surface for `v0.2.1`.\n- [`docs/community.md`](docs/community.md) explains contribution lanes and maintainer response rules.\n- [`docs/release_draft_v0.1.0.md`](docs/release_draft_v0.1.0.md) is a copy-ready first release draft.\n- [`docs/release_draft_v0.2.0.md`](docs/release_draft_v0.2.0.md) is the public validation and contributor-workflow release draft.\n- [`docs/release_draft_v0.2.1.md`](docs/release_draft_v0.2.1.md) is the validation entrypoint and outreach follow-through release draft.\n- [`docs/release_draft_v0.2.2.md`](docs/release_draft_v0.2.2.md) is the AkShare public A-share validation release draft.\n- [`docs/promotion_kit.md`](docs/promotion_kit.md) contains copy-ready social and community posts.\n- [`docs/article_zh_213_factor_csi300.md`](docs/article_zh_213_factor_csi300.md) is the\n  long-form Chinese technical launch article.\n- [`docs/community_posts_zh.md`](docs/community_posts_zh.md) adapts the article for\n  Zhihu, Juejin, V2EX, JoinQuant, and Ricequant.\n- [`docs/community_outreach.md`](docs/community_outreach.md) lists target communities and copy-ready outreach posts.\n- [`docs/content_calendar.md`](docs/content_calendar.md) turns real updates into a four-week launch rhythm.\n- [`docs/visibility_status.md`](docs/visibility_status.md) tracks live launch links, contributor calls, and next outreach steps.\n- [`v0.1.0`](https://github.com/initial-d/ml-quant-trading/releases/tag/v0.1.0) is the first public research baseline release.\n- [`v0.2.0`](https://github.com/initial-d/ml-quant-trading/releases/tag/v0.2.0) is the public validation and contributor-workflow release.\n- [`v0.2.1`](https://github.com/initial-d/ml-quant-trading/releases/tag/v0.2.1) is the validation entrypoint and outreach follow-through release.\n- [`v0.2.2`](https://github.com/initial-d/ml-quant-trading/releases/tag/v0.2.2) is the AkShare public A-share validation release.\n- [Benchmark and reproduction discussion](https://github.com/initial-d/ml-quant-trading/discussions/13) is open for community reports.\n\n\u003c/details\u003e\n\n---\n\n## Factor Library (213 factors: 9 Alpha101 + 204 legacy)\n\nThe 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])`.\n\n📖 **Factor Handbook:** [English](docs/factor_handbook_en.md) · [中文](docs/factor_handbook.md) — design notes and implementation rationale for each factor.\n\n| Family | Count | Description |\n|--------|-------|-------------|\n| `better_001` – `better_028` | 28 | VWAP deviation + volume-weighted momentum |\n| `best_001` – `best_021` | 21 | Close-location momentum variants |\n| `old_027` – `old_076` | 50 | Classic alpha signals (corr/rank composites) |\n| `stock_001` – `stock_022` | 22 | Per-stock derived series (volume, range, price) |\n| `extra_001` – `extra_014` | 14 | Turnover + amount features |\n| `add_001` – `add_030` | 30 | Additional composite factors |\n| `change_001` – `change_005` | 5 | Short-window change-of-velocity |\n| `original_001` – `original_028` | 28 | Close/volume direct statistics |\n| `cs_rank_*` | 6 | Market breadth (cross-sectional rank signals) |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eFull factor list (click to expand)\u003c/b\u003e\u003c/summary\u003e\n\n```\nadd_001    add_002    add_003    add_004    add_005    add_006\nadd_007    add_008    add_009    add_010    add_011    add_012\nadd_013    add_014    add_015    add_016    add_017    add_018\nadd_019    add_020    add_021    add_022    add_023    add_024\nadd_025    add_026    add_027    add_028    add_029    add_030\nbest_001   best_002   best_003   best_004   best_005   best_006\nbest_007   best_008   best_009   best_010   best_011   best_012\nbest_013   best_014   best_015   best_016   best_017   best_018\nbest_019   best_020   best_021\nchange_001 change_002 change_003 change_004 change_005\nextra_001  extra_002  extra_003  extra_004  extra_005  extra_006\nextra_007  extra_008  extra_009  extra_010  extra_011  extra_012\nextra_013  extra_014\nold_027    old_028    old_029    old_030    old_031    old_032\nold_033    old_034    old_035    old_036    old_037    old_038\nold_039    old_040    old_041    old_042    old_043    old_044\nold_045    old_046    old_047    old_048    old_049    old_050\nold_051    old_052    old_053    old_054    old_055    old_056\nold_057    old_058    old_059    old_060    old_061    old_062\nold_063    old_064    old_065    old_066    old_067    old_068\nold_069    old_070    old_071    old_072    old_073    old_074\nold_075    old_076\noriginal_001 original_002 original_003 original_004 original_005\noriginal_006 original_007 original_008 original_009 original_010\noriginal_011 original_012 original_013 original_014 original_015\noriginal_016 original_017 original_018 original_019 original_020\noriginal_021 original_022 original_023 original_024 original_025\noriginal_026 original_027 original_028\nstock_001  stock_002  stock_003  stock_004  stock_005  stock_006\nstock_007  stock_008  stock_009  stock_010  stock_011  stock_012\nstock_013  stock_014  stock_015  stock_016  stock_017  stock_018\nstock_019  stock_020  stock_021  stock_022\n```\n\n\u003c/details\u003e\n\n### Data Sources\n\nYou can directly fetch stock data from Yahoo Finance, Baostock, or AkShare.\n\n**yfinance:**\n```python\nfrom mlquant.data import make_panel\n\npanel = make_panel(\n    source=\"yfinance\",\n    tickers=[\"000001.SZ\", \"600000.SS\"],\n    start=\"2020-01-01\",\n    end=\"2023-12-31\"\n)\n```\n\n**baostock:**\n```python\nfrom mlquant.data import make_panel\n\npanel = make_panel(\n    source=\"baostock\",\n    tickers=[\"sh.600000\", \"sz.000001\"],\n    start=\"2020-01-01\",\n    end=\"2023-12-31\"\n)\n```\n\n**AkShare (A-shares, no API key):**\n```python\nfrom mlquant.data import make_panel\n\npanel = make_panel(\n    source=\"akshare\",\n    tickers=[\"600519\", \"000001\"],\n    start=\"2020-01-01\",\n    end=\"2023-12-31\",\n    adjust=\"qfq\",\n)\n```\n\nAkShare uses public upstream interfaces, so availability, schemas, and rate\nlimits can change independently of this project.\n\n### Usage\n\n```python\nfrom mlquant.features import compute_legacy_set, LEGACY_REGISTRY\n\n# Compute all 213 factors (204 legacy + 9 Alpha101)\nfactors, mask, names = compute_legacy_set(panel)  # → [T, N, 213]\n\n# Or a subset\nfactors, mask, names = compute_legacy_set(panel, names=(\"best_001\", \"add_015\", \"old_042\"))\n```\n\n---\n\n## Architecture\n\n```mermaid\nflowchart LR\n    subgraph Data[\"1. Data\"]\n        A[Raw OHLCV] --\u003e B[loaders\u003cbr/\u003esynthetic / yfinance / baostock / akshare]\n    end\n    subgraph Features[\"2. Features\"]\n        B --\u003e C[tensor_factors\u003cbr/\u003eGPU masked primitives]\n        C --\u003e D[bias\u003cbr/\u003elimit-up/down/halt correction]\n        D --\u003e E[compute_legacy_set\u003cbr/\u003e213-factor tensor\u003cbr/\u003e204 legacy + 9 Alpha101]\n    end\n    subgraph Training[\"3. Training\"]\n        E --\u003e F[FactorDataset\u003cbr/\u003eforward returns + masks]\n        F --\u003e G[MLP Regressor]\n        F -.-\u003e|optional| GBM[GBM augment]\n        G -.-\u003e|alternative| T[Transformer]\n        G --\u003e H[losses\u003cbr/\u003eAdjMSE / IC / RankIC]\n    end\n    subgraph Portfolio[\"4. Portfolio\"]\n        H --\u003e I[Markowitz\u003cbr/\u003eLedoit-Wolf shrunk cov\u003cbr/\u003eno-short constraint]\n    end\n    subgraph Backtest[\"5. Backtest\"]\n        I --\u003e J[engine\u003cbr/\u003evectorized backtest]\n        J --\u003e K[Sharpe / IC / IR / DD]\n    end\n```\n\n\u003e Solid = required in default pipeline. Dashed = optional / alternative module (not called by CLI).\n\n---\n\n## Project Layout\n\n```\nml-quant-trading/\n├── src/mlquant/\n│   ├── data/           # Panel dataclass, loaders, synthetic generator\n│   ├── features/       # Factor engine + 204 legacy + Alpha101\n│   ├── training/       # Dataset, augmentation, trainer\n│   ├── models/         # MLP, Transformer, losses\n│   ├── portfolio/      # Markowitz, frontier sweep\n│   ├── backtest/       # Engine, metrics\n│   └── cli/            # Command-line interface\n├── configs/            # small.yaml (smoke) / paper.yaml (full)\n├── tests/              # pytest suite\n├── scripts/            # IC eval, frontier plot\n├── legacy/             # Original research scripts (archival, unsupported)\n└── docs/               # Architecture, factor docs, paper reproduction\n```\n\n---\n\n## Reproducing the Paper\n\nSee [`docs/reproducing_paper.md`](docs/reproducing_paper.md) for table-by-table mapping.\n\n| Paper section | Code module | Tests |\n|---|---|---|\n| §3.1 Tensor factor engine | `features.tensor_factors` | `test_tensor_factors` |\n| §3.2 Alpha + microstructure factors | `features.alpha101`, `features.legacy_factors` | `test_alpha101` |\n| §3.3 Neutralisation | `features.neutralize` | — |\n| §3.4 Bias correction | `features.bias` | `test_bias` |\n| §4.1 GBM augmentation | `training.augment` | `test_augment` |\n| §4.2 ML models | `models.nets`, `models.losses` | `test_losses` |\n| §5 Portfolio optimisation | `portfolio.markowitz` | `test_markowitz` |\n| §6 Backtest | `backtest.engine`, `backtest.metrics` | `test_metrics` |\n\n---\n\n## Roadmap\n\nSee [`docs/roadmap.md`](docs/roadmap.md) for contributor-friendly tasks, research extensions,\nengineering extensions, and community milestones.\n\nFor announcements, release posts, and benchmark calls, see the\n[`Promotion Kit`](docs/promotion_kit.md). For the maintainer growth loop, see\n[`docs/growth_plan.md`](docs/growth_plan.md).\n\n## Contributing\n\nContributions are welcome, especially docs, reproducibility notes, tests, data adapters, and small examples. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for setup and pull request guidance.\n\n## Disclaimer\n\nThis 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.\n\n---\n\n## Citation\n\n```bibtex\n@article{du2025mlquant,\n  title  = {Machine Learning Enhanced Multi-Factor Quantitative Trading:\n            A Cross-Sectional Portfolio Optimization Approach with Bias Correction},\n  author = {Du, Yimin},\n  journal= {arXiv preprint arXiv:2507.07107},\n  year   = {2025},\n  url    = {https://arxiv.org/abs/2507.07107}\n}\n```\n\n## License\n\nMIT — see [`LICENSE`](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finitial-d%2Fml-quant-trading","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finitial-d%2Fml-quant-trading","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finitial-d%2Fml-quant-trading/lists"}