CarrotQuant Analytics (cq.analytics)

量化指标分析、可视化图表工厂、多维策略报告容器与多策略横向对比引擎。

核心定位

CarrotQuant Analytics (cq.analytics) 是 CarrotQuant 生态中负责指标计算、可视化图表构建、策略回测报告生成与多策略横向评测的核心分析库。

graph TD
    DATA["carrotquant-data (cq.data)<br/>行情价格与特征因子数据源"] -->|行情价格 / 特征因子| ANALYTICS["carrotquant-analytics (cq.analytics)<br/>指标算子 + 基础图表 + 策略报告 + 多策略对比引擎"]
    DATA -->|多标的行情时序| ENGINE["carrotquant-engine (cq.engine)<br/>事件驱动与向量化撮合执行内核"]
    ENGINE -->|净值曲线 / 交易流水 / 信号事件| ANALYTICS

    ANALYTICS --> OUT1["交互式 HTML 报告 (自包含离线单文件 + 客户端拖拽重绘)"]
    ANALYTICS --> OUT2["结构化 Excel 报告 (多 Sheet 导出)"]
    ANALYTICS --> OUT3["Markdown / 终端 ASCII 文本报告"]
    ANALYTICS --> OUT4["原始数据快照 (结构化 JSON Dump/Load)"]
    ANALYTICS --> OUT5["多策略横向对比看板 (参数 Diff / 收益相关性 / 指标横评)"]

核心特性

• 纯净依赖架构：基于 polars, plotly, jinja2, pyyaml, xlsxwriter，独立自洽，不强绑定外部生态包；
• 单一事实来源 (SSOT)：由强类型 ReportSnapshot 数据契约统一驱动 HTML、Excel、Markdown 与 JSON 多通道输出；
• 标准金融几何复利：全面支持 CAGR、夏普比率、索提诺比率、卡玛比率、水下回撤区间分析与月历复利透视；
• 多标的 T+N 前向收益分析体系：提供 ForwardReturnAnalysis 与 ForwardReturnResult，一键生成前向收益矩阵、IC 衰减时序与胜率衰减图；
• 4 类金融基础图表工厂：折线图 (支持双 Y 轴)、涨跌双色柱状图、矩阵热力图、收益分布直方图；
• 自包含离线 HTML 报告：单文件内联 Plotly.js 与客户端动态重绘引擎，支持拖入 .json 报告快照实时重绘；
• 多策略横向对比引擎：ReportComparer 支持同轴资金曲线叠加、核心指标横评、参数 Diff 与收益相关性矩阵。

快速上手

1. 代码驱动生成报告

import polars as pl
from cq.analytics import Report, charts, metrics, ColorConvention

# 1. 初始化报告容器
report = Report(
    strategy_name="DualMA_Trend",
    report_id="rep_20260825_01",
    params={"fast_period": 5, "slow_period": 20},
    color_convention=ColorConvention.CN,
)

# 2. 计算并装载综合指标 (几何复利)
summary = metrics.performance_summary(equity_df, trades=trades_df["pnl"])
report.add_metrics(summary)

# 3. 构造并装载图表
fig = charts.line(equity_df, x="date", y="equity", title="策略资金曲线")
report.add_figure(fig, figure_id="chart_equity", title="资金曲线")

# 4. 多通道导出
report.save_html("output/report.html")
report.save_excel("output/report.xlsx")
report.save_markdown("output/report.md")
report.save_json("output/rep_snapshot.json")

2. 声明式 YAML 模板驱动

from cq.analytics import Report

report = Report.from_template(
    "examples/sample_template.yaml",
    data={"equity": equity_df, "trades": trades_df},
)
report.save_html("output/yaml_report.html")

3. 多策略横向对比

from cq.analytics import ReportComparer

# 扫描快照目录自动生成对比看板
comparer = ReportComparer.from_dir("output/", match="*.json")
comparer.save_html("output/comparison_report.html")
comparer.save_excel("output/comparison_report.xlsx")

4. 多标的 T+N 前向收益分析

from cq.analytics import compute_forward_returns

# 传入多标的信号与行情价格
result = compute_forward_returns(signals_df, prices_df, periods=(1, 3, 5, 10, 20))

# 导出衰减图与结构化分析表格
fig_decay = result.to_decay_figure()
fig_heatmap = result.to_heatmap_figure()
table_spec = result.to_table()

5. 全局主题与涨跌配色配置

import cq.analytics as cqa
from cq.analytics import Theme, ColorConvention

# 全局切换为暗色主题与国际绿涨红跌配色
cqa.set_theme(theme=Theme.DARK, convention=ColorConvention.INTL)