msd-backtest 0.2.1__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.1/msd_backtest.egg-info → msd_backtest-0.3.0}/PKG-INFO +50 -17
  2. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/README.md +48 -15
  3. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/__init__.py +5 -0
  4. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/account.py +22 -9
  5. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/data_provider.py +6 -3
  6. {msd_backtest-0.2.1 → 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.1 → msd_backtest-0.3.0}/mbt/gui/app.py +1 -1
  19. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/gui/chart.py +3 -3
  20. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/gui/dialogs.py +11 -7
  21. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/gui/inspect_strategy.py +3 -1
  22. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/gui/views.py +5 -2
  23. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/portfolio.py +31 -21
  24. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/run/backend.py +18 -1
  25. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/run/msd.py +10 -9
  26. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/run/overview.py +12 -12
  27. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/run/report.py +8 -0
  28. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/run/runner.py +6 -3
  29. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/select/panel.py +9 -7
  30. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/shared/__init__.py +2 -0
  31. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/shared/financial.py +2 -2
  32. msd_backtest-0.3.0/mbt/shared/stocks.py +690 -0
  33. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/strategy.py +26 -2
  34. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/strategy_templates/fundamental_timing.py +2 -2
  35. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/strategy_templates/multifactor_rotation.py +2 -1
  36. {msd_backtest-0.2.1 → msd_backtest-0.3.0/msd_backtest.egg-info}/PKG-INFO +50 -17
  37. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/msd_backtest.egg-info/SOURCES.txt +17 -0
  38. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/msd_backtest.egg-info/requires.txt +1 -1
  39. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/pyproject.toml +2 -2
  40. msd_backtest-0.3.0/tests/test_factor_cli_and_report.py +165 -0
  41. msd_backtest-0.3.0/tests/test_factor_contract.py +156 -0
  42. msd_backtest-0.3.0/tests/test_factor_expr.py +174 -0
  43. msd_backtest-0.3.0/tests/test_factor_metrics.py +261 -0
  44. msd_backtest-0.3.0/tests/test_factor_preprocess.py +146 -0
  45. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_feedback_fixes.py +74 -0
  46. msd_backtest-0.3.0/tests/test_stocks.py +192 -0
  47. msd_backtest-0.3.0/tests/test_stocks_industry_map.py +128 -0
  48. msd_backtest-0.2.1/mbt/shared/stocks.py +0 -401
  49. msd_backtest-0.2.1/tests/test_stocks.py +0 -132
  50. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/LICENSE +0 -0
  51. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/gui/__init__.py +0 -0
  52. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/gui/__main__.py +0 -0
  53. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/gui/config.py +0 -0
  54. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/gui/downsample.py +0 -0
  55. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/gui/dpi.py +0 -0
  56. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/gui/worker.py +0 -0
  57. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/notify.py +0 -0
  58. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/run/__init__.py +0 -0
  59. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/run/cli.py +0 -0
  60. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/run/review.py +0 -0
  61. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/run/server.py +0 -0
  62. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/run/validator.py +0 -0
  63. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/select/__init__.py +0 -0
  64. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/select/cli.py +0 -0
  65. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/select/msd.py +0 -0
  66. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/select/selector.py +0 -0
  67. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/strategy_templates/__init__.py +0 -0
  68. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/mbt/strategy_templates/cta_momentum.py +0 -0
  69. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/msd_backtest.egg-info/dependency_links.txt +0 -0
  70. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/msd_backtest.egg-info/top_level.txt +0 -0
  71. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/setup.cfg +0 -0
  72. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_account.py +0 -0
  73. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_agent_first.py +0 -0
  74. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_alpha.py +0 -0
  75. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_benchmark_decouple.py +0 -0
  76. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_cli_smoke.py +0 -0
  77. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_dreman_strategy.py +0 -0
  78. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_fee.py +0 -0
  79. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_financial_lag.py +0 -0
  80. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_fix_phase1.py +0 -0
  81. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_fix_phase2.py +0 -0
  82. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_fix_phase3.py +0 -0
  83. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_gui.py +0 -0
  84. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_holding_ror_grid.py +0 -0
  85. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_load_strategy.py +0 -0
  86. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_mdate.py +0 -0
  87. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_msd_setup.py +0 -0
  88. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_multi_start_and_holdout.py +0 -0
  89. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_notify.py +0 -0
  90. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_overview.py +0 -0
  91. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_panel_resample.py +0 -0
  92. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_panel_zero_copy.py +0 -0
  93. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_performance_optimizations.py +0 -0
  94. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_portfolio.py +0 -0
  95. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_position_computed_properties.py +0 -0
  96. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_position_cost_and_ror.py +0 -0
  97. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_raw_prices.py +0 -0
  98. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_rebalance_sell_conflict.py +0 -0
  99. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_report.py +0 -0
  100. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_run_cli_selector.py +0 -0
  101. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_run_msd.py +0 -0
  102. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_runner.py +0 -0
  103. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_runner_fast_path.py +0 -0
  104. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_select_financial.py +0 -0
  105. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_selector.py +0 -0
  106. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_selector_contract.py +0 -0
  107. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_selector_financial.py +0 -0
  108. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_strategy.py +0 -0
  109. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_strategy_finalize.py +0 -0
  110. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_strategy_loading_complex.py +0 -0
  111. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_strategy_templates.py +0 -0
  112. {msd_backtest-0.2.1 → msd_backtest-0.3.0}/tests/test_volume_breakout_monthly_yang_selector.py +0 -0
  113. {msd_backtest-0.2.1 → 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.1
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
 
@@ -628,6 +633,8 @@ class Account:
628
633
  self.slippage = slippage
629
634
  """group index"""
630
635
  self.group = group
636
+ """execution mode ('close' or 'next_open')"""
637
+ self.exec_mode: str = "close"
631
638
 
632
639
  s = self.group * dp.bars
633
640
  e = s + dp.bars
@@ -745,7 +752,13 @@ class Account:
745
752
  raise ValueError(f"invalid operation: {operation}")
746
753
 
747
754
  fee = 0.0
748
- 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
+ ):
749
762
  dividend = self.dividends[ts]
750
763
  transfer_shares = self.transfer_shares[ts]
751
764
  right_share = self.right_shares[ts]
@@ -1,7 +1,7 @@
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
 
@@ -50,10 +50,10 @@ class _LazySlicedDict(dict):
50
50
  return default
51
51
  return self._materialize(key)
52
52
 
53
- def items(self):
53
+ def items(self): # type: ignore[override]
54
54
  return [(k, self._materialize(k)) for k in self.keys()]
55
55
 
56
- def values(self):
56
+ def values(self): # type: ignore[override]
57
57
  return [self._materialize(k) for k in self.keys()]
58
58
 
59
59
  def copy(self):
@@ -95,6 +95,9 @@ class DataProvider:
95
95
  self.next_hook = next_hook
96
96
  self.groups = len(self.objs)
97
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
98
101
 
99
102
  @staticmethod
100
103
  def verify_data(objs: list[str], data: dict[str, np.ndarray], ts_name: str):
@@ -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())