msd-backtest 0.2.0__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (113) hide show
  1. {msd_backtest-0.2.0/msd_backtest.egg-info → msd_backtest-0.3.0}/PKG-INFO +50 -17
  2. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/README.md +48 -15
  3. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/__init__.py +5 -0
  4. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/account.py +100 -21
  5. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/data_provider.py +82 -1
  6. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/doctor.py +1 -1
  7. msd_backtest-0.3.0/mbt/factor/__init__.py +77 -0
  8. msd_backtest-0.3.0/mbt/factor/__main__.py +11 -0
  9. msd_backtest-0.3.0/mbt/factor/cli.py +409 -0
  10. msd_backtest-0.3.0/mbt/factor/evaluator.py +609 -0
  11. msd_backtest-0.3.0/mbt/factor/expr.py +846 -0
  12. msd_backtest-0.3.0/mbt/factor/factor.py +595 -0
  13. msd_backtest-0.3.0/mbt/factor/metrics.py +791 -0
  14. msd_backtest-0.3.0/mbt/factor/overview.py +361 -0
  15. msd_backtest-0.3.0/mbt/factor/preprocess.py +307 -0
  16. msd_backtest-0.3.0/mbt/factor/report.py +476 -0
  17. msd_backtest-0.3.0/mbt/factor/returns.py +250 -0
  18. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/gui/app.py +1 -1
  19. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/gui/chart.py +3 -3
  20. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/gui/dialogs.py +11 -7
  21. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/gui/inspect_strategy.py +3 -1
  22. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/gui/views.py +5 -2
  23. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/portfolio.py +452 -130
  24. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/run/backend.py +18 -1
  25. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/run/cli.py +128 -72
  26. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/run/msd.py +56 -36
  27. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/run/overview.py +12 -12
  28. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/run/report.py +56 -41
  29. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/run/runner.py +277 -67
  30. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/select/msd.py +45 -31
  31. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/select/panel.py +56 -37
  32. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/shared/__init__.py +2 -0
  33. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/shared/financial.py +2 -2
  34. msd_backtest-0.3.0/mbt/shared/stocks.py +690 -0
  35. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/strategy.py +26 -2
  36. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/strategy_templates/cta_momentum.py +76 -51
  37. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/strategy_templates/fundamental_timing.py +99 -70
  38. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/strategy_templates/multifactor_rotation.py +2 -1
  39. {msd_backtest-0.2.0 → msd_backtest-0.3.0/msd_backtest.egg-info}/PKG-INFO +50 -17
  40. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/msd_backtest.egg-info/SOURCES.txt +18 -0
  41. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/msd_backtest.egg-info/requires.txt +1 -1
  42. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/pyproject.toml +2 -2
  43. msd_backtest-0.3.0/tests/test_factor_cli_and_report.py +165 -0
  44. msd_backtest-0.3.0/tests/test_factor_contract.py +156 -0
  45. msd_backtest-0.3.0/tests/test_factor_expr.py +174 -0
  46. msd_backtest-0.3.0/tests/test_factor_metrics.py +261 -0
  47. msd_backtest-0.3.0/tests/test_factor_preprocess.py +146 -0
  48. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_feedback_fixes.py +74 -0
  49. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_panel_resample.py +32 -0
  50. msd_backtest-0.3.0/tests/test_performance_optimizations.py +189 -0
  51. msd_backtest-0.3.0/tests/test_stocks.py +192 -0
  52. msd_backtest-0.3.0/tests/test_stocks_industry_map.py +128 -0
  53. msd_backtest-0.2.0/mbt/shared/stocks.py +0 -401
  54. msd_backtest-0.2.0/tests/test_stocks.py +0 -132
  55. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/LICENSE +0 -0
  56. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/gui/__init__.py +0 -0
  57. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/gui/__main__.py +0 -0
  58. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/gui/config.py +0 -0
  59. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/gui/downsample.py +0 -0
  60. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/gui/dpi.py +0 -0
  61. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/gui/worker.py +0 -0
  62. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/notify.py +0 -0
  63. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/run/__init__.py +0 -0
  64. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/run/review.py +0 -0
  65. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/run/server.py +0 -0
  66. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/run/validator.py +0 -0
  67. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/select/__init__.py +0 -0
  68. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/select/cli.py +0 -0
  69. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/select/selector.py +0 -0
  70. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/mbt/strategy_templates/__init__.py +0 -0
  71. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/msd_backtest.egg-info/dependency_links.txt +0 -0
  72. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/msd_backtest.egg-info/top_level.txt +0 -0
  73. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/setup.cfg +0 -0
  74. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_account.py +0 -0
  75. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_agent_first.py +0 -0
  76. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_alpha.py +0 -0
  77. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_benchmark_decouple.py +0 -0
  78. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_cli_smoke.py +0 -0
  79. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_dreman_strategy.py +0 -0
  80. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_fee.py +0 -0
  81. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_financial_lag.py +0 -0
  82. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_fix_phase1.py +0 -0
  83. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_fix_phase2.py +0 -0
  84. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_fix_phase3.py +0 -0
  85. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_gui.py +0 -0
  86. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_holding_ror_grid.py +0 -0
  87. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_load_strategy.py +0 -0
  88. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_mdate.py +0 -0
  89. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_msd_setup.py +0 -0
  90. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_multi_start_and_holdout.py +0 -0
  91. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_notify.py +0 -0
  92. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_overview.py +0 -0
  93. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_panel_zero_copy.py +0 -0
  94. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_portfolio.py +0 -0
  95. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_position_computed_properties.py +0 -0
  96. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_position_cost_and_ror.py +0 -0
  97. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_raw_prices.py +0 -0
  98. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_rebalance_sell_conflict.py +0 -0
  99. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_report.py +0 -0
  100. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_run_cli_selector.py +0 -0
  101. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_run_msd.py +0 -0
  102. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_runner.py +0 -0
  103. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_runner_fast_path.py +0 -0
  104. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_select_financial.py +0 -0
  105. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_selector.py +0 -0
  106. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_selector_contract.py +0 -0
  107. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_selector_financial.py +0 -0
  108. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_strategy.py +0 -0
  109. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_strategy_finalize.py +0 -0
  110. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_strategy_loading_complex.py +0 -0
  111. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_strategy_templates.py +0 -0
  112. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_volume_breakout_monthly_yang_selector.py +0 -0
  113. {msd_backtest-0.2.0 → msd_backtest-0.3.0}/tests/test_warmup_bars.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: msd-backtest
3
- Version: 0.2.0
3
+ Version: 0.3.0
4
4
  Summary: MSD backtest framework
5
5
  License-Expression: BSD-2-Clause
6
6
  Requires-Python: >=3.12
@@ -8,7 +8,7 @@ Description-Content-Type: text/markdown
8
8
  License-File: LICENSE
9
9
  Requires-Dist: numpy>=2.4.2
10
10
  Provides-Extra: alpha
11
- Requires-Dist: py-alpha-lib>=0.4; extra == "alpha"
11
+ Requires-Dist: py-alpha-lib>=0.5; extra == "alpha"
12
12
  Provides-Extra: msd
13
13
  Requires-Dist: pymsd>=0.1; extra == "msd"
14
14
  Requires-Dist: polars>=1.0.0; extra == "msd"
@@ -29,7 +29,7 @@ Dynamic: license-file
29
29
 
30
30
  # 简介
31
31
 
32
- `msd-backtest` 是一个基于 Python 的, Agent First 的高性能、向量化量化投研与回测框架。框架深度融合 [MSD (Market Strategy Data)](.agents/skills/msd-strategy-guide/references/msd.md) 数据服务与 [py-alpha-lib](.agents/skills/msd-strategy-guide/references/algo.md) 并行算法库,全面支持**横截面选股(Selector)**、**单标的独立交易策略(Trading Strategy)**以及**多标的多资产组合配置与动态调仓策略(Portfolio Strategy)**。
32
+ `msd-backtest` 是一个基于 Python 的, Agent First 的高性能、向量化量化投研与回测框架。框架深度融合 [MSD (Market Strategy Data)](.agents/skills/msd-strategy-guide/references/msd.md) 数据服务与 [py-alpha-lib](.agents/skills/msd-strategy-guide/references/algo.md) 并行算法库,全面支持**因子研究与评估(Factor)**、**横截面选股(Selector)**、**单标的独立交易策略(Trading Strategy)**以及**多标的多资产组合配置与动态调仓策略(Portfolio Strategy)**。
33
33
 
34
34
 
35
35
  ## 实测性能
@@ -57,11 +57,15 @@ npx skills add msd-rs/msd-backtest
57
57
 
58
58
  然后, 告知它你的想要的策略逻辑即可. 如果你的 LLM 支持识图, 你甚至可以将贴给它, *复刻你平常看到的策略时最方便*
59
59
 
60
+ ---
60
61
 
61
- # Hand Write 的说明
62
+ > **以下内容仅供人类参考阅读, AI Agent 可以通过上述的 Skill 完成所有工作. 包括数据环境搭建和策略编写**
62
63
 
63
64
  ---
64
65
 
66
+ # Hand Write 的说明
67
+
68
+
65
69
  ## 📖 极佳的代码自解释性与 Pydoc 支持
66
70
 
67
71
  > [!TIP]
@@ -80,6 +84,10 @@ npx skills add msd-rs/msd-backtest
80
84
  # 查看选股器与数据提供者(包含矩阵布局契约与字段语义)
81
85
  uv run python -m pydoc mbt.select.SelectorDataProvider
82
86
  uv run python -m pydoc mbt.select.Panel
87
+
88
+ # 查看因子评估子系统与表达式算子契约
89
+ uv run python -m pydoc mbt.factor
90
+ uv run python -m mbt.factor --list-ops
83
91
  ```
84
92
  - **启动本地 Web 文档服务器:**
85
93
  ```bash
@@ -93,7 +101,8 @@ npx skills add msd-rs/msd-backtest
93
101
 
94
102
  ## 🌟 核心特性
95
103
 
96
- - **三位一体的策略架构**:
104
+ - **四位一体的量化投研架构**:
105
+ - **因子评估(`mbt.factor` / `mbt.Factor` / `mbt.ExpressionFactor`)**:支持 Python 向量化因子类与 `alpha.lang` 公式表达式(WorldQuant BRAIN 规范 + WQ101/GTJA191 方言兼容),内置动态因果性探针(防未来函数)、MAD/行业市值中性化、IC/RankIC(Newey-West t 检验)、Tranche 分层净值、样本外验证与中文高 DPI 全景报告图。
97
106
  - **选股策略(`mbt.Selector`)**:多阶段漏斗式选股(`stepXX`),基于 `Panel` 二维矩阵与 Polars 进行高效率横截面因子筛选,无缝对齐财务指标与快照数据。
98
107
  - **交易策略(`mbt.Strategy`)**:单标的独立账户机制,用于细粒度验证个股时间序列上的择时信号与买卖点逻辑。
99
108
  - **组合策略(`mbt.PortfolioStrategy`)**:多标的共享单一现金池(`PortfolioAccount`),内置权重调仓(`ctx.rebalance`)、两阶段撮合(先卖后买)、交易限额、停牌与涨跌停约束。
@@ -123,20 +132,15 @@ npx skills add msd-rs/msd-backtest
123
132
  推荐使用现代 Python 包管理器 `uv`(要求 Python 3.12+):
124
133
 
125
134
  ```bash
126
- # 克隆仓库
127
- git clone https://github.com/msd-rs/msd-backtest.git
128
- cd msd-backtest
129
-
130
- # 安装核心及 CLI 依赖
131
- uv sync --with cli
132
-
133
- # 若需启动远程回测服务器(可选)
134
- uv sync --with server
135
+ # use uv
136
+ uv add "msd-backtest[cli]"
137
+ # or use pip
138
+ pip install "msd-backtest[cli]"
135
139
  ```
136
140
 
137
141
  ### 2. 环境配置
138
142
 
139
- 在项目根目录下创建或编辑 `.env` 文件,配置 MSD 数据库地址与费率规则:
143
+ 在项目根目录下创建或编辑 `.env` 文件,配置 MSD 数据库地址:
140
144
 
141
145
  ```env
142
146
  # MSD 服务端地址(必须)
@@ -145,8 +149,8 @@ MSD_HOST=http://localhost:50510
145
149
  # 基准指数代码(可选,默认为上证指数 SH000001)
146
150
  MSD_BT_BENCHMARK=SH000001
147
151
 
148
- # 手续费配置文件(可选,未指定时默认使用 etc/fee.json 标准印花税与佣金)
149
- # MSD_BT_FEE=etc/fee.json
152
+ # 手续费配置文件(可选,未指定时默认使用如 etc/fee.json 标准印花税与佣金)
153
+ MSD_BT_FEE=etc/fee.json
150
154
  ```
151
155
 
152
156
  ---
@@ -359,6 +363,25 @@ uv run python -m mbt.run.cli strategy/my_strategy.py -s SH600000 -b 2023-01-01 -
359
363
 
360
364
 
361
365
 
366
+ ### 运行因子评估 (`mbt.factor` / `mbt.factor.cli`)
367
+
368
+ ```bash
369
+ # 1. 查看规范表达式算子、WQ101/GTJA191 方言别名与数据字段
370
+ uv run python -m mbt.factor --list-ops
371
+
372
+ # 2. 评估 Python 因子文件(支持多因子族、行业市值中性化、样本外 Holdout 与中文全景图)
373
+ uv run python -m mbt.factor strategy/demo_factor.py \
374
+ -s A_STOCKS_EXCLUDE_ST -b 2022-01-01 -e 2025-12-31 \
375
+ --winsorize mad --neutralize industry,mktcap --holdout 2025-01-01 \
376
+ -S --overview factor_overview.png -o factor_report.json
377
+
378
+ # 3. 直接评估内联因子表达式(支持重复传入 -E 自动输出排行榜与相关性矩阵)
379
+ uv run python -m mbt.factor \
380
+ -E 'bp=f003 / raw_close' \
381
+ -E 'wq7=((adv20 < volume) ? ((-1 * ts_rank(abs(delta(close, 7)), 60)) * sign(delta(close, 7))) : -1)' \
382
+ -s A_STOCKS_EXCLUDE_ST -b 2023-01-01 -e 2025-12-31 -S
383
+ ```
384
+
362
385
  ---
363
386
 
364
387
  ## 📂 项目结构
@@ -370,6 +393,16 @@ uv run python -m mbt.run.cli strategy/my_strategy.py -s SH600000 -b 2023-01-01 -
370
393
  │ ├── portfolio.py # 共享资金组合账户、调仓撮合与多资产上下文
371
394
  │ ├── strategy.py # 策略基类(Strategy, PortfolioStrategy)与 Context
372
395
  │ ├── data_provider.py # 数据源抽象接口
396
+ │ ├── factor/ # 因子评估子系统
397
+ │ │ ├── factor.py # Factor 基类、AST 检查与动态因果性探针
398
+ │ │ ├── expr.py # alpha.lang 表达式编译、ExpressionFactor 与 PanelExecContext
399
+ │ │ ├── returns.py # 前瞻总收益与停牌/涨跌停可交易性掩码
400
+ │ │ ├── preprocess.py # 截面去极值、标准化与行业/市值中性化
401
+ │ │ ├── metrics.py # IC/RankIC、Tranche 分层收益、换手衰减、Holdout 与相关性矩阵
402
+ │ │ ├── evaluator.py # 因子评估编排引擎(evaluate_panel / evaluate_factor)
403
+ │ │ ├── report.py # Markdown / JSON / CSV / XLSX 报告导出
404
+ │ │ ├── overview.py # 中文高 DPI 因子评估全景图渲染器
405
+ │ │ └── cli.py # 因子评估命令行工具
373
406
  │ ├── select/ # 选股器模块
374
407
  │ │ ├── selector.py # Selector 基类与静态选股器
375
408
  │ │ ├── panel.py # 2D Panel 矩阵视图与向量化算子计算
@@ -1,6 +1,6 @@
1
1
  # 简介
2
2
 
3
- `msd-backtest` 是一个基于 Python 的, Agent First 的高性能、向量化量化投研与回测框架。框架深度融合 [MSD (Market Strategy Data)](.agents/skills/msd-strategy-guide/references/msd.md) 数据服务与 [py-alpha-lib](.agents/skills/msd-strategy-guide/references/algo.md) 并行算法库,全面支持**横截面选股(Selector)**、**单标的独立交易策略(Trading Strategy)**以及**多标的多资产组合配置与动态调仓策略(Portfolio Strategy)**。
3
+ `msd-backtest` 是一个基于 Python 的, Agent First 的高性能、向量化量化投研与回测框架。框架深度融合 [MSD (Market Strategy Data)](.agents/skills/msd-strategy-guide/references/msd.md) 数据服务与 [py-alpha-lib](.agents/skills/msd-strategy-guide/references/algo.md) 并行算法库,全面支持**因子研究与评估(Factor)**、**横截面选股(Selector)**、**单标的独立交易策略(Trading Strategy)**以及**多标的多资产组合配置与动态调仓策略(Portfolio Strategy)**。
4
4
 
5
5
 
6
6
  ## 实测性能
@@ -28,11 +28,15 @@ npx skills add msd-rs/msd-backtest
28
28
 
29
29
  然后, 告知它你的想要的策略逻辑即可. 如果你的 LLM 支持识图, 你甚至可以将贴给它, *复刻你平常看到的策略时最方便*
30
30
 
31
+ ---
31
32
 
32
- # Hand Write 的说明
33
+ > **以下内容仅供人类参考阅读, AI Agent 可以通过上述的 Skill 完成所有工作. 包括数据环境搭建和策略编写**
33
34
 
34
35
  ---
35
36
 
37
+ # Hand Write 的说明
38
+
39
+
36
40
  ## 📖 极佳的代码自解释性与 Pydoc 支持
37
41
 
38
42
  > [!TIP]
@@ -51,6 +55,10 @@ npx skills add msd-rs/msd-backtest
51
55
  # 查看选股器与数据提供者(包含矩阵布局契约与字段语义)
52
56
  uv run python -m pydoc mbt.select.SelectorDataProvider
53
57
  uv run python -m pydoc mbt.select.Panel
58
+
59
+ # 查看因子评估子系统与表达式算子契约
60
+ uv run python -m pydoc mbt.factor
61
+ uv run python -m mbt.factor --list-ops
54
62
  ```
55
63
  - **启动本地 Web 文档服务器:**
56
64
  ```bash
@@ -64,7 +72,8 @@ npx skills add msd-rs/msd-backtest
64
72
 
65
73
  ## 🌟 核心特性
66
74
 
67
- - **三位一体的策略架构**:
75
+ - **四位一体的量化投研架构**:
76
+ - **因子评估(`mbt.factor` / `mbt.Factor` / `mbt.ExpressionFactor`)**:支持 Python 向量化因子类与 `alpha.lang` 公式表达式(WorldQuant BRAIN 规范 + WQ101/GTJA191 方言兼容),内置动态因果性探针(防未来函数)、MAD/行业市值中性化、IC/RankIC(Newey-West t 检验)、Tranche 分层净值、样本外验证与中文高 DPI 全景报告图。
68
77
  - **选股策略(`mbt.Selector`)**:多阶段漏斗式选股(`stepXX`),基于 `Panel` 二维矩阵与 Polars 进行高效率横截面因子筛选,无缝对齐财务指标与快照数据。
69
78
  - **交易策略(`mbt.Strategy`)**:单标的独立账户机制,用于细粒度验证个股时间序列上的择时信号与买卖点逻辑。
70
79
  - **组合策略(`mbt.PortfolioStrategy`)**:多标的共享单一现金池(`PortfolioAccount`),内置权重调仓(`ctx.rebalance`)、两阶段撮合(先卖后买)、交易限额、停牌与涨跌停约束。
@@ -94,20 +103,15 @@ npx skills add msd-rs/msd-backtest
94
103
  推荐使用现代 Python 包管理器 `uv`(要求 Python 3.12+):
95
104
 
96
105
  ```bash
97
- # 克隆仓库
98
- git clone https://github.com/msd-rs/msd-backtest.git
99
- cd msd-backtest
100
-
101
- # 安装核心及 CLI 依赖
102
- uv sync --with cli
103
-
104
- # 若需启动远程回测服务器(可选)
105
- uv sync --with server
106
+ # use uv
107
+ uv add "msd-backtest[cli]"
108
+ # or use pip
109
+ pip install "msd-backtest[cli]"
106
110
  ```
107
111
 
108
112
  ### 2. 环境配置
109
113
 
110
- 在项目根目录下创建或编辑 `.env` 文件,配置 MSD 数据库地址与费率规则:
114
+ 在项目根目录下创建或编辑 `.env` 文件,配置 MSD 数据库地址:
111
115
 
112
116
  ```env
113
117
  # MSD 服务端地址(必须)
@@ -116,8 +120,8 @@ MSD_HOST=http://localhost:50510
116
120
  # 基准指数代码(可选,默认为上证指数 SH000001)
117
121
  MSD_BT_BENCHMARK=SH000001
118
122
 
119
- # 手续费配置文件(可选,未指定时默认使用 etc/fee.json 标准印花税与佣金)
120
- # MSD_BT_FEE=etc/fee.json
123
+ # 手续费配置文件(可选,未指定时默认使用如 etc/fee.json 标准印花税与佣金)
124
+ MSD_BT_FEE=etc/fee.json
121
125
  ```
122
126
 
123
127
  ---
@@ -330,6 +334,25 @@ uv run python -m mbt.run.cli strategy/my_strategy.py -s SH600000 -b 2023-01-01 -
330
334
 
331
335
 
332
336
 
337
+ ### 运行因子评估 (`mbt.factor` / `mbt.factor.cli`)
338
+
339
+ ```bash
340
+ # 1. 查看规范表达式算子、WQ101/GTJA191 方言别名与数据字段
341
+ uv run python -m mbt.factor --list-ops
342
+
343
+ # 2. 评估 Python 因子文件(支持多因子族、行业市值中性化、样本外 Holdout 与中文全景图)
344
+ uv run python -m mbt.factor strategy/demo_factor.py \
345
+ -s A_STOCKS_EXCLUDE_ST -b 2022-01-01 -e 2025-12-31 \
346
+ --winsorize mad --neutralize industry,mktcap --holdout 2025-01-01 \
347
+ -S --overview factor_overview.png -o factor_report.json
348
+
349
+ # 3. 直接评估内联因子表达式(支持重复传入 -E 自动输出排行榜与相关性矩阵)
350
+ uv run python -m mbt.factor \
351
+ -E 'bp=f003 / raw_close' \
352
+ -E 'wq7=((adv20 < volume) ? ((-1 * ts_rank(abs(delta(close, 7)), 60)) * sign(delta(close, 7))) : -1)' \
353
+ -s A_STOCKS_EXCLUDE_ST -b 2023-01-01 -e 2025-12-31 -S
354
+ ```
355
+
333
356
  ---
334
357
 
335
358
  ## 📂 项目结构
@@ -341,6 +364,16 @@ uv run python -m mbt.run.cli strategy/my_strategy.py -s SH600000 -b 2023-01-01 -
341
364
  │ ├── portfolio.py # 共享资金组合账户、调仓撮合与多资产上下文
342
365
  │ ├── strategy.py # 策略基类(Strategy, PortfolioStrategy)与 Context
343
366
  │ ├── data_provider.py # 数据源抽象接口
367
+ │ ├── factor/ # 因子评估子系统
368
+ │ │ ├── factor.py # Factor 基类、AST 检查与动态因果性探针
369
+ │ │ ├── expr.py # alpha.lang 表达式编译、ExpressionFactor 与 PanelExecContext
370
+ │ │ ├── returns.py # 前瞻总收益与停牌/涨跌停可交易性掩码
371
+ │ │ ├── preprocess.py # 截面去极值、标准化与行业/市值中性化
372
+ │ │ ├── metrics.py # IC/RankIC、Tranche 分层收益、换手衰减、Holdout 与相关性矩阵
373
+ │ │ ├── evaluator.py # 因子评估编排引擎(evaluate_panel / evaluate_factor)
374
+ │ │ ├── report.py # Markdown / JSON / CSV / XLSX 报告导出
375
+ │ │ ├── overview.py # 中文高 DPI 因子评估全景图渲染器
376
+ │ │ └── cli.py # 因子评估命令行工具
344
377
  │ ├── select/ # 选股器模块
345
378
  │ │ ├── selector.py # Selector 基类与静态选股器
346
379
  │ │ ├── panel.py # 2D Panel 矩阵视图与向量化算子计算
@@ -21,6 +21,8 @@ from .portfolio import (
21
21
  SelectorStrategy,
22
22
  )
23
23
  from . import strategy_templates
24
+ from . import factor
25
+ from .factor import Factor, ExpressionFactor
24
26
 
25
27
 
26
28
  __all__ = [
@@ -32,6 +34,8 @@ __all__ = [
32
34
  "Account",
33
35
  "Context",
34
36
  "DataProvider",
37
+ "ExpressionFactor",
38
+ "Factor",
35
39
  "Fee",
36
40
  "MsdSelectorDataProvider",
37
41
  "Operation",
@@ -47,5 +51,6 @@ __all__ = [
47
51
  "SelectorStrategy",
48
52
  "StaticSelector",
49
53
  "Strategy",
54
+ "factor",
50
55
  "strategy_templates",
51
56
  ]
@@ -357,15 +357,20 @@ class Fee:
357
357
  def build_fee_item(x):
358
358
  return FeeItem(**x)
359
359
 
360
+ self.config: list[FeeItem]
360
361
  if isinstance(config, list):
361
- if len(config) > 0 and isinstance(config[0], str):
362
- self.config = [json.loads(x, object_hook=build_fee_item) for x in config] # type: ignore
363
- self.config.sort(key=lambda x: x.ts)
364
- elif len(config) > 0 and isinstance(config[0], dict):
365
- self.config = [FeeItem(**x) for x in config] # type: ignore
366
- self.config.sort(key=lambda x: x.ts)
367
- else:
368
- self.config = list(config)
362
+ items: list[FeeItem] = []
363
+ for x in config:
364
+ if isinstance(x, FeeItem):
365
+ items.append(x)
366
+ elif isinstance(x, str):
367
+ items.append(json.loads(x, object_hook=build_fee_item))
368
+ elif isinstance(x, dict):
369
+ items.append(FeeItem(**x))
370
+ else:
371
+ raise TypeError(f"Unsupported fee config item type: {type(x).__name__}")
372
+ items.sort(key=lambda x: x.ts)
373
+ self.config = items
369
374
  elif isinstance(config, (str, Path)):
370
375
  p = Path(config)
371
376
 
@@ -588,6 +593,8 @@ class Account:
588
593
  fee: Fee | None = None,
589
594
  unit: int = 100,
590
595
  slippage: float = 0.0,
596
+ _dates_i64: np.ndarray | None = None,
597
+ _skip_fill: bool = False,
591
598
  ):
592
599
  """
593
600
  Args:
@@ -617,19 +624,25 @@ class Account:
617
624
  self.per_assets = 0.0
618
625
  """deducted commission and other fees"""
619
626
  self.deducted = 0.0
620
- """records of the account"""
621
- self.records = []
627
+ """records of the account (materialized lazily when backed by Rust trades)"""
628
+ self._records: list[Record] | None = []
629
+ self._raw_trades: tuple[dict[str, np.ndarray], int, int] | None = None
622
630
  """fee calculator"""
623
631
  self.fee = fee if fee is not None else Fee()
624
632
  """slippage of the buy and sell operations"""
625
633
  self.slippage = slippage
626
634
  """group index"""
627
635
  self.group = group
636
+ """execution mode ('close' or 'next_open')"""
637
+ self.exec_mode: str = "close"
628
638
 
629
639
  s = self.group * dp.bars
630
640
  e = s + dp.bars
631
641
  """dates of current group"""
632
- self.dates = dp.dates[s:e].astype('datetime64[s]').astype(int)
642
+ if _dates_i64 is not None:
643
+ self.dates = _dates_i64[s:e]
644
+ else:
645
+ self.dates = dp.dates[s:e].astype('datetime64[s]').astype(int)
633
646
  """history of assets for current group"""
634
647
  self.assets = dp.all("assets", create_if_not_exist=np.float64)[s:e]
635
648
  """history of rate of return for current group"""
@@ -641,17 +654,75 @@ class Account:
641
654
  self.action_shares = dp.all("action_shares", create_if_not_exist=np.float64)[s:e]
642
655
 
643
656
  """corporate actions"""
644
- self.dividends = dp.all("dividend")[s:e] if "dividend" in dp.data else np.zeros(dp.bars, dtype=np.float64)
645
- self.transfer_shares = dp.all("transfer_shares")[s:e] if "transfer_shares" in dp.data else np.zeros(dp.bars, dtype=np.float64)
646
- self.right_shares = dp.all("right_shares")[s:e] if "right_shares" in dp.data else np.zeros(dp.bars, dtype=np.float64)
647
- self.right_prices = dp.all("right_price")[s:e] if "right_price" in dp.data else np.zeros(dp.bars, dtype=np.float64)
657
+ if _skip_fill:
658
+ self.dividends = None # type: ignore[assignment]
659
+ self.transfer_shares = None # type: ignore[assignment]
660
+ self.right_shares = None # type: ignore[assignment]
661
+ self.right_prices = None # type: ignore[assignment]
662
+ else:
663
+ self.dividends = dp.all("dividend")[s:e] if "dividend" in dp.data else np.zeros(dp.bars, dtype=np.float64)
664
+ self.transfer_shares = dp.all("transfer_shares")[s:e] if "transfer_shares" in dp.data else np.zeros(dp.bars, dtype=np.float64)
665
+ self.right_shares = dp.all("right_shares")[s:e] if "right_shares" in dp.data else np.zeros(dp.bars, dtype=np.float64)
666
+ self.right_prices = dp.all("right_price")[s:e] if "right_price" in dp.data else np.zeros(dp.bars, dtype=np.float64)
667
+
668
+ self.assets.fill(initial_cash)
669
+ self.ror.fill(0.0)
670
+ self.actions.fill(ACTION_KEEP)
671
+ self.action_shares.fill(0.0)
648
672
 
649
- self.assets.fill(initial_cash)
650
- self.ror.fill(0.0)
651
- self.actions.fill(ACTION_KEEP)
652
- self.action_shares.fill(0.0)
673
+ @property
674
+ def records(self) -> list[Record]:
675
+ if self._records is None:
676
+ self._records = self._materialize_records()
677
+ return self._records
678
+
679
+ @records.setter
680
+ def records(self, val: list[Record]):
681
+ self._records = val
682
+ self._raw_trades = None
683
+
684
+ def _materialize_records(self) -> list[Record]:
685
+ raw_info = self._raw_trades
686
+ if raw_info is None:
687
+ return []
688
+ trades, start, end = raw_info
689
+ if end <= start:
690
+ return []
691
+ t_bars = trades["bar"][start:end].tolist()
692
+ t_actions = trades["action"][start:end].tolist()
693
+ t_shares = trades["shares"][start:end].tolist()
694
+ t_prices = trades["deal_price"][start:end].tolist()
695
+ t_fees = trades["fee"][start:end].tolist()
696
+ t_cash = trades["cash_after"][start:end].tolist()
697
+ t_pos_sh = trades["pos_shares"][start:end].tolist()
698
+ t_cost = trades["raw_cost_price"][start:end].tolist()
699
+
700
+ recs: list[Record] = []
701
+ for k in range(len(t_bars)):
702
+ act = t_actions[k]
703
+ sh = t_shares[k]
704
+ dp_val = t_prices[k]
705
+ if act == ACTION_BUY:
706
+ op = Operation.buy(Position(sh, dp_val))
707
+ elif act == ACTION_SELL:
708
+ op = Operation.sell(Position(sh, dp_val))
709
+ elif act == ACTION_BUY_NO_CASH:
710
+ op = Operation.buy_no_cash(Position(0.0, 0.0))
711
+ elif act == ACTION_SELL_NO_HOLD:
712
+ op = Operation.sell_no_hold(Position(0.0, 0.0))
713
+ else:
714
+ op = Operation(act, Position(sh, dp_val))
715
+ pos_snap = Position(t_pos_sh[k], t_cost[k])
716
+ recs.append(Record(t_bars[k], op, t_cash[k], 0.0, pos_snap, t_fees[k]))
717
+ return recs
653
718
 
654
- def clone(self, group: int = 0) -> "Account":
719
+ def clone(
720
+ self,
721
+ group: int = 0,
722
+ *,
723
+ _dates_i64: np.ndarray | None = None,
724
+ _skip_fill: bool = False,
725
+ ) -> "Account":
655
726
  return Account(
656
727
  self.cash,
657
728
  self.dp,
@@ -659,6 +730,8 @@ class Account:
659
730
  fee=self.fee,
660
731
  unit=self.unit,
661
732
  slippage=self.slippage,
733
+ _dates_i64=_dates_i64,
734
+ _skip_fill=_skip_fill,
662
735
  )
663
736
 
664
737
  @property
@@ -679,7 +752,13 @@ class Account:
679
752
  raise ValueError(f"invalid operation: {operation}")
680
753
 
681
754
  fee = 0.0
682
- if self.position.shares > 0:
755
+ if (
756
+ self.position.shares > 0
757
+ and self.dividends is not None
758
+ and self.transfer_shares is not None
759
+ and self.right_shares is not None
760
+ and self.right_prices is not None
761
+ ):
683
762
  dividend = self.dividends[ts]
684
763
  transfer_shares = self.transfer_shares[ts]
685
764
  right_share = self.right_shares[ts]
@@ -1,13 +1,65 @@
1
1
  # Copyright 2026 MSD-RS Project LiJia
2
2
  # SPDX-License-Identifier: BSD-2-Clause
3
3
 
4
- from typing import Protocol
4
+ from typing import Any, Protocol
5
5
  import numpy as np
6
6
  from numpy.typing import DTypeLike
7
7
 
8
8
  MAX_N = 1_000_000_000
9
9
 
10
10
 
11
+ _UNMATERIALIZED = object()
12
+
13
+
14
+ class _LazySlicedDict(dict):
15
+ """Dict view that slices (groups, bars) arrays lazily on first field access."""
16
+
17
+ def __init__(
18
+ self,
19
+ src: dict[str, np.ndarray],
20
+ groups: int,
21
+ bars: int,
22
+ start_bar: int,
23
+ skip_keys: set[str],
24
+ ):
25
+ keys = [k for k in src if k not in skip_keys]
26
+ super().__init__({k: _UNMATERIALIZED for k in keys})
27
+ self._src = src
28
+ self._groups = groups
29
+ self._bars = bars
30
+ self._start_bar = start_bar
31
+
32
+ def _materialize(self, key):
33
+ val = dict.__getitem__(self, key)
34
+ if val is _UNMATERIALIZED:
35
+ raw = self._src[key]
36
+ if len(raw) == self._groups * self._bars:
37
+ val = np.ascontiguousarray(
38
+ raw.reshape(self._groups, self._bars)[:, self._start_bar :]
39
+ ).reshape(-1)
40
+ else:
41
+ val = raw
42
+ dict.__setitem__(self, key, val)
43
+ return val
44
+
45
+ def __getitem__(self, key):
46
+ return self._materialize(key)
47
+
48
+ def get(self, key, default=None):
49
+ if key not in self:
50
+ return default
51
+ return self._materialize(key)
52
+
53
+ def items(self): # type: ignore[override]
54
+ return [(k, self._materialize(k)) for k in self.keys()]
55
+
56
+ def values(self): # type: ignore[override]
57
+ return [self._materialize(k) for k in self.keys()]
58
+
59
+ def copy(self):
60
+ return {k: self._materialize(k) for k in self.keys()}
61
+
62
+
11
63
  class NextHook(Protocol):
12
64
  def __call__(self, i: int, groups: int, bars: int):
13
65
  """
@@ -43,6 +95,9 @@ class DataProvider:
43
95
  self.next_hook = next_hook
44
96
  self.groups = len(self.objs)
45
97
  self.bars = len(self.dates) // self.groups if self.groups > 0 else 0
98
+ self.warmup_bars: int = 0
99
+ self.fin_only_year: bool = False
100
+ self.financial_frame: Any = None
46
101
 
47
102
  @staticmethod
48
103
  def verify_data(objs: list[str], data: dict[str, np.ndarray], ts_name: str):
@@ -146,3 +201,29 @@ class DataProvider:
146
201
  k: v for k, v in self.data.items() if len(v) == self.groups * self.bars
147
202
  }
148
203
  return Panel(cols, list(self.objs), self.bars)
204
+
205
+ def slice_time_window(self, start_bar: int, warmup_bars: int = 0) -> "DataProvider":
206
+ """Return a new DataProvider sliced from `start_bar` to the end without re-querying MSD."""
207
+ if start_bar < 0 or start_bar >= self.bars:
208
+ raise ValueError(f"start_bar {start_bar} out of range [0, {self.bars})")
209
+
210
+ transient = {"assets", "ror", "ror_hold", "actions", "action_shares"}
211
+ g = self.groups
212
+ b = self.bars
213
+ if start_bar == 0:
214
+ new_data = {k: v for k, v in self.data.items() if k not in transient}
215
+ else:
216
+ new_data = _LazySlicedDict(self.data, g, b, start_bar, transient)
217
+
218
+ dp_sub = DataProvider(
219
+ new_data,
220
+ objs=list(self.objs),
221
+ ts_name=self.ts_name,
222
+ next_hook=self.next_hook,
223
+ )
224
+ dp_sub.warmup_bars = max(0, int(warmup_bars))
225
+ if hasattr(self, "fin_only_year"):
226
+ dp_sub.fin_only_year = self.fin_only_year
227
+ if hasattr(self, "financial_frame"):
228
+ dp_sub.financial_frame = self.financial_frame
229
+ return dp_sub
@@ -15,7 +15,7 @@ from typing import Any
15
15
  def check_env() -> dict[str, Any]:
16
16
  """Check Python runtime and core quantitative dependencies."""
17
17
  packages = ["polars", "numpy", "pymsd", "alpha", "orjson"]
18
- installed = {}
18
+ installed: dict[str, str | None] = {}
19
19
  for pkg in packages:
20
20
  try:
21
21
  ver = importlib.metadata.version(pkg)
@@ -0,0 +1,77 @@
1
+ # Copyright 2026 MSD-RS Project LiJia
2
+ # SPDX-License-Identifier: BSD-2-Clause
3
+
4
+ """mbt.factor: Agent-First alpha factor evaluation subsystem."""
5
+
6
+ from .evaluator import evaluate_factor, evaluate_panel
7
+ from .expr import (
8
+ CompiledExpression,
9
+ ExpressionFactor,
10
+ PanelExecContext,
11
+ compile_expression,
12
+ format_operator_catalog,
13
+ load_expression_file,
14
+ parse_inline_expressions,
15
+ )
16
+ from .factor import (
17
+ Factor,
18
+ check_factor_causality,
19
+ check_factor_source,
20
+ load_factor,
21
+ normalize_factor_output,
22
+ )
23
+ from .metrics import (
24
+ ICSummary,
25
+ QuantileAnalysis,
26
+ QuantileMetrics,
27
+ compute_factor_correlation_matrix,
28
+ compute_ic_series,
29
+ compute_quantile_analysis,
30
+ compute_turnover_and_autocorr,
31
+ summarize_ic,
32
+ )
33
+ from .preprocess import (
34
+ compute_log_mktcap,
35
+ neutralize,
36
+ preprocess_factor,
37
+ standardize,
38
+ winsorize,
39
+ )
40
+ from .report import FactorReport, MultiFactorReport, export_report
41
+ from .returns import ForwardReturnSet, build_tradability_masks, compute_forward_returns
42
+
43
+ __all__ = [
44
+ "CompiledExpression",
45
+ "ExpressionFactor",
46
+ "Factor",
47
+ "FactorReport",
48
+ "ForwardReturnSet",
49
+ "ICSummary",
50
+ "MultiFactorReport",
51
+ "PanelExecContext",
52
+ "QuantileAnalysis",
53
+ "QuantileMetrics",
54
+ "build_tradability_masks",
55
+ "check_factor_causality",
56
+ "check_factor_source",
57
+ "compile_expression",
58
+ "compute_factor_correlation_matrix",
59
+ "compute_forward_returns",
60
+ "compute_ic_series",
61
+ "compute_log_mktcap",
62
+ "compute_quantile_analysis",
63
+ "compute_turnover_and_autocorr",
64
+ "evaluate_factor",
65
+ "evaluate_panel",
66
+ "export_report",
67
+ "format_operator_catalog",
68
+ "load_expression_file",
69
+ "load_factor",
70
+ "neutralize",
71
+ "normalize_factor_output",
72
+ "parse_inline_expressions",
73
+ "preprocess_factor",
74
+ "standardize",
75
+ "summarize_ic",
76
+ "winsorize",
77
+ ]
@@ -0,0 +1,11 @@
1
+ # Copyright 2026 MSD-RS Project LiJia
2
+ # SPDX-License-Identifier: BSD-2-Clause
3
+
4
+ """Allow running factor CLI via ``python -m mbt.factor``."""
5
+
6
+ import sys
7
+
8
+ from mbt.factor.cli import main
9
+
10
+ if __name__ == "__main__":
11
+ sys.exit(main())