kepler-metric | 金融风险指标计算库

概述

kepler-metric 是一个用于计算金融风险和绩效指标的 Python 库。基于 Quantopian Inc. 开发的 empyrical，经过现代化重构，为量化金融专业人士和研究人员提供了全面的工具集。

特性

• 现代化架构：模块化设计，清晰的代码结构
• 完整的指标：超过 50 个金融指标，包括收益、风险、风险调整收益和市场关系
• DataFrame 支持：当输入为 DataFrame 时，所有函数返回带列名的 pandas Series
• 灵活输入：支持 pandas Series/DataFrame 和 numpy 数组
• 类型注解：完整的 Python 3.10+ 类型提示
• Portfolio 类：高级接口，一次计算多个指标

安装

pip install kepler-metric

注意：虽然 PyPI 包名是 kepler-metric，但导入时仍然使用 kepler.metric：

import kepler.metric

快速开始

import pandas as pd
import numpy as np
from kepler.metric import (
    max_drawdown, sharpe, total_return,
    volatility, calmar, Portfolio, analyze
)

# 创建示例收益率数据
np.random.seed(42)
returns = pd.DataFrame(
    np.random.normal(0.001, 0.02, (252, 3)),
    columns=['Strategy_A', 'Strategy_B', 'Strategy_C']
)

# 计算各种指标
metrics = {
    'Total Return': total_return(returns),
    'Max Drawdown': max_drawdown(returns),
    'Sharpe': sharpe(returns),
    'Volatility': volatility(returns),
    'Calmar': calmar(returns)
}

# 打印结果
for metric, values in metrics.items():
    print(f"\n{metric}:")
    print(values)

使用 Portfolio 类

Portfolio 类提供了一种更便捷的方式来计算多个指标：

from kepler.metric import Portfolio

# 创建 Portfolio 实例
# 注意：risk_free 是日度无风险利率，不是年度！
# 如果年化无风险利率是 2%，日度利率 = 0.02 / 252
pf = Portfolio(returns, risk_free=0.02/252)

# 计算单个指标
print(pf.sharpe())
print(pf.max_drawdown())

# 获取所有指标的摘要
summary = pf.summary()
print(summary)

# 转换为 DataFrame
df = pf.to_frame()

使用 analyze() 函数

from kepler.metric import analyze

# 一次性分析
result = analyze(
    returns,
    metrics=['sharpe', 'max_drawdown', 'total_return', 'volatility']
)
print(result)

⚠️ 重要说明

risk_free 参数

所有涉及 risk_free 的函数，该参数都是日度无风险利率，不是年度！

# ❌ 错误：传入年度 2%
sharpe(returns, risk_free=0.02)  # 结果会是负数，完全错误！

# ✅ 正确：转换为日度利率
annual_rf = 0.02  # 年化 2%
daily_rf = annual_rf / 252  # 日度利率
sharpe(returns, risk_free=daily_rf)  # 正确！

# ✅ 或者直接传 0（默认值）
sharpe(returns)  # 假设无风险利率为 0

API 参考

收益指标

风险指标

风险调整收益

市场关系

高级接口

从 0.x 迁移

如果你从旧版本 (0.x) 迁移，以下是主要的 API 变更：

DataFrame 支持

所有函数都支持 DataFrame 输入，并保留列名：

# DataFrame 输入
returns = pd.DataFrame({
    'Stock_A': [...],
    'Stock_B': [...],
    'Stock_C': [...]
})

# 返回带列名的 Series
result = sharpe(returns)
print(result)
# Stock_A    0.75
# Stock_B    0.82
# Stock_C    0.68
# dtype: float64

开发

从源码安装：

git clone https://github.com/cloudQuant/kepler.metric
cd kepler.metric
pip install -e .

运行测试：

pytest tests/

许可证

Apache License 2.0

致谢

基于 Quantopian Inc. 开发的 empyrical 库，经过现代化重构。