Metadata-Version: 2.5
Name: carrotquant-analytics
Version: 0.1.0
Summary: Quantitative metrics calculation, charts factory, strategy reports and comparison engine.
Author: CarrotQuant Team
Requires-Python: >=3.12
Requires-Dist: jinja2>=3.1.6
Requires-Dist: plotly>=6.9.0
Requires-Dist: polars>=1.44.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: xlsxwriter>=3.2.9
Description-Content-Type: text/markdown

# CarrotQuant Analytics (`cq.analytics`)

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

[![Python Version](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

---

## 核心定位

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

```mermaid
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. 代码驱动生成报告

```python
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 模板驱动

```python
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. 多策略横向对比

```python
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 前向收益分析

```python
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. 全局主题与涨跌配色配置

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

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