rangebar-eval-metrics

区间棒评估指标

用于评估区间棒（基于价格的采样）数据的先进指标机器可读参考资料和计算脚本。

何时使用此技能

适用于以下情况：

• 评估机器学习模型在区间棒数据上的表现
• 计算具有非 IID 棒序列的夏普比率
• 运行 Walk-Forward Optimization 指标分析
• 计算 PSR、DSR 或 MinTRL 统计检验
• 根据折结果生成评估报告

快速入门

# Compute metrics from predictions + actuals
python scripts/compute_metrics.py --predictions preds.npy --actuals actuals.npy --timestamps ts.npy

# Generate full evaluation report
python scripts/generate_report.py --results folds.jsonl --output report.md

指标层级

层级	用途	指标	计算范围
主要（5 项）	研究决策	weekly_sharpe、hit_rate、cumulative_pnl、n_bars、positive_sharpe_rate	按折 + 汇总
次要/风险（5 项）	补充背景	max_drawdown、bar_sharpe、return_per_bar、profit_factor、cv_fold_returns	按折
机器学习质量（3 项）	预测健康度	ic、prediction_autocorr、is_collapsed	按折
诊断（5 项）	最终验证	psr、dsr、autocorr_lag1、effective_n、binomial_pvalue	仅汇总
扩展风险（5 项）	深度风险分析	var_95、cvar_95、omega_ratio、sortino_ratio、ulcer_index	按折（可选）

区间棒为何需要特殊处理

区间棒违反标准 IID 假设：

1. 持续时间不定：棒的形成取决于价格波动，而非时间
2. 自相关：高波动时期会形成棒的聚集 → 时间相关性
3. 信息量不恒定：波动期间棒数增加 = 每日信息量增加

标准解决方案：在计算夏普比率之前，通过 _group_by_day() 按日聚合。

参考资料

核心参考文件

主题	参考文件
夏普比率计算	sharpe-formulas.md
风险指标（VaR、Omega、Ulcer）	risk-metrics.md
机器学习预测质量（IC、自相关）	ml-prediction-quality.md
加密货币市场注意事项	crypto-markets.md
时间聚合规则	temporal-aggregation.md
指标 JSON Schema	metrics-schema.md
反模式（交易成本）	anti-patterns.md
2025-2026 年先进技术（SHAP、BOCPD 等）	sota-2025-2026.md
实例演示（BTC、EUR/USD）	worked-examples.md
结构化日志（NDJSON）	structured-logging.md

相关技能

技能	关联
adaptive-wfo-epoch	使用 weekly_sharpe、psr、dsr 计算 WFE

依赖项

pip install -r requirements.txt
# Or: pip install numpy>=1.24 pandas>=2.0 scipy>=1.10

关键公式

按日聚合的夏普比率（主要指标）

def weekly_sharpe(pnl: np.ndarray, timestamps: np.ndarray) -> float:
    """Sharpe with daily aggregation for range bars."""
    daily_pnl = _group_by_day(pnl, timestamps)  # Sum PnL per calendar day
    if len(daily_pnl) < 2 or np.std(daily_pnl) == 0:
        return 0.0
    daily_sharpe = np.mean(daily_pnl) / np.std(daily_pnl)
    # For crypto (7-day week): sqrt(7). For equities: sqrt(5)
    return daily_sharpe * np.sqrt(7)  # Crypto default

信息系数（预测质量）

from scipy.stats import spearmanr

def information_coefficient(predictions: np.ndarray, actuals: np.ndarray) -> float:
    """Spearman rank IC - captures magnitude alignment."""
    ic, _ = spearmanr(predictions, actuals)
    return ic  # Range: [-1, 1]. >0.02 acceptable, >0.05 good, >0.10 excellent

概率夏普比率（统计验证）

from scipy.stats import norm

def psr(sharpe: float, se: float, benchmark: float = 0.0) -> float:
    """P(true Sharpe > benchmark)."""
    return norm.cdf((sharpe - benchmark) / se)

年化系数

市场	日 → 周	日 → 年	原因
加密货币（24/7）	sqrt(7) = 2.65	sqrt(365) = 19.1	每周 7 个交易日
股票	sqrt(5) = 2.24	sqrt(252) = 15.9	每周 5 个交易日

加密货币市场绝不能使用 sqrt(252)。

关键：时段筛选会改变年化计算

视图	筛选条件	days_per_week	原因
时段筛选（伦敦－纽约）	工作日 08:00-16:00	sqrt(5)	按股票市场方式交易
所有 K 线（未筛选）	无	sqrt(7)	加密货币全天候交易

对经过时段筛选的数据使用 sqrt(7)，会使夏普比率高估约 18%！

详细原因请参阅 crypto-markets.md。

双视图指标

为进行全面分析，请用两种视图计算指标：

1. 时段筛选（伦敦 08:00 至纽约 16:00）：主要策略评估
2. 所有 K 线：市场状态检测、数据质量诊断

学术参考文献

概念	引用
修正夏普比率	Bailey & López de Prado (2014)
非正态分布下夏普比率的标准误	Mertens (2002)
夏普比率统计	Lo (2002)
Omega 比率	Keating & Shadwick (2002)
Ulcer 指数	Peter Martin (1987)

决策框架

通过标准（研究）

go_criteria:
  - positive_sharpe_rate > 0.55
  - mean_weekly_sharpe > 0
  - cv_fold_returns < 1.5
  - mean_hit_rate > 0.50

发表标准

publication_criteria:
  - binomial_pvalue < 0.05
  - psr > 0.85
  - dsr > 0.50 # If n_trials > 1

脚本

脚本	用途
scripts/compute_metrics.py	根据预测值/实际值计算所有指标
scripts/generate_report.py	根据折叠结果生成 Markdown 报告
scripts/validate_schema.py	根据架构验证指标 JSON

修复措施（2026-01-19 多 Agent 审计）

根据一项由 12 个子 Agent 进行的对抗性审计，应用了以下修复：

问题	根本原因	修复措施	来源
weekly_sharpe=0	预测值恒定	模型坍塌检测 + 架构修复	model-expert
IC=None	预测值方差为零	对恒定值返回 1.0（语义正确）	model-expert
prediction_autocorr=NaN	除以零	当 std < 1e-10 时进行保护，返回 1.0	model-expert
Ulcer 指数除以零	峰值权益 = 0	使用 np.where(peak > 1e-10, ...) 进行保护	risk-analyst
Omega/Profit Factor 不可靠	样本过少	min_days 参数（默认值：5）	robustness-analyst
BiLSTM 均值坍塌	架构过小	hidden_size: 16→48，dropout: 0.5→0.3	model-expert
profit_factor=1.0 (n_bars=0)	提前返回了错误值	无数据可计算比率时返回 NaN	risk-analyst

模型坍塌检测

# ALWAYS check for model collapse after prediction
pred_std = np.std(predictions)
if pred_std < 1e-6:
    logger.warning(
        f"Constant predictions detected (std={pred_std:.2e}). "
        "Model collapsed to mean - check architecture."
    )

推荐的 BiLSTM 架构

# BEFORE (causes collapse on range bars)
HIDDEN_SIZE = 16
DROPOUT = 0.5

# AFTER (prevents collapse)
HIDDEN_SIZE = 48  # Triple capacity
DROPOUT = 0.3     # Less aggressive regularization

完整实现细节请参阅参考文档。

---

故障排除

问题	原因	解决方案
weekly_sharpe 为 0	预测结果恒定	检查模型是否发生坍塌，并增大 hidden_size
IC 返回 None	预测结果方差为零	模型已坍塌——检查架构
prediction_autocorr 为 NaN	除以零	在自相关计算中，对 std < 1e-10 添加保护
Ulcer Index 除法错误	峰值权益为零	添加保护：np.where(peak > 1e-10, ...)
profit_factor = 1.0	未处理任何 bar	当 n_bars 为 0 时返回 NaN
Sharpe 虚高 18%	数据年化方式错误	会话筛选数据使用 sqrt(5)，全天候数据使用 sqrt(7)
未计算 PSR/DSR	缺少 scipy	安装：pip install scipy
未解析时间戳	格式错误	确保使用 Unix 时间戳，而非 datetime 字符串