策略预定义阶段的代码库架构剖析machine-learning-for-trading 第六章的策略定义、统计方法与事件研究设计【免费下载链接】machine-learning-for-tradingCode for Machine Learning for Trading, 3rd edition — from data sourcing to live execution.项目地址: https://gitcode.com/GitHub_Trending/ma/machine-learning-for-trading本指南基于machine-learning-for-trading仓库中的 06_strategy_definition/exploration.md 深度架构分析报告系统梳理策略定义这一章节代码库的整体架构、核心代码模式、统计方法与数据流设计并结合当前仓库中的 notebook 源码、测试用例与相关实现进行交叉印证。读者读完后将掌握一套可复用的假说驱动探索工程范式从数据契约到冻结配置、从基于时间的远期收益到事件冷却再到可版本化的策略条款表Term Sheet以及 Newey-West HAC、Lo2002Sharpe 标准误等统计工具的正确分工。一、文档背景一次针对策略预定义代码库的深度架构审查exploration.md是一份对策略定义章节代码库的Deep Architecture Pattern Review深度架构与模式审查生成于 2026-01-25审查类型为深度架构与模式审查。其结论将整章代码库评为★★★★☆4/5出版就绪仍有小幅改进空间并从架构、代码质量、组件清单、数据流、统计方法、依赖关系、风险区域等多个维度给出了完整的证据链。值得注意的是该报告撰写时对应的是章节编号为Chapter 5Strategy Definition的代码结构而当前仓库快照中该目录已演进为Chapter 6Strategy Research Framework目录内实际包含 3 个 notebook01_where_ideas_come_from、02_cv_foundations、03_case_study_overview与 README.md。因此本文以分析报告为骨架同时以当前仓库的实际源码为佐证指出两者之间的演进关系确保所有结论可验证、可追溯。核心结论速览维度评估整体质量★★★★☆4/5出版就绪文档质量★★★★★每个 notebook 均含用途、数据契约、假设与局限类型安全★★★★☆冻结数据类 关键函数类型标注Polars 使用★★★★★惰性 API、.over()窗口仅边界处使用 pandas时间处理★★★★★基于时间的 join 而非 shift、时区感知、容差参数时点正确性Point-in-Time★★★★☆滚动 z-score、宏观数据滞后处理、明确的未来函数警告二、架构总览目录结构与假说驱动探索模式2.1 报告记录的目录结构Chapter 5 时期06_strategy_definition/ ├── chapter/ # 书稿基于分节的工作流 │ ├── draft.md # 由分节自动生成 │ ├── summary.md # 章节范围定义 │ ├── bibliography.md # 学术参考文献 │ └── sections/ # 10 个分节文件真源 │ ├── code/ # 5 个 Jupytext notebook约 4,500 行 │ ├── 01_etf_momentum.py # ETF 相关性、状态、轮动858 行 │ ├── 02_crypto_premium.py # 资金费率均值回归792 行 │ ├── 03_algoseek_intraday.py # 微观结构探索817 行 │ ├── 04_aqr_factor_performance.py # 一个世纪的因子证据1,395 行 │ └── 05_strategy_term_sheet_template.py # Python 数据类模板694 行 │ ├── term_sheets/ # 8 份已完成的策略规格说明书 ├── catalog/ # 5 份 notebook 元数据 JSON ├── figures/ # 书稿图AI 生成 notebook 输出 └── reviews/ # 代码审查产物2.2 当前仓库的对应结构Chapter 6 时期当前仓库中该目录已精简为 3 个 notebook但保持了同样的研究框架定位Notebook教学内容对应章节01_where_ideas_come_from.py从故事到可测量的足迹用 SLOW/WRONG/RISK 分类命名策略优势来源再通过五分位条件收益排序、时代压力测试与换手率检查验证跨资产动量是否留下足迹§6.1–§6.202_cv_foundations.py从第一性原理推导 Walk-Forward 交叉验证决策时点可纳性、标签缓冲purging、特征缓冲embargo、日历感知切分、嵌套 Walk-Forward 与 CPCV§6.503_case_study_overview.py九个案例研究的跨策略汇总资产类别、标的池、成本类别、评估协议与预测覆盖时间线§6.32.3 核心模式假说驱动探索Hypothesis-Driven Exploration整个章节代码库遵循一条清晰的教学模式流水线1. Data Contract文档化的数据假设 ↓ 2. Configuration Dataclass冻结、版本化 ↓ 3. Exploratory Analysis相关性、分布、状态 ↓ 4. Event Study含冷却期、远期收益 ↓ 5. Key Priors Summary供 Term Sheet 使用这条流水线在 01_where_ideas_come_from.py 中有着直接体现notebook 首先明确想法与机制SLOW/WRONG/RISK 分类、谁在对赌、为何愿意与我们交易然后通过参数区定义探索配置再执行五分位条件收益排序、时代压力测试与换手率检查最后把可测量的结论留给后续章节冻结设定。README 将这种逻辑表述为策略不只是信号或模型而是一个必须在决策时点定义、并像实盘一样评估的可执行决策过程——假说驱动探索正是把这句话工程化的手段。三、四大核心代码模式文档精华3.1 模式一配置数据类Configuration Dataclasses——评分为 Excellentdataclass(frozenTrue) class EtfExplorationConfig: Configuration for ETF momentum exploration (Chapter 2). start_date_str: str 2007-01-01 trading_days_per_year: int 252 momentum_formation_days: int 126 # 6 months skip_month_days: int 21 # Skip most recent month # ... etc收益不可变immutable、文档化、成为 notebook 参数的单一真源single source of truth。冻结数据类可以防止探索过程中参数被意外篡改配合类型标注让 IDE 与静态检查工具都能参与校验。当前仓库中的对应实现在 01_where_ideas_come_from.py 中同样的参数化哲学以参数区 Papermill 注入的形式出现# %% tags[parameters] # Production defaults — Papermill injects overrides for CI LOOKBACK 12 # months of past return in the signal SKIP 1 # skip the most recent month (the 12-1 convention) N_QUANTILES 5 # quintiles MIN_NAMES 30 # minimum eligible ETFs in a month to include itLOOKBACK 12信号使用过去 12 个月收益即经典12-1 动量约定SKIP 1跳过最近一个月规避短期反转噪音N_QUANTILES 5按信号分为五分位MIN_NAMES 30月度内合格 ETF 数量下限防止小样本月份污染排序。这与报告中的skip_month_days: int 21遥相呼应——两种时期分别用月数与交易日数表达同一个跳过最近一个月的约定。3.2 模式二基于时间的远期收益Time-Based Forward Returns——生产级质量def _compute_forward_returns_hourly( df: pl.DataFrame, *, price_col: str, horizons_hours: tuple[int, ...], group_col: str, ts_col: str, tolerance_hours: int 2, ) - pl.DataFrame:模式要点使用join_asof配合tolerance容差替代.shift()来计算远期收益从而正确处理缺失数据/非对齐时间戳造成的缺口。.shift()假设数据行是均匀间隔的而真实市场数据尤其是小时级 crypto 或分钟级微观结构数据存在停牌、节假日、数据缺口join_asof加容差才能在最近可用的未来价格上精确计算收益。设计启示函数签名使用 keyword-only 参数*之后强制调用方显式写出每个参数名显著降低参数错位风险tolerance_hours的存在说明作者把数据缺口容忍度视为显式的建模假设而非隐藏的默认行为。3.3 模式三带冷却期的事件研究Event Study with Proper Cooldowndef event_study_with_cooldown( df: pl.DataFrame, regime_col: str regime, cooldown_hours: int 24, ) - pl.DataFrame:模式要点有状态的稀疏化stateful thinning——比较的对象是最近一个被保留的事件而不是上一个事件。这一细节至关重要如果简单地按时间间隔过滤如事件之间至少间隔 24 小时在事件密集区会因为前一个事件被剔除、当前事件却因与它相距够远而被保留而产生误判正确做法是维护一个最后保留事件的时间戳每遇到新事件都与它比较。这保证了事件样本的独立性避免同一波行情被重复计数而放大显著性。3.4 模式四策略条款表Strategy Term Sheet作为 Python 数据类dataclass class StrategyTermSheet: name: str version: str status: Literal[Draft, Review, Approved] classification: Literal[Price-Based, Fundamental, Structural, ML-Enhanced] hypothesis: FalsifiableHypothesis blueprint: ImplementationBlueprint feasibility: FeasibilityGate validation: ValidationPlan收益强制结构化支持 JSON/YAML 导出支持版本控制。逐字段解读字段类型作用namestr策略名称对应 term sheet 文件名主前缀versionstr版本号配合 git 实现版本化演进statusLiteral[Draft, Review, Approved]生命周期状态机约束策略何时可进入下游回测classificationLiteral[Price-Based, Fundamental, Structural, ML-Enhanced]策略族分类是可行性过滤器的第一层hypothesisFalsifiableHypothesis可证伪假说——策略的为什么可能有效必须以可被数据拒绝的形式陈述blueprintImplementationBlueprint实现蓝图信号定义、决策时点、换仓规则、可交易标的feasibilityFeasibilityGate可行性门数据可得性、交易成本量级、容量约束validationValidationPlan验证计划评估协议、失败条件、通过/拒绝阈值FalsifiableHypothesis可证伪假说字段是整章方法论的核心——它把策略想法从叙事性陈述动量有效改造成可拒绝的实证声明过去 12 个月收益居前五分位的资产未来一个月条件收益单调高于末五分位从而为后续所有统计检验提供靶子。这一点在当前仓库 01_where_ideas_come_from.py 的 SLOW/WRONG/RISK 分类中得到呼应notebook 预先命名机制SLOW宏观信息跨市场缓慢扩散WRONG投资者反应不足并追逐表现同时预先声明失败模式动量在转折点剧烈反转且因人人可读同一份价格历史而衰减——这正是可证伪假说思维在探索阶段的落地。3.5 内部依赖关系05_strategy_term_sheet_template.py ↓ exports StrategyTermSheet (dataclass) ↓ used by term_sheets/*.md (via to_markdown())即数据类模板通过to_markdown()方法导出为 markdown 形式的 term sheet实现代码即真源、文档即产物的单向依赖。四、组件清单Notebook、Term Sheet 与章节分节4.1 Notebook 清单报告记录5 个约 4,500 行Notebook用途数据源行数质量01_etf_momentum相关性、状态、轮动ETF Universe, FRED858★★★★★02_crypto_premium资金费率均值回归Binance Premium/OHLCV792★★★★★03_algoseek_intraday微观结构探索AlgoSeek NASDAQ100817★★★★☆04_aqr_factor_performance一个世纪的因子证据AQR, Fama-French1,395★★★★★05_strategy_term_sheet_template交互式 Term Sheet无694★★★★★4.2 Term Sheet 清单报告记录8 份Term Sheet分类状态etf_momentum__rotational_momentum.mdPrice-BasedCompletecrypto_premium__premium_funding_reversal.mdStructuralCompletenasdaq100_reversal__intraday_orderflow_reversal.mdStructuralCompleteus_factors__cross_sectional_factor_momentum.mdPrice-BasedCompletefutures_carry__term_structure_momentum.mdStructuralCompletefx_momentum__cross_sectional_momentum.mdPrice-BasedCompletealgoseek_sp500__options_volatility_alpha.mdStructuralCompleteetf_momentum.mdPrice-BasedLegacy旧版应使用带__的版本命名约定{dataset}__{strategy_type}.md例如etf_momentum__rotational_momentum.md、crypto_premium__premium_funding_reversal.md。报告中指出etf_momentum.md与etf_momentum__rotational_momentum.md并存造成了哪个是规范版本的混淆属于中等风险项。这些 term sheet 所描述的策略族与当前仓库 case_studies 目录下的案例一一对应——case_studies/etfs、case_studies/crypto_perps_funding、case_studies/nasdaq100_microstructure、case_studies/us_firm_characteristics 等均延续了ETF 轮动 / 资金费率反转 / 微观结构 / 因子动量的研究线且这些案例目录中都包含 14_backtest 等下游回测 notebook印证了报告数据流图中Term Sheet → 下游章节特征、回测的走向。4.3 章节分节清单报告记录10 节00_preamble.md 01_the_strategy_specification_problem.md 02_a_map_of_strategies_and_edges.md 03_the_strategy_term_sheet.md 04_filling_the_term_sheet.md 05_minimum_specification_feasibility.md 06_validation_plan_and_failure_conditions.md 07_where_ideas_come_from.md 08_evidence_discipline_and_the_factor_zoo.md 09_key_takeaways.md当前仓库 README.md 将这一脉络浓缩为 7 个学习目标把想法映射到策略地图、以决策时点术语定义版本化交易设定、在经济意义上定义更好、设计保持时序的评估协议、建立窄基线检查点、用试验分类学保持搜索可审计——可以看到策略规格说明问题→策略地图→Term Sheet→可行性→验证计划这一报告中的分节骨架被完整保留。五、数据流架构从数据层到下游章节┌─────────────────┐ │ Data Layer │ │ (utils, DATA_DIR)│ └────────┬────────┘ │ ┌────────────────────┼────────────────────┐ │ │ │ ▼ ▼ ▼ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ ETF Universe │ │ Crypto Premium│ │ AlgoSeek │ │ FRED │ │ OHLCV │ │ Minute Bars │ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘ │ │ │ ▼ ▼ ▼ ┌───────────────────────────────────────────────────┐ │ Exploration Notebooks │ │ (correlation, regime, event study, statistics) │ └───────────────────────┬───────────────────────────┘ │ ▼ ┌───────────────────────────────────────────────────┐ │ Strategy Term Sheets │ │ (hypothesis, blueprint, feasibility, validation)│ └───────────────────────────────────────────────────┘ │ ▼ Downstream Chapters (Ch7 features, Ch17 backtest)这条数据流的三个关键设计决策值得展开数据层统一接入所有 notebook 通过utilsDATA_DIR路径管理与ml4t.data.providersAQR、Fama-French 数据接入数据不在 notebook 内部硬编码路径。当前仓库的 01_where_ideas_come_from.py 延续了该约定通过from data import load_etfs加载 ETF 面板并注明数据前提ML4T_DATA_PATH/etfs/market/下存在 parquet缺失时运行python data/etfs/market/download.py。探索先行、规格后置Notebook 只负责产出证据相关性、状态、事件研究统计量不负责下结论结论沉淀为 Term Sheet。这实现了证据生产与决策记录的解耦。单向依赖Term Sheet 只依赖探索 notebook 的输出下游章节特征工程、回测只依赖 Term Sheet不存在反向依赖从而保证整个研究流水线可独立重跑、独立审计。六、统计方法详解工具的正确分工6.1 因子分析04_aqr_factor_performance方法实现质量Newey-West HAC t 统计calculate_mean_return_tstat()★★★★★Lo2002Sharpe 标准误calculate_sharpe_stats()★★★★★最大回撤calculate_max_drawdown()★★★★☆滚动相关性pl.rolling_corr()原生★★★★★报告特别强调的关键区分必须正确区分Harvey et al.2016均值收益 t 统计用于因子发现与Lo2002Sharpe 比率显著性用于绩效评估两种推断框架。前者回答这个因子是否真实存在后者回答这个策略绩效是否显著区别于运气——用错工具会直接导致多重检验下的虚假发现。当前仓库的对应实现在 17_portfolio_construction/05_factor_allocation_evidence.py 中可以找到同名的calculate_mean_return_tstat()其实现细节正是文档所述方法的可运行版本# Newey-West lag selection max_lag int(np.floor(4 * (n / 100) ** (2 / 9))) max_lag max(1, min(max_lag, n // 4)) # Compute Newey-West HAC variance resid returns - mean_ret gamma_0 np.sum(resid**2) / n gamma_sum 0 for j in range(1, max_lag 1): weight 1 - j / (max_lag 1) # Bartlett kernel gamma_j np.sum(resid[j:] * resid[:-j]) / n gamma_sum 2 * weight * gamma_j nw_var (gamma_0 gamma_sum) / n nw_se np.sqrt(max(nw_var, 1e-10)) mean_tstat mean_ret / nw_se if nw_se 0 else 0要点解读滞后阶数选择遵循4 * (n / 100)^(2/9)的经验法则并夹在[1, n//4]区间内Bartlett 核weight 1 - j / (max_lag 1)对高阶自协方差线性递减加权保证 HAC 方差估计半正定推断使用月度尺度上的mean_tstat而非年化标准误——年化只用于展示mean_return避免了年化 SE 带来的误导。同文件中的calculate_sharpe_stats()则采用 Lo 式诊断将月度估计与其标准误一并重标度到年度单位并用compute_autocorrelation_adjustment()对收益自相关进行不确定性膨胀——这是一个透明的 Lo 风格近似该文件注释明确说明不是 Lo (2002) 的完整协方差表达式报告对该实现的评价是★★★★★正确区分了两种推断目的。6.2 动量分析01_etf_momentum方法实现质量截面五分位排名.rank(ordinal).over(timestamp)★★★★★6-1 动量跳过最近月向量化.shift()★★★★★收益率曲线状态过滤FRED 数据 2 交易日滞后★★★★★轮动模拟逐月循环教学目的★★★★☆截面五分位排名使用 Polars 的over(timestamp)窗口内排名天然是截面cross-sectional操作无数据泄漏6-1 动量的跳过最近一个月约定与 01_where_ideas_come_from.py 中SKIP 1参数一致该约定在仓库测试中被显式验证——tests/test_etf_skip_recent_momentum.py 的测试test_skip_recent_momentum_uses_price_ratio_ending_one_month_ago断言跳过的区间是一个月并规定skip_recent 21个交易日、动量窗口族[5, 10, 21, 42, 63, 126, 189, 252]。该测试用 AST 解析方式从 notebook 中抽取momentum_features函数而不执行整个 notebook确保被测试的就是 notebook 内真实使用的实现收益率曲线状态过滤引入 2 交易日滞后是时点正确性point-in-time纪律的典型例子——宏观数据发布滞后必须显式建模否则状态标签会偷看未来逐月循环模拟被标记为教学目的可接受的教学性实现属于低风险项。6.3 事件研究02_crypto_premium、03_algoseek_intraday方法实现质量滚动 z-score时点正确168 小时窗口★★★★★事件冷却按组有状态稀疏化★★★★★远期收益基于时间 join 容差★★★★★Winsorization全局分位数仅探索用★★★★☆滚动 z-score 使用168 小时窗口7 天而不是固定行数窗口保证在数据缺失时窗口仍然代表最近 7 个自然日的完整信息。全局 winsorization使用全样本分位数被文档标注为仅探索阶段使用——因为它理论上存在轻微的时点泄漏在正式信号构建阶段应替换为滚动分位数。七、代码质量标准符合度与依赖分析7.1 与书籍标准的符合度标准符合度说明Polars-first✅ 完全除可视化边界外无 pandas冻结配置数据类✅ 完全所有 notebook 均采用该模式基于时间的 join✅ 完全远期收益不使用.shift()数据契约文档化✅ 完全每个 notebook 均有契约表输出仅限figures/✅ 完全无临时文件落盘章节正文不含代码✅ 完全按名称引用 notebookTEST 模式支持⚠️ 部分并非所有 notebook 都有显式 TEST 守卫7.2 外部依赖# Core polars # DataFrames主 numpy # 数值运算 pandas # 仅边界转换 plotly # 可视化 # Domain scipy.stats # 统计检验 IPython.display # Jupyter 渲染 # ML4T utils # DATA_DIR、路径 ml4t.data.providers # AQR、Fama-FrenchPolars-first、pandas 仅限可视化边界是这份审查报告反复强调的架构纪律pandas 仅在需要matplotlib/scipy互操作时出现转换只发生在边界处核心计算全部由 Polars 的惰性 API 承担。运行方式方面README.md 给出当前仓库的推荐执行方式# 仓库根目录执行 uv run python 06_strategy_definition/notebook.py # 测试模式通过 Papermill 缩减数据 uv run pytest tests/test_notebooks.py -v -k 06_strategy_definition这解释了 3.1 节中tags[parameters]参数区的作用正常执行使用生产默认值CI 测试时由 Papermill 注入缩减数据集的覆盖参数。八、改进建议、风险区域与总结8.1 改进建议按优先级优先级 1代码细节改进为 notebook 增加__all__导出支持模块级复用__all__ [EtfExplorationConfig, calculate_momentum_score]抽取公共工具到共享模块_compute_forward_returns_*系列函数与_event_cooldown_filter在多个 notebook 中重复出现应上移到utils/exploration.py为旧版etf_momentum.md增加 catalog 条目或直接移除明确规范版本。优先级 2文档增强在 README 增加 notebook 执行顺序说明文档化 term sheet 命名约定{dataset}__{strategy_type}.md。优先级 3测试覆盖为calculate_mean_return_tstat()、calculate_sharpe_stats()Lo 2002 SE、_event_cooldown_filter()增加单元测试对照已知数值与边界情况增加数据契约校验测试验证 parquet 模式与文档化契约一致检查预期列名与 dtype。值得注意第 3 条数据契约校验的建议在当前仓库中已经部分落地——tests/test_etf_skip_recent_momentum.py 正是以从 notebook 中抽取真实函数 断言可复现行为的方式补上了动量定义的可测试性。8.2 风险区域低风险可接受区域观察缓解pandas 边界matplotlib/scipy 需要 pandas仅边界转换影响最小全局 winsorization使用全样本分位数已文档化为仅探索使用轮动模拟中的循环逐月循环为清晰起见教学目的可接受中等风险需监控区域观察缓解重复 term sheetetf_momentum.md与etf_momentum__*.md并存澄清规范版本硬编码魔法数字notebook 正文中的部分阈值移入配置数据类缺少类型标注部分辅助函数类型不全为生产复用补齐8.3 总结这份代码库为什么值得作为策略预定义的标准范本综合报告结论策略定义章节代码库体现了四点示范价值清晰的关注点分离数据契约 → 配置 → 分析 → 总结每层职责单一、边界明确正确的统计工具Newey-West HAC 用于因子发现、Lo Sharpe 标准误用于绩效评估、基于时间的远期收益避免缺口误判工具与问题严格匹配时点正确性纪律滚动 z-score、宏观数据滞后处理、标签缓冲与特征缓冲从源头杜绝未来函数版本化产物Term Sheet 作为结构化文档进入版本控制使策略规格本身成为可 diff、可审计、可回滚的一等公民。该章节的核心方法论在演进后的 README.md 中凝练为一句可执行的原则历史上有效的测试要能说明未来的行为就必须把策略当作在决策时点定义、并像实盘一样评估的可执行决策过程——假说驱动探索、冻结配置、事件研究冷却与可证伪假说正是把这一原则落到代码层面的完整工具箱。报告最终评价为出版就绪仅需小幅清理其改进建议抽取公共工具、澄清命名、补齐统计函数测试也是任何同类策略研究代码库可以直接复用的治理清单。本文以 06_strategy_definition/exploration.md 为骨架结合当前仓库 06_strategy_definition/ 下的 notebook 源码、tests/test_etf_skip_recent_momentum.py 与 17_portfolio_construction/05_factor_allocation_evidence.py 中的统计实现交叉印证报告中记录的 Chapter 5 时期目录结构如code/、term_sheets/属于分析时的快照当前仓库中该章节已演进为 Chapter 6 的 3-notebook 结构两者以演进关系对应不构成矛盾。【免费下载链接】machine-learning-for-tradingCode for Machine Learning for Trading, 3rd edition — from data sourcing to live execution.项目地址: https://gitcode.com/GitHub_Trending/ma/machine-learning-for-trading创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
策略预定义阶段的代码库架构剖析machine-learning-for-trading 第六章的策略定义、统计方法与事件研究设计【免费下载链接】machine-learning-for-tradingCode for Machine Learning for Trading, 3rd edition — from data sourcing to live execution.项目地址: https://gitcode.com/GitHub_Trending/ma/machine-learning-for-trading本指南基于machine-learning-for-trading仓库中的 06_strategy_definition/exploration.md 深度架构分析报告系统梳理策略定义这一章节代码库的整体架构、核心代码模式、统计方法与数据流设计并结合当前仓库中的 notebook 源码、测试用例与相关实现进行交叉印证。读者读完后将掌握一套可复用的假说驱动探索工程范式从数据契约到冻结配置、从基于时间的远期收益到事件冷却再到可版本化的策略条款表Term Sheet以及 Newey-West HAC、Lo2002Sharpe 标准误等统计工具的正确分工。一、文档背景一次针对策略预定义代码库的深度架构审查exploration.md是一份对策略定义章节代码库的Deep Architecture Pattern Review深度架构与模式审查生成于 2026-01-25审查类型为深度架构与模式审查。其结论将整章代码库评为★★★★☆4/5出版就绪仍有小幅改进空间并从架构、代码质量、组件清单、数据流、统计方法、依赖关系、风险区域等多个维度给出了完整的证据链。值得注意的是该报告撰写时对应的是章节编号为Chapter 5Strategy Definition的代码结构而当前仓库快照中该目录已演进为Chapter 6Strategy Research Framework目录内实际包含 3 个 notebook01_where_ideas_come_from、02_cv_foundations、03_case_study_overview与 README.md。因此本文以分析报告为骨架同时以当前仓库的实际源码为佐证指出两者之间的演进关系确保所有结论可验证、可追溯。核心结论速览维度评估整体质量★★★★☆4/5出版就绪文档质量★★★★★每个 notebook 均含用途、数据契约、假设与局限类型安全★★★★☆冻结数据类 关键函数类型标注Polars 使用★★★★★惰性 API、.over()窗口仅边界处使用 pandas时间处理★★★★★基于时间的 join 而非 shift、时区感知、容差参数时点正确性Point-in-Time★★★★☆滚动 z-score、宏观数据滞后处理、明确的未来函数警告二、架构总览目录结构与假说驱动探索模式2.1 报告记录的目录结构Chapter 5 时期06_strategy_definition/ ├── chapter/ # 书稿基于分节的工作流 │ ├── draft.md # 由分节自动生成 │ ├── summary.md # 章节范围定义 │ ├── bibliography.md # 学术参考文献 │ └── sections/ # 10 个分节文件真源 │ ├── code/ # 5 个 Jupytext notebook约 4,500 行 │ ├── 01_etf_momentum.py # ETF 相关性、状态、轮动858 行 │ ├── 02_crypto_premium.py # 资金费率均值回归792 行 │ ├── 03_algoseek_intraday.py # 微观结构探索817 行 │ ├── 04_aqr_factor_performance.py # 一个世纪的因子证据1,395 行 │ └── 05_strategy_term_sheet_template.py # Python 数据类模板694 行 │ ├── term_sheets/ # 8 份已完成的策略规格说明书 ├── catalog/ # 5 份 notebook 元数据 JSON ├── figures/ # 书稿图AI 生成 notebook 输出 └── reviews/ # 代码审查产物2.2 当前仓库的对应结构Chapter 6 时期当前仓库中该目录已精简为 3 个 notebook但保持了同样的研究框架定位Notebook教学内容对应章节01_where_ideas_come_from.py从故事到可测量的足迹用 SLOW/WRONG/RISK 分类命名策略优势来源再通过五分位条件收益排序、时代压力测试与换手率检查验证跨资产动量是否留下足迹§6.1–§6.202_cv_foundations.py从第一性原理推导 Walk-Forward 交叉验证决策时点可纳性、标签缓冲purging、特征缓冲embargo、日历感知切分、嵌套 Walk-Forward 与 CPCV§6.503_case_study_overview.py九个案例研究的跨策略汇总资产类别、标的池、成本类别、评估协议与预测覆盖时间线§6.32.3 核心模式假说驱动探索Hypothesis-Driven Exploration整个章节代码库遵循一条清晰的教学模式流水线1. Data Contract文档化的数据假设 ↓ 2. Configuration Dataclass冻结、版本化 ↓ 3. Exploratory Analysis相关性、分布、状态 ↓ 4. Event Study含冷却期、远期收益 ↓ 5. Key Priors Summary供 Term Sheet 使用这条流水线在 01_where_ideas_come_from.py 中有着直接体现notebook 首先明确想法与机制SLOW/WRONG/RISK 分类、谁在对赌、为何愿意与我们交易然后通过参数区定义探索配置再执行五分位条件收益排序、时代压力测试与换手率检查最后把可测量的结论留给后续章节冻结设定。README 将这种逻辑表述为策略不只是信号或模型而是一个必须在决策时点定义、并像实盘一样评估的可执行决策过程——假说驱动探索正是把这句话工程化的手段。三、四大核心代码模式文档精华3.1 模式一配置数据类Configuration Dataclasses——评分为 Excellentdataclass(frozenTrue) class EtfExplorationConfig: Configuration for ETF momentum exploration (Chapter 2). start_date_str: str 2007-01-01 trading_days_per_year: int 252 momentum_formation_days: int 126 # 6 months skip_month_days: int 21 # Skip most recent month # ... etc收益不可变immutable、文档化、成为 notebook 参数的单一真源single source of truth。冻结数据类可以防止探索过程中参数被意外篡改配合类型标注让 IDE 与静态检查工具都能参与校验。当前仓库中的对应实现在 01_where_ideas_come_from.py 中同样的参数化哲学以参数区 Papermill 注入的形式出现# %% tags[parameters] # Production defaults — Papermill injects overrides for CI LOOKBACK 12 # months of past return in the signal SKIP 1 # skip the most recent month (the 12-1 convention) N_QUANTILES 5 # quintiles MIN_NAMES 30 # minimum eligible ETFs in a month to include itLOOKBACK 12信号使用过去 12 个月收益即经典12-1 动量约定SKIP 1跳过最近一个月规避短期反转噪音N_QUANTILES 5按信号分为五分位MIN_NAMES 30月度内合格 ETF 数量下限防止小样本月份污染排序。这与报告中的skip_month_days: int 21遥相呼应——两种时期分别用月数与交易日数表达同一个跳过最近一个月的约定。3.2 模式二基于时间的远期收益Time-Based Forward Returns——生产级质量def _compute_forward_returns_hourly( df: pl.DataFrame, *, price_col: str, horizons_hours: tuple[int, ...], group_col: str, ts_col: str, tolerance_hours: int 2, ) - pl.DataFrame:模式要点使用join_asof配合tolerance容差替代.shift()来计算远期收益从而正确处理缺失数据/非对齐时间戳造成的缺口。.shift()假设数据行是均匀间隔的而真实市场数据尤其是小时级 crypto 或分钟级微观结构数据存在停牌、节假日、数据缺口join_asof加容差才能在最近可用的未来价格上精确计算收益。设计启示函数签名使用 keyword-only 参数*之后强制调用方显式写出每个参数名显著降低参数错位风险tolerance_hours的存在说明作者把数据缺口容忍度视为显式的建模假设而非隐藏的默认行为。3.3 模式三带冷却期的事件研究Event Study with Proper Cooldowndef event_study_with_cooldown( df: pl.DataFrame, regime_col: str regime, cooldown_hours: int 24, ) - pl.DataFrame:模式要点有状态的稀疏化stateful thinning——比较的对象是最近一个被保留的事件而不是上一个事件。这一细节至关重要如果简单地按时间间隔过滤如事件之间至少间隔 24 小时在事件密集区会因为前一个事件被剔除、当前事件却因与它相距够远而被保留而产生误判正确做法是维护一个最后保留事件的时间戳每遇到新事件都与它比较。这保证了事件样本的独立性避免同一波行情被重复计数而放大显著性。3.4 模式四策略条款表Strategy Term Sheet作为 Python 数据类dataclass class StrategyTermSheet: name: str version: str status: Literal[Draft, Review, Approved] classification: Literal[Price-Based, Fundamental, Structural, ML-Enhanced] hypothesis: FalsifiableHypothesis blueprint: ImplementationBlueprint feasibility: FeasibilityGate validation: ValidationPlan收益强制结构化支持 JSON/YAML 导出支持版本控制。逐字段解读字段类型作用namestr策略名称对应 term sheet 文件名主前缀versionstr版本号配合 git 实现版本化演进statusLiteral[Draft, Review, Approved]生命周期状态机约束策略何时可进入下游回测classificationLiteral[Price-Based, Fundamental, Structural, ML-Enhanced]策略族分类是可行性过滤器的第一层hypothesisFalsifiableHypothesis可证伪假说——策略的为什么可能有效必须以可被数据拒绝的形式陈述blueprintImplementationBlueprint实现蓝图信号定义、决策时点、换仓规则、可交易标的feasibilityFeasibilityGate可行性门数据可得性、交易成本量级、容量约束validationValidationPlan验证计划评估协议、失败条件、通过/拒绝阈值FalsifiableHypothesis可证伪假说字段是整章方法论的核心——它把策略想法从叙事性陈述动量有效改造成可拒绝的实证声明过去 12 个月收益居前五分位的资产未来一个月条件收益单调高于末五分位从而为后续所有统计检验提供靶子。这一点在当前仓库 01_where_ideas_come_from.py 的 SLOW/WRONG/RISK 分类中得到呼应notebook 预先命名机制SLOW宏观信息跨市场缓慢扩散WRONG投资者反应不足并追逐表现同时预先声明失败模式动量在转折点剧烈反转且因人人可读同一份价格历史而衰减——这正是可证伪假说思维在探索阶段的落地。3.5 内部依赖关系05_strategy_term_sheet_template.py ↓ exports StrategyTermSheet (dataclass) ↓ used by term_sheets/*.md (via to_markdown())即数据类模板通过to_markdown()方法导出为 markdown 形式的 term sheet实现代码即真源、文档即产物的单向依赖。四、组件清单Notebook、Term Sheet 与章节分节4.1 Notebook 清单报告记录5 个约 4,500 行Notebook用途数据源行数质量01_etf_momentum相关性、状态、轮动ETF Universe, FRED858★★★★★02_crypto_premium资金费率均值回归Binance Premium/OHLCV792★★★★★03_algoseek_intraday微观结构探索AlgoSeek NASDAQ100817★★★★☆04_aqr_factor_performance一个世纪的因子证据AQR, Fama-French1,395★★★★★05_strategy_term_sheet_template交互式 Term Sheet无694★★★★★4.2 Term Sheet 清单报告记录8 份Term Sheet分类状态etf_momentum__rotational_momentum.mdPrice-BasedCompletecrypto_premium__premium_funding_reversal.mdStructuralCompletenasdaq100_reversal__intraday_orderflow_reversal.mdStructuralCompleteus_factors__cross_sectional_factor_momentum.mdPrice-BasedCompletefutures_carry__term_structure_momentum.mdStructuralCompletefx_momentum__cross_sectional_momentum.mdPrice-BasedCompletealgoseek_sp500__options_volatility_alpha.mdStructuralCompleteetf_momentum.mdPrice-BasedLegacy旧版应使用带__的版本命名约定{dataset}__{strategy_type}.md例如etf_momentum__rotational_momentum.md、crypto_premium__premium_funding_reversal.md。报告中指出etf_momentum.md与etf_momentum__rotational_momentum.md并存造成了哪个是规范版本的混淆属于中等风险项。这些 term sheet 所描述的策略族与当前仓库 case_studies 目录下的案例一一对应——case_studies/etfs、case_studies/crypto_perps_funding、case_studies/nasdaq100_microstructure、case_studies/us_firm_characteristics 等均延续了ETF 轮动 / 资金费率反转 / 微观结构 / 因子动量的研究线且这些案例目录中都包含 14_backtest 等下游回测 notebook印证了报告数据流图中Term Sheet → 下游章节特征、回测的走向。4.3 章节分节清单报告记录10 节00_preamble.md 01_the_strategy_specification_problem.md 02_a_map_of_strategies_and_edges.md 03_the_strategy_term_sheet.md 04_filling_the_term_sheet.md 05_minimum_specification_feasibility.md 06_validation_plan_and_failure_conditions.md 07_where_ideas_come_from.md 08_evidence_discipline_and_the_factor_zoo.md 09_key_takeaways.md当前仓库 README.md 将这一脉络浓缩为 7 个学习目标把想法映射到策略地图、以决策时点术语定义版本化交易设定、在经济意义上定义更好、设计保持时序的评估协议、建立窄基线检查点、用试验分类学保持搜索可审计——可以看到策略规格说明问题→策略地图→Term Sheet→可行性→验证计划这一报告中的分节骨架被完整保留。五、数据流架构从数据层到下游章节┌─────────────────┐ │ Data Layer │ │ (utils, DATA_DIR)│ └────────┬────────┘ │ ┌────────────────────┼────────────────────┐ │ │ │ ▼ ▼ ▼ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ ETF Universe │ │ Crypto Premium│ │ AlgoSeek │ │ FRED │ │ OHLCV │ │ Minute Bars │ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘ │ │ │ ▼ ▼ ▼ ┌───────────────────────────────────────────────────┐ │ Exploration Notebooks │ │ (correlation, regime, event study, statistics) │ └───────────────────────┬───────────────────────────┘ │ ▼ ┌───────────────────────────────────────────────────┐ │ Strategy Term Sheets │ │ (hypothesis, blueprint, feasibility, validation)│ └───────────────────────────────────────────────────┘ │ ▼ Downstream Chapters (Ch7 features, Ch17 backtest)这条数据流的三个关键设计决策值得展开数据层统一接入所有 notebook 通过utilsDATA_DIR路径管理与ml4t.data.providersAQR、Fama-French 数据接入数据不在 notebook 内部硬编码路径。当前仓库的 01_where_ideas_come_from.py 延续了该约定通过from data import load_etfs加载 ETF 面板并注明数据前提ML4T_DATA_PATH/etfs/market/下存在 parquet缺失时运行python data/etfs/market/download.py。探索先行、规格后置Notebook 只负责产出证据相关性、状态、事件研究统计量不负责下结论结论沉淀为 Term Sheet。这实现了证据生产与决策记录的解耦。单向依赖Term Sheet 只依赖探索 notebook 的输出下游章节特征工程、回测只依赖 Term Sheet不存在反向依赖从而保证整个研究流水线可独立重跑、独立审计。六、统计方法详解工具的正确分工6.1 因子分析04_aqr_factor_performance方法实现质量Newey-West HAC t 统计calculate_mean_return_tstat()★★★★★Lo2002Sharpe 标准误calculate_sharpe_stats()★★★★★最大回撤calculate_max_drawdown()★★★★☆滚动相关性pl.rolling_corr()原生★★★★★报告特别强调的关键区分必须正确区分Harvey et al.2016均值收益 t 统计用于因子发现与Lo2002Sharpe 比率显著性用于绩效评估两种推断框架。前者回答这个因子是否真实存在后者回答这个策略绩效是否显著区别于运气——用错工具会直接导致多重检验下的虚假发现。当前仓库的对应实现在 17_portfolio_construction/05_factor_allocation_evidence.py 中可以找到同名的calculate_mean_return_tstat()其实现细节正是文档所述方法的可运行版本# Newey-West lag selection max_lag int(np.floor(4 * (n / 100) ** (2 / 9))) max_lag max(1, min(max_lag, n // 4)) # Compute Newey-West HAC variance resid returns - mean_ret gamma_0 np.sum(resid**2) / n gamma_sum 0 for j in range(1, max_lag 1): weight 1 - j / (max_lag 1) # Bartlett kernel gamma_j np.sum(resid[j:] * resid[:-j]) / n gamma_sum 2 * weight * gamma_j nw_var (gamma_0 gamma_sum) / n nw_se np.sqrt(max(nw_var, 1e-10)) mean_tstat mean_ret / nw_se if nw_se 0 else 0要点解读滞后阶数选择遵循4 * (n / 100)^(2/9)的经验法则并夹在[1, n//4]区间内Bartlett 核weight 1 - j / (max_lag 1)对高阶自协方差线性递减加权保证 HAC 方差估计半正定推断使用月度尺度上的mean_tstat而非年化标准误——年化只用于展示mean_return避免了年化 SE 带来的误导。同文件中的calculate_sharpe_stats()则采用 Lo 式诊断将月度估计与其标准误一并重标度到年度单位并用compute_autocorrelation_adjustment()对收益自相关进行不确定性膨胀——这是一个透明的 Lo 风格近似该文件注释明确说明不是 Lo (2002) 的完整协方差表达式报告对该实现的评价是★★★★★正确区分了两种推断目的。6.2 动量分析01_etf_momentum方法实现质量截面五分位排名.rank(ordinal).over(timestamp)★★★★★6-1 动量跳过最近月向量化.shift()★★★★★收益率曲线状态过滤FRED 数据 2 交易日滞后★★★★★轮动模拟逐月循环教学目的★★★★☆截面五分位排名使用 Polars 的over(timestamp)窗口内排名天然是截面cross-sectional操作无数据泄漏6-1 动量的跳过最近一个月约定与 01_where_ideas_come_from.py 中SKIP 1参数一致该约定在仓库测试中被显式验证——tests/test_etf_skip_recent_momentum.py 的测试test_skip_recent_momentum_uses_price_ratio_ending_one_month_ago断言跳过的区间是一个月并规定skip_recent 21个交易日、动量窗口族[5, 10, 21, 42, 63, 126, 189, 252]。该测试用 AST 解析方式从 notebook 中抽取momentum_features函数而不执行整个 notebook确保被测试的就是 notebook 内真实使用的实现收益率曲线状态过滤引入 2 交易日滞后是时点正确性point-in-time纪律的典型例子——宏观数据发布滞后必须显式建模否则状态标签会偷看未来逐月循环模拟被标记为教学目的可接受的教学性实现属于低风险项。6.3 事件研究02_crypto_premium、03_algoseek_intraday方法实现质量滚动 z-score时点正确168 小时窗口★★★★★事件冷却按组有状态稀疏化★★★★★远期收益基于时间 join 容差★★★★★Winsorization全局分位数仅探索用★★★★☆滚动 z-score 使用168 小时窗口7 天而不是固定行数窗口保证在数据缺失时窗口仍然代表最近 7 个自然日的完整信息。全局 winsorization使用全样本分位数被文档标注为仅探索阶段使用——因为它理论上存在轻微的时点泄漏在正式信号构建阶段应替换为滚动分位数。七、代码质量标准符合度与依赖分析7.1 与书籍标准的符合度标准符合度说明Polars-first✅ 完全除可视化边界外无 pandas冻结配置数据类✅ 完全所有 notebook 均采用该模式基于时间的 join✅ 完全远期收益不使用.shift()数据契约文档化✅ 完全每个 notebook 均有契约表输出仅限figures/✅ 完全无临时文件落盘章节正文不含代码✅ 完全按名称引用 notebookTEST 模式支持⚠️ 部分并非所有 notebook 都有显式 TEST 守卫7.2 外部依赖# Core polars # DataFrames主 numpy # 数值运算 pandas # 仅边界转换 plotly # 可视化 # Domain scipy.stats # 统计检验 IPython.display # Jupyter 渲染 # ML4T utils # DATA_DIR、路径 ml4t.data.providers # AQR、Fama-FrenchPolars-first、pandas 仅限可视化边界是这份审查报告反复强调的架构纪律pandas 仅在需要matplotlib/scipy互操作时出现转换只发生在边界处核心计算全部由 Polars 的惰性 API 承担。运行方式方面README.md 给出当前仓库的推荐执行方式# 仓库根目录执行 uv run python 06_strategy_definition/notebook.py # 测试模式通过 Papermill 缩减数据 uv run pytest tests/test_notebooks.py -v -k 06_strategy_definition这解释了 3.1 节中tags[parameters]参数区的作用正常执行使用生产默认值CI 测试时由 Papermill 注入缩减数据集的覆盖参数。八、改进建议、风险区域与总结8.1 改进建议按优先级优先级 1代码细节改进为 notebook 增加__all__导出支持模块级复用__all__ [EtfExplorationConfig, calculate_momentum_score]抽取公共工具到共享模块_compute_forward_returns_*系列函数与_event_cooldown_filter在多个 notebook 中重复出现应上移到utils/exploration.py为旧版etf_momentum.md增加 catalog 条目或直接移除明确规范版本。优先级 2文档增强在 README 增加 notebook 执行顺序说明文档化 term sheet 命名约定{dataset}__{strategy_type}.md。优先级 3测试覆盖为calculate_mean_return_tstat()、calculate_sharpe_stats()Lo 2002 SE、_event_cooldown_filter()增加单元测试对照已知数值与边界情况增加数据契约校验测试验证 parquet 模式与文档化契约一致检查预期列名与 dtype。值得注意第 3 条数据契约校验的建议在当前仓库中已经部分落地——tests/test_etf_skip_recent_momentum.py 正是以从 notebook 中抽取真实函数 断言可复现行为的方式补上了动量定义的可测试性。8.2 风险区域低风险可接受区域观察缓解pandas 边界matplotlib/scipy 需要 pandas仅边界转换影响最小全局 winsorization使用全样本分位数已文档化为仅探索使用轮动模拟中的循环逐月循环为清晰起见教学目的可接受中等风险需监控区域观察缓解重复 term sheetetf_momentum.md与etf_momentum__*.md并存澄清规范版本硬编码魔法数字notebook 正文中的部分阈值移入配置数据类缺少类型标注部分辅助函数类型不全为生产复用补齐8.3 总结这份代码库为什么值得作为策略预定义的标准范本综合报告结论策略定义章节代码库体现了四点示范价值清晰的关注点分离数据契约 → 配置 → 分析 → 总结每层职责单一、边界明确正确的统计工具Newey-West HAC 用于因子发现、Lo Sharpe 标准误用于绩效评估、基于时间的远期收益避免缺口误判工具与问题严格匹配时点正确性纪律滚动 z-score、宏观数据滞后处理、标签缓冲与特征缓冲从源头杜绝未来函数版本化产物Term Sheet 作为结构化文档进入版本控制使策略规格本身成为可 diff、可审计、可回滚的一等公民。该章节的核心方法论在演进后的 README.md 中凝练为一句可执行的原则历史上有效的测试要能说明未来的行为就必须把策略当作在决策时点定义、并像实盘一样评估的可执行决策过程——假说驱动探索、冻结配置、事件研究冷却与可证伪假说正是把这一原则落到代码层面的完整工具箱。报告最终评价为出版就绪仅需小幅清理其改进建议抽取公共工具、澄清命名、补齐统计函数测试也是任何同类策略研究代码库可以直接复用的治理清单。本文以 06_strategy_definition/exploration.md 为骨架结合当前仓库 06_strategy_definition/ 下的 notebook 源码、tests/test_etf_skip_recent_momentum.py 与 17_portfolio_construction/05_factor_allocation_evidence.py 中的统计实现交叉印证报告中记录的 Chapter 5 时期目录结构如code/、term_sheets/属于分析时的快照当前仓库中该章节已演进为 Chapter 6 的 3-notebook 结构两者以演进关系对应不构成矛盾。【免费下载链接】machine-learning-for-tradingCode for Machine Learning for Trading, 3rd edition — from data sourcing to live execution.项目地址: https://gitcode.com/GitHub_Trending/ma/machine-learning-for-trading创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
