alpha-risk-kit 0.1.0

Portfolio analytics toolkit with interactive widgets for quants - return analysis, drawdown visualization, and benchmark comparison

Alpha Risk Kit

Portfolio analytics toolkit with interactive widgets for quants

Alpha Risk Kit is a comprehensive Python library for analyzing portfolio returns, inspired by QuantStats and VectorBT. It provides:

• Interactive Widgets: AnyWidget-based components for Jupyter, Marimo, and VS Code
• Static Charts: Matplotlib and Plotly visualizations
• Pandas Accessor: VectorBT-style returns.ark.stats() pattern
• Bilingual Support: English and Chinese (中文) interfaces

Quick Start

uv sync --extra all

uv run jupyter notebook
uv run marimo edit --watch usages/marimo/demo.py
uv run streamlit run usages/streamlit/app.py

import alpha_risk_kit as ark
import pandas as pd

# Your returns data
returns = pd.Series([0.01, -0.02, 0.015, -0.005, 0.02])

# Get comprehensive statistics
returns.ark.stats()

# Create interactive widget
from alpha_risk_kit.widgets import ReturnsWidget
widget = ReturnsWidget(returns=returns)
widget  # Display in Jupyter

Installation

# Basic installation
pip install alpha-risk-kit

# With plotting support
pip install alpha-risk-kit[plots]

# All dependencies
pip install alpha-risk-kit[all]

# Development installation
pip install -e ".[all]"

Features

Core Metrics

# Using pandas accessor
returns.ark.sharpe()           # Sharpe Ratio
returns.ark.sortino()          # Sortino Ratio
returns.ark.max_drawdown()     # Maximum Drawdown
returns.ark.calmar()           # Calmar Ratio
returns.ark.win_rate()         # Win Rate

# With benchmark comparison
returns.ark.stats(benchmark=sp500_returns)

Interactive Widgets

from alpha_risk_kit.widgets import ReturnsWidget, ComparisonWidget, DashboardWidget

# Single strategy analysis
widget = ReturnsWidget(returns=my_returns, benchmark=benchmark)

# Strategy vs benchmark comparison
comparison = ComparisonWidget(returns=strategy, benchmark=benchmark)

# Multi-strategy dashboard
dashboard = DashboardWidget(returns=strategies_df, benchmarks=benchmarks_df)

Static Charts

# Matplotlib
fig = ark.plot_combined(returns, benchmark=benchmark, backend='matplotlib')

# Plotly (interactive)
fig = ark.plot_combined(returns, benchmark=benchmark, backend='plotly')
fig.show()

Bilingual Support

ark.set_language('zh')  # Switch to Chinese (中文)
ark.set_language('en')  # Switch to English

Widget Gallery

Widget	Description
ReturnsWidget	Cumulative returns + drawdown + key metrics
ComparisonWidget	Strategy vs benchmark with excess returns
DashboardWidget	Multi-strategy comparison with sortable table

Platform Support

Platform	Widgets	Static Charts
Jupyter Notebook	✅	✅
JupyterLab	✅	✅
VS Code	✅	✅
Marimo	✅	✅
Streamlit	❌	✅
Google Colab	✅	✅

Project Structure

alpha-risk-kit/
├── src/alpha_risk_kit/
│   ├── stats.py          # Core metrics
│   ├── plots.py          # Chart generation
│   ├── accessors.py      # Pandas accessor
│   ├── i18n.py           # Translations
│   ├── utils.py          # Utilities
│   └── widgets/          # AnyWidget components
├── usages/
│   ├── jupyter/          # Jupyter notebook demo
│   ├── streamlit/        # Streamlit app demo
│   └── marimo/           # Marimo notebook demo
└── docs/                 # MkDocs documentation

Comparison with Other Tools

Feature	Alpha Risk Kit	QuantStats	VectorBT
Interactive Widgets	✅ AnyWidget	❌	❌
Pandas Accessor	✅ .ark	❌	✅ .vbt
Bilingual (EN/ZH)	✅	❌	❌
Plotly Charts	✅	✅	✅
Matplotlib Charts	✅	✅	✅

Documentation

Full documentation is available at: https://daviddwlee84.github.io/alpha-risk-kit

Contributing

Contributions are welcome! Please see AGENTS.md for development guidelines.

License

MIT License - see LICENSE for details.