CarrotQuant

CarrotQuant 是高性能全栈量化交易、金融数据流水线与量化分析回测框架的主入口元包 (Umbrella Package)，聚合了数据中台、回测内核与可视化分析引擎三大核心组件。

🏗️ 架构全景

                                pip install carrotquant (默认安装全套能力)
                                                   │
         ┌─────────────────────────────────────────┼─────────────────────────────────────────┐
         ▼                                         ▼                                         ▼
┌─────────────────────────────┐       ┌─────────────────────────────┐       ┌─────────────────────────────┐
│    carrotquant-engine       │       │      carrotquant-data       │       │    carrotquant-analytics    │
│  (Numba 极速回测与撮合引擎)   │       │  (金融数据增量同步与持久化)   │       │  (量化指标计算与交互式报告)  │
│  - 事件驱动与向量化撮合     │       │  - Baostock / 东财 / 通达信 │       │  - 纯函数复利/回撤/信号指标 │
│  - 物理切片严格防未来函数   │       │  - 列式存储 (Parquet / CSV) │       │  - Plotly 金融级图表工厂    │
│  - 多空交易与滑点/税费模型  │       │  - React Web 金融终端 & CLI │       │  - 离线 HTML/Excel/MD 报告  │
└─────────────────────────────┘       └─────────────────────────────┘       └─────────────────────────────┘

📦 安装 (Installation)

环境要求：Python >= 3.12（支持 Python 3.12 / 3.13 / 3.14+）。

1. 默认安装 (推荐，开箱即用)

# 默认安装 carrotquant-engine、carrotquant-data 与 carrotquant-analytics 全套组件
pip install carrotquant

# 或使用 uv 安装
uv add carrotquant

2. 细分可选安装 (Extras)

# 仅安装核心回测引擎
pip install carrotquant[engine]

# 仅安装数据同步与 Web 终端
pip install carrotquant[data]

# 仅安装量化指标与可视化报告引擎
pip install carrotquant[analytics]

# 显式安装全套依赖
pip install carrotquant[all]

🚀 快速开始

1. 数据同步与 Web 终端管理

通过命令行工具 cqdata（安装 carrotquant 后自动就绪）：

# 启动本地 Web 数据终端与 REST API 服务
cqdata server --port 8888 --open

# 触发 A 股日线数据自动增量同步
cqdata sync -t ashare.kline.1d.raw.baostock

2. 数据读取、策略回测与交互式报告全流程

# 方式 A：通过主元包分层结构化调用
import carrotquant as cq

# 1. (数据层) 读取本地清洗好的 Parquet/CSV 数据
df = cq.data.read(
    table_id="ashare.kline.1d.raw.baostock",
    symbols=["sh.600000", "sz.000001"],
    start_date="2023-01-01",
    end_date="2023-12-31"
)

# 2. (策略层) 定义事件驱动双均线策略
@cq.engine.strategy
def dual_ma_strategy(ctx: cq.engine.BarContext):
    for i in range(ctx.n_symbols):
        if not ctx.is_tradable[i]:
            continue

        # 读取后复权历史收盘价
        c_hist = ctx.adj.close_history[-20:, i]
        ma5 = c_hist[-5:].mean()
        ma20 = c_hist[-20:].mean()

        if ma5 > ma20 and ctx.positions[i] == 0:
            ctx.buy(symbol_idx=i, amount=100)
        elif ma5 < ma20 and ctx.positions[i] > 0:
            ctx.sell(symbol_idx=i, amount=ctx.positions[i])

# 3. (引擎层) 初始化并启动 Numba 高性能回测
data_stream = cq.engine.ColumnDataLoader.scan_parquet_chunks(
    path="data/parquet/ashare.kline.1d.raw.baostock",
    partition_by="year"
)

engine = cq.engine.Engine(
    initial_cash=1_000_000.0,
    fee_rate=0.0003,
    stamp_duty=0.0005,
    slippage=0.0001,
    matching_mode="close"
)

results = engine.run(strategy=dual_ma_strategy, data=data_stream)

# 4. (分析层) 基于协议无缝装配并一键导出离线交互式回测报告
report = cq.analytics.Report.from_engine_result(results)
report.to_html("backtest_report.html")  # 自包含离线单页报告
report.to_excel("backtest_report.xlsx")  # 多 Sheet 格式化 Excel 报告
print(report.to_text())  # 终端 ASCII / Markdown 绩效排版

方式 B：按需直接使用标准子命名空间导入：

from cq.data import read, ashare
from cq.engine import Engine, strategy, BarContext, ColumnDataLoader
from cq.analytics import Report, ReportComparer, metrics, charts, theme

🔗 生态子项目链接

• 回测引擎源码：carrotquant-engine
• 数据管理源码：carrotquant-data
• 量化分析源码：carrotquant-analytics

📝 许可证 (License)

本项目遵循 Apache License 2.0。