Back to Details

residual-edge-analyzer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Residual Edge Analyzer

剩余超额收益分析器

Overview

概述

Test whether a strategy's apparent performance survives explicit comparison with predeclared baseline return series. Produce an auditable JSON artifact and a concise Markdown report without fetching data or changing trading exposure.
Treat this as a falsification gate after 
backtest-expert
, not as trade authorization.
测试策略的表观业绩是否能通过与预先设定的基准收益序列进行明确对比而成立。无需获取数据或改变交易敞口，即可生成可审计的JSON产物和简洁的Markdown报告。
将此视为
backtest-expert
之后的验证关卡，而非交易授权依据。

Prerequisites

前提条件

  • Use Python 3.9+.
  • Prepare one CSV containing an ISO date, strategy return, and every baseline return on the same row.
  • Prepare a JSON specification following references/input-contract.md.
  • Supply actual period returns. Do not substitute CAGR, Sharpe, cumulative P&L, or other summary metrics.
  • 使用Python 3.9及以上版本。
  • 准备一份CSV文件，包含ISO日期、策略收益，且每一行对应所有基准收益。
  • 遵循references/input-contract.md准备JSON规格文件。
  • 提供实际的期间收益。请勿用CAGR、夏普比率、累计盈亏或其他汇总指标替代。

Workflow

工作流程

1. Define the question before inspecting results

1. 在查看结果前明确问题

State the claimed independent edge in one sentence. Select a primary baseline that is a plausible simple copy of the strategy, then select at least one alternate baseline model.
Record these declarations in the config:
  • baseline_selection: predeclared
  • strategy_return_basis
    and 
    baseline_return_basis
    : both 
    gross
    or both 
    net
  • analysis_scope
    : 
    out_of_sample
    , 
    live
    , or 
    in_sample
  • universe_data
    : 
    point_in_time
    , 
    current_constituents
    , or 
    not_applicable
Every declaration is mandatory for a decision-grade verdict. Omitting one is treated as undeclared, not as benign, and drops the report to 
REVIEW_REQUIRED
. 
not_applicable
exists so that a baseline with no universe membership can be declared explicitly rather than left blank.
Do not choose a baseline because it gives the preferred residual result.
用一句话说明声称的独立超额收益。选择一个合理的、可简单复制策略的主基准，然后至少选择一个替代基准模型。
在配置文件中记录这些声明：
  • baseline_selection: predeclared
  • strategy_return_basis
    和
    baseline_return_basis
    ：均设为
    gross
    或均设为
    net
  • analysis_scope
    : 
    out_of_sample
    、
    live
    或
    in_sample
  • universe_data
    : 
    point_in_time
    、
    current_constituents
    或
    not_applicable
所有声明对于决策级结论都是必需的。遗漏任何一项将被视为未声明，而非无关紧要，报告状态会降至
REVIEW_REQUIRED
。
not_applicable
的存在是为了明确声明无标的池成员的基准，而非留空。
请勿因基准能给出偏好的剩余收益结果而选择它。

2. Validate the return-series contract

2. 验证收益序列合约

Require:
  • unique ISO dates;
  • finite numeric returns greater than -100%;
  • identical frequency and cost basis across strategy and baselines;
  • point-in-time membership for same-universe equal-weight or momentum baselines;
  • regime labels defined independently of the loss periods being explained.
Stop if the input lacks a dated strategy return series. Report summary-only input as insufficient rather than inventing observations.
要求：
  • 唯一的ISO日期；
  • 有限的数值收益，且大于-100%；
  • 策略与基准的频率和成本基准一致；
  • 同一标的池的等权重或动量基准需采用时点成员数据；
  • 市场状态标签的定义独立于所解释的亏损时段。
如果输入缺少带日期的策略收益序列，请停止分析。仅基于汇总指标的输入应报告为数据不足，而非自行生成观测值。

3. Run the analyzer

3. 运行分析器

bash
python3 skills/residual-edge-analyzer/scripts/analyze_residual_edge.py \
  --input reports/strategy_returns.csv \
  --config reports/residual_edge_config.json \
  --output-json reports/residual_edge_report.json \
  --output-markdown reports/residual_edge_report.md
The script runs the predeclared primary model and all sensitivity models in one execution. It uses an intercept OLS model and HAC/Newey-West standard errors. It reports the residual edge ratio as annualized alpha divided by annualized residual volatility; do not calculate a Sharpe ratio from raw OLS residual mean because an intercept makes that mean zero.
bash
python3 skills/residual-edge-analyzer/scripts/analyze_residual_edge.py \
  --input reports/strategy_returns.csv \
  --config reports/residual_edge_config.json \
  --output-json reports/residual_edge_report.json \
  --output-markdown reports/residual_edge_report.md
该脚本会一次性运行预先设定的主模型和所有敏感性模型。它使用带截距的OLS模型和HAC/Newey-West标准误。报告的剩余超额收益比率为年化Alpha除以年化剩余波动率；请勿从原始OLS剩余均值计算夏普比率，因为截距会使该均值为零。

4. Interpret the evidence

4. 解读证据

Use the four statuses as diagnostic labels:
  • RESIDUAL_EDGE
    : alpha, residual edge ratio, and rolling stability clear configured thresholds.
  • BASELINE_EXPLAINED
    : baseline R-squared is high while residual evidence is weak.
  • RESIDUAL_FRAGILE
    : results fail one or more robustness gates or change across declared baseline models. Also use this status when rolling analysis is disabled, unavailable, incomplete, or no sensitivity model was supplied.
  • INSUFFICIENT_EVIDENCE
    : the sample is below the configured minimum.
Read 
decision_eligibility
separately. A statistically interesting result remains 
REVIEW_REQUIRED
when critical provenance, cost-basis, sample, or multicollinearity warnings exist, when rolling evidence is unavailable, or when no alternate baseline was tested.
Inspect:
  1. primary and sensitivity-model status;
  2. annualized alpha and HAC t-stat;
  3. residual edge ratio and residual autocorrelation;
  4. rolling alpha stability;
  5. VIF for multi-factor models;
  6. active-return breakdown across predeclared regimes.
使用四种状态作为诊断标签：
  • RESIDUAL_EDGE
    ：Alpha、剩余超额收益比率和滚动稳定性均达到配置的阈值。
  • BASELINE_EXPLAINED
    ：基准的R平方值较高，而剩余收益证据薄弱。
  • RESIDUAL_FRAGILE
    ：结果未通过一个或多个稳健性检验，或在不同既定基准模型间存在差异。当滚动分析被禁用、不可用、不完整，或未提供敏感性模型时，也使用此状态。
  • INSUFFICIENT_EVIDENCE
    ：样本量低于配置的最小值。
单独查看
decision_eligibility
状态。当存在关键来源、成本基准、样本量或多重共线性警告，滚动证据不可用，或未测试替代基准时，即使统计结果有趣，仍会标记为
REVIEW_REQUIRED
。
检查以下内容：
  1. 主模型和敏感性模型的状态；
  2. 年化Alpha和HAC t统计量；
  3. 剩余超额收益比率和剩余自相关性；
  4. 滚动Alpha稳定性；
  5. 多因子模型的VIF值；
  6. 既定市场状态下的主动收益分解。

5. Hand off findings

5. 交付研究结果

  • Send baseline-choice, OOS, and stability findings back to 
    backtest-expert
    .
  • Send recurring residual failure regimes to 
    signal-postmortem
    .
  • Pass only evidence and operating constraints to 
    trade-performance-coach
    .
  • Never change position size, exposure, or orders automatically.
  • 将基准选择、样本外表现和稳定性结果反馈给
    backtest-expert
    。
  • 将反复出现的剩余收益失效状态发送给
    signal-postmortem
    。
  • 仅将证据和操作约束传递给
    trade-performance-coach
    。
  • 切勿自动调整仓位大小、敞口或订单。

Boundaries

边界说明

  • Do not call this holdings-based contribution analysis. Brinson allocation, selection, and interaction effects require historical holdings, benchmark weights, and constituent returns.
  • Do not claim stock-selection alpha from a market-index-only baseline.
  • Do not build equal-weight baselines from current constituents and label them point-in-time.
  • Do not interpret in-sample residual edge as confirmed alpha.
  • Do not mine many regime definitions after seeing losses. Predeclare a small set and confirm findings out of sample.
  • Do not assume high R-squared makes a strategy worthless; capacity, tail behavior, costs, and implementation value require separate evidence.
  • 请勿将此称为基于持仓的贡献分析。Brinson配置、选择和交互效应需要历史持仓、基准权重和成分股收益。
  • 请勿仅基于市场指数基准就声称选股Alpha。
  • 请勿用当前成分股构建等权重基准并标记为时点数据。
  • 请勿将样本内剩余超额收益解读为已确认的Alpha。
  • 请勿在看到亏损后挖掘大量市场状态定义。预先设定少量状态，并在样本外验证结果。
  • 请勿假设高R平方意味着策略毫无价值；容量、尾部表现、成本和实现价值需要单独的证据支持。

Resources

资源

  • scripts/analyze_residual_edge.py
    — deterministic CSV-to-JSON/Markdown analyzer.
  • references/input-contract.md
    — CSV/config contract and runnable example.
  • references/methodology.md
    — statistical definitions, interpretation, and limitations.
  • scripts/analyze_residual_edge.py
    — 确定性CSV转JSON/Markdown分析器。
  • references/input-contract.md
    — CSV/配置合约及可运行示例。
  • references/methodology.md
    — 统计定义、解读及局限性说明。