fincore 0.3.0

Quantitative performance and risk analytics for Python

fincore | Quantitative Performance & Risk Analytics

English · 中文 · Documentation · Contributing · Changelog · Migration Guide

---

Overview

fincore is a Python library for quantitative finance analytics — 150+ financial metrics, portfolio optimization, Monte Carlo simulation, and performance attribution. It continues the empyrical stack under active maintenance by cloudQuant.

Highlights

Feature	Description
150+ Metrics	Returns, risk, drawdown, alpha/beta, capture ratios, timing, streaks
AnalysisContext	fincore.analyze() — lazy, cached computation with JSON/HTML export
RollingEngine	Batch rolling metrics (sharpe, volatility, max_drawdown, beta) in one call
Pluggable Viz	Matplotlib, HTML, Plotly, Bokeh backends via VizBackend protocol
Portfolio Optimization	Efficient frontier, risk parity, constrained optimization
Monte Carlo	Bootstrap, scenario testing, path simulation
Performance Attribution	Brinson, Fama-French, style analysis
Lazy Imports	import fincore in ~0.04s — heavy deps load on first access
PEP 561	py.typed marker for type checker support

Installation

pip install fincore                  # Core
pip install "fincore[viz]"           # + matplotlib, seaborn
pip install "fincore[all]"           # Everything
pip install "fincore[dev]"           # Development tools

From source:

git clone https://github.com/cloudQuant/fincore   # International
git clone https://gitee.com/yunjinqi/fincore       # China mirror
cd fincore && pip install -e ".[dev,viz]"

Quick Start

import fincore

# One-liner analysis — lazy, cached
ctx = fincore.analyze(returns, factor_returns=benchmark)

print(f"Sharpe:  {ctx.sharpe_ratio:.4f}")
print(f"Max DD:  {ctx.max_drawdown:.4f}")
print(f"Alpha:   {ctx.alpha:.6f}")

ctx.to_html(path="report.html")       # Self-contained HTML report
ctx.to_json()                          # JSON export

Classic API (drop-in empyrical replacement):

from fincore import empyrical

sharpe = empyrical.sharpe_ratio(returns, risk_free=0.02/252)
alpha, beta = empyrical.alpha_beta(returns, benchmark)
mdd = empyrical.max_drawdown(returns)

RollingEngine (batch rolling metrics):

from fincore.core.engine import RollingEngine

engine = RollingEngine(returns, factor_returns=benchmark, window=60)
results = engine.compute(['sharpe', 'volatility', 'max_drawdown', 'beta'])

Portfolio Optimization:

from fincore.optimization import efficient_frontier, risk_parity, optimize

ef = efficient_frontier(returns_df, n_points=50)
rp = risk_parity(returns_df)
w = optimize(returns_df, objective="max_sharpe")

Architecture

fincore/
├── __init__.py          # Lazy exports (Empyrical, Pyfolio, analyze)
├── empyrical.py         # Empyrical facade (150+ methods)
├── core/
│   ├── context.py       # AnalysisContext — lazy cached metrics
│   └── engine.py        # RollingEngine — batch rolling metrics
├── metrics/             # 17 metric modules (returns, risk, ratios, ...)
├── viz/                 # VizBackend protocol + backends
├── optimization/        # Efficient frontier, risk parity
├── simulation/          # Monte Carlo, bootstrap
├── attribution/         # Brinson, Fama-French, style analysis
├── risk/                # EVT, GARCH
├── report/              # HTML/PDF report generation
├── tearsheets/          # Pyfolio-style plotting
└── utils/               # Shared helpers

Testing

pytest tests/ -n 4                   # Parallel (2345 tests)
pytest tests/ --cov=fincore          # With coverage
pytest tests/test_core/              # AnalysisContext, RollingEngine, Viz

License

Apache License 2.0 — see LICENSE. Originally by Quantopian Inc., maintained by the open-source community.

---

概述

fincore 是面向量化金融的 Python 分析库 — 150+ 金融指标、组合优化、蒙特卡洛模拟和绩效归因。它延续 empyrical 分析栈，由 cloudQuant 持续维护。

核心特性

特性	说明
150+ 指标	收益、风险、回撤、Alpha/Beta、捕获比率、择时、连续统计
AnalysisContext	fincore.analyze() — 惰性计算、自动缓存，支持 JSON/HTML 导出
RollingEngine	批量滚动指标（sharpe、volatility、max_drawdown、beta）一次调用
可插拔可视化	Matplotlib、HTML、Plotly、Bokeh 后端，基于 VizBackend 协议
组合优化	有效前沿、风险平价、约束优化
蒙特卡洛	Bootstrap、情景测试、路径模拟
绩效归因	Brinson、Fama-French、风格分析
惰性导入	import fincore 仅需 ~0.04 秒
PEP 561	py.typed 标记，支持类型检查器

安装

pip install fincore                  # 核心
pip install "fincore[viz]"           # + matplotlib, seaborn
pip install "fincore[all]"           # 全部依赖
pip install "fincore[dev]"           # 开发工具

从源码安装：

git clone https://gitee.com/yunjinqi/fincore       # 中国用户
git clone https://github.com/cloudQuant/fincore     # 国际用户
cd fincore && pip install -e ".[dev,viz]"

快速开始

import fincore

# 一行代码完成分析 — 惰性计算、自动缓存
ctx = fincore.analyze(returns, factor_returns=benchmark)

print(f"夏普比率: {ctx.sharpe_ratio:.4f}")
print(f"最大回撤: {ctx.max_drawdown:.4f}")
print(f"Alpha:    {ctx.alpha:.6f}")

ctx.to_html(path="report.html")       # 独立 HTML 报告
ctx.to_json()                          # JSON 导出

经典 API（可直接替换 empyrical）：

from fincore import empyrical

sharpe = empyrical.sharpe_ratio(returns, risk_free=0.02/252)
alpha, beta = empyrical.alpha_beta(returns, benchmark)
mdd = empyrical.max_drawdown(returns)

RollingEngine（批量滚动指标）：

from fincore.core.engine import RollingEngine

engine = RollingEngine(returns, factor_returns=benchmark, window=60)
results = engine.compute(['sharpe', 'volatility', 'max_drawdown', 'beta'])

组合优化：

from fincore.optimization import efficient_frontier, risk_parity, optimize

ef = efficient_frontier(returns_df, n_points=50)
rp = risk_parity(returns_df)
w = optimize(returns_df, objective="max_sharpe")

指标概览

类别	主要指标
收益	simple_returns, cum_returns, annual_return, cagr, aggregate_returns
风险	max_drawdown, annual_volatility, downside_risk, value_at_risk, conditional_value_at_risk
风险调整	sharpe_ratio, sortino_ratio, calmar_ratio, omega_ratio, information_ratio
市场关系	alpha, beta, up_capture, down_capture, treynor_ratio
滚动	roll_sharpe_ratio, roll_max_drawdown, roll_beta, roll_alpha 等
择时	treynor_mazuy_timing, henriksson_merton_timing, market_timing_return
连续统计	max_consecutive_up_days, max_consecutive_down_days, max_single_day_gain

完整指标列表见 API 文档

测试

pytest tests/ -n 4                   # 并行运行（2345 个测试）
pytest tests/ --cov=fincore          # 含覆盖率
pytest tests/test_core/              # AnalysisContext、RollingEngine、可视化

贡献

欢迎贡献！详见 CONTRIBUTING.md。

许可证

Apache License 2.0 — 详见 LICENSE。最初由 Quantopian Inc. 开发，目前由开源社区维护。