用途
Range Bar Evaluation Metrics 是一个用于量化交易的评估指标技能，提供机器可读的参考文档与计算脚本，用于评估 Range Bar（基于价格采样）数据上的指标。适用场景包括：评估机器学习模型在 Range Bar 数据上的表现；在非 IID 的 bar 序列上计算夏普比率；执行 Walk-Forward Optimization（WFO）指标分析；计算 PSR、DSR、MinTRL 统计检验；从 fold 结果生成评估报告。
主要能力
指标分为若干层级：
- 主指标（5 个）：weekly_sharpe、hit_rate、cumulative_pnl、n_bars、positive_sharpe_rate，用于研究决策，按 fold 加聚合计算。
- 次要与风险指标（5 个）：max_drawdown、bar_sharpe、return_per_bar、profit_factor、cv_fold_returns，按 fold 计算。
- 机器学习质量指标（3 个）：ic、prediction_autocorr、is_collapsed，按 fold 计算。
- 诊断指标（5 个）：psr、dsr、autocorr_lag1、effective_n、binomial_pvalue，仅聚合计算。
- 扩展风险指标（5 个）：var_95、cvar_95、omega_ratio、sortino_ratio、ulcer_index，按 fold 可选计算。
使用方式
快速开始命令： 从预测值与实际值计算指标： python scripts/compute_metrics.py --predictions preds.npy --actuals actuals.npy --timestamps ts.npy
生成完整评估报告： python scripts/generate_report.py --results folds.jsonl --output report.md
脚本包括：scripts/compute_metrics.py（从预测/实际值计算全部指标）、scripts/generate_report.py（从 fold 结果生成 Markdown 报告）、scripts/validate_schema.py（按 schema 校验指标 JSON）。
依赖安装： pip install -r requirements.txt 或：pip install numpy>=1.24 pandas>=2.0 scipy>=1.10
为什么 Range Bar 需要特殊处理
资料指出 Range Bar 违反标准 IID 假设：
- 变时长：bar 基于价格变动而非时间形成；
- 自相关：高波动时段 bar 聚集，导致时间相关性；
- 信息量不恒定：波动期间 bar 更多，每天信息量不同。 规范性解决方案：在计算夏普比率前，通过 _group_by_day() 进行按日聚合。
关键公式与年化
按日聚合夏普（主指标）使用 weekly_sharpe 函数，按日历日汇总 PnL，再计算日均值/标准差，并乘以年化因子。加密市场使用 sqrt(7)，股票市场使用 sqrt(5)。资料明确提示：加密市场绝不使用 sqrt(252)。
会话过滤会改变年化因子：会话过滤（伦敦-纽约，工作日 08:00-16:00）使用 sqrt(5)；全 bar（未过滤）使用 sqrt(7)。对会话过滤数据使用 sqrt(7) 会使夏普比率高估约 18%。资料建议为全面分析计算双视图指标：会话过滤视图（主要策略评估）与全 bar 视图（regime 检测、数据质量诊断）。
信息系数（IC）使用 Spearman 秩相关，范围 [-1, 1]，大于 0.02 可接受，大于 0.05 良好，大于 0.10 优秀。概率夏普比率（PSR）定义为 P(true Sharpe > benchmark)。
决策框架
研究 Go 标准：positive_sharpe_rate > 0.55，mean_weekly_sharpe > 0，cv_fold_returns < 1.5，mean_hit_rate > 0.50。 发表标准：binomial_pvalue < 0.05，psr > 0.85，若 n_trials > 1 则 dsr > 0.50。
模型坍缩检测与修复
资料建议在预测后始终检查模型坍缩：若预测值标准差小于 1e-6，提示模型坍缩至均值，需检查架构。推荐的 BiLSTM 架构调整：HIDDEN_SIZE 由 16 改为 48（三倍容量），DROPOUT 由 0.5 改为 0.3（降低正则化强度）。
已知修复（2026-01-19 多智能体审计）
包括：weekly_sharpe=0 因恒定预测，改为模型坍缩检测与架构修复；IC=None 因预测零方差，改为对常数返回 1.0；prediction_autocorr=NaN 因除零，增加 std < 1e-10 保护并返回 1.0；Ulcer Index 除零因峰值权益为 0，使用 np.where(peak > 1e-10, ...) 保护；Omega/利润因子不可靠因样本太少，增加 min_days 参数（默认 5）；profit_factor=1.0（n_bars=0）改为在无数据时返回 NaN。
参考文档主题
核心参考文件涵盖：夏普比率计算、风险指标（VaR、Omega、Ulcer）、机器学习预测质量（IC、自相关）、加密市场考量、时间聚合规则、指标 JSON schema、反模式（交易成本）、SOTA 2025-2026（SHAP、BOCPD 等）、实际示例（BTC、EUR/USD）、结构化日志（NDJSON）。
关联与依赖
相关技能：adaptive-wfo-epoch（使用 weekly_sharpe、psr、dsr 进行 WFE 计算）。
限制与缺失信息
资料未提供该技能的具体收费、价格、平台兼容范围或适用范围之外的保证。上述指标阈值与年化因子为资料给出的参考值，实际使用需结合具体市场与数据视图。