katsustats 0.3.0

A modernized backtest report module powered by Polars

Katsustats

katsustats is a Polars-powered analytics and reporting library for daily return series, inspired by quantstats.

Pass a DataFrame with date and returns, and get summary metrics, drawdown analysis, key metrics with visualizations, and a self-contained HTML report.

Highlights:

• Polars-first API with pandas input support
• Benchmark-aware performance comparison
• Self-contained offline HTML reports
• Functional modules for stats, plots, and reports

Preview

Cumulative returns	Daily returns

Drawdowns	Monthly returns

Yearly returns	Rolling Sharpe

Rolling volatility	Day-of-week returns

How to use

Installation

pip install katsustats

Or with uv:

uv add katsustats

Try it online

• Open in Google Colab
• Open in Kaggle

Data format

katsustats accepts either a Polars or pandas DataFrame with two required columns:

column	type	description
date	date-like	Trading date
returns	float-like	Daily return (e.g. 0.01 = +1%)

When a pandas DataFrame is passed, katsustats converts it to Polars at the start of processing.

If date is datetime-like, it is normalized to pl.Date before analysis.

If multiple rows share the same date, katsustats compounds those same-day returns values into one daily return, emits a warning, and continues.

Basic usage

import polars as pl
import katsustats

# Build your return series
returns = pl.DataFrame({
    "date": pl.date_range(pl.date(2020, 1, 1), pl.date(2023, 12, 31), "1d", eager=True),
    "returns": your_daily_returns,   # list / numpy array of floats
})

# Generate the full report (prints metrics + shows all plots)
results = katsustats.reports.full(returns)

Pandas inputs work too:

import pandas as pd

returns = pd.DataFrame({
    "date": dates,
    "returns": your_daily_returns,
})

results = katsustats.reports.full(returns)

See also the runnable examples in examples/quickstart.py, examples/with_benchmark.py, and examples/html_report.py.

results is a dict with the following keys:

key	type	description
summary	dict[str, float]	Raw numeric summary values
metrics	pl.DataFrame	Summary metrics table
drawdowns	pl.DataFrame	Top-5 drawdown periods
dow_stats	pl.DataFrame	Day-of-week statistics
figures	dict[str, Figure]	All 8 matplotlib figures

With a benchmark

benchmark = pl.DataFrame({
    "date": pl.date_range(pl.date(2020, 1, 1), pl.date(2023, 12, 31), "1d", eager=True),
    "returns": benchmark_daily_returns,
})

results = katsustats.reports.full(returns, benchmark=benchmark)

When a benchmark is provided, the metrics table also includes Alpha, Beta, Correlation, Information Ratio, and Excess Return.

Advanced options

results = katsustats.reports.full(
    returns,
    benchmark=benchmark,
    rf=0.04,          # annualized risk-free rate (default 0.0)
    periods=252,      # trading days per year (default 252)
    show=False,       # suppress inline plot display
)

HTML report

Generate a self-contained HTML report (similar to qs.reports.html()):

# Save to file
katsustats.reports.html(returns, benchmark=benchmark, title="My Strategy", output="report.html")

# Or get HTML string
html_str = katsustats.reports.html(returns, title="My Strategy")

The report includes headline metric cards, performance tables, period performance, drawdown analysis, day-of-week statistics, and all 8 charts embedded as images — all in a single .html file that works offline.

When a benchmark is provided, the HTML report also includes regime analysis.

Using individual modules

You can also call the lower-level APIs directly:

import katsustats

# --- Stats ---
katsustats.stats.total_return(returns)
katsustats.stats.cagr(returns)
katsustats.stats.sharpe(returns, rf=0.0)
katsustats.stats.sortino(returns)
katsustats.stats.max_drawdown(returns)
katsustats.stats.calmar(returns)
katsustats.stats.volatility(returns)
katsustats.stats.win_rate(returns)
katsustats.stats.profit_factor(returns)
katsustats.stats.value_at_risk(returns, alpha=0.05)

katsustats.stats.drawdown_details(returns, top_n=5)      # pl.DataFrame
katsustats.stats.day_of_week_stats(returns)              # pl.DataFrame
katsustats.stats.summary_metrics(returns, benchmark)     # pl.DataFrame

# --- Plots ---
katsustats.plots.plot_cumulative_returns(returns, benchmark)
katsustats.plots.plot_drawdown(returns)
katsustats.plots.plot_monthly_heatmap(returns)
katsustats.plots.plot_yearly_returns(returns, benchmark)
katsustats.plots.plot_return_distribution(returns, benchmark)
katsustats.plots.plot_rolling_sharpe(returns, benchmark)
katsustats.plots.plot_rolling_volatility(returns, benchmark)
katsustats.plots.plot_dow_returns(returns)

Metrics produced

metric	description
Total Return	Compounded return over the full period
CAGR	Compound Annual Growth Rate
Sharpe Ratio	Annualized risk-adjusted return
Sortino Ratio	Sharpe using only downside deviation
Max Drawdown	Largest peak-to-trough decline
Calmar Ratio	CAGR / |Max Drawdown|
Volatility (ann.)	Annualized standard deviation
Win Rate	% of days with positive returns
Profit Factor	Gross profit / gross loss
Best / Worst Day	Largest single-day gain / loss
Avg Win / Avg Loss	Mean return on winning / losing days
Daily VaR (95%)	5th-percentile daily return
CVaR (95%)	Mean return in the worst 5% tail
Recovery Factor	Total return / |Max Drawdown|
Skewness / Kurtosis	Distribution shape statistics
Best / Worst Month	Largest / smallest monthly return
Best / Worst Year	Largest / smallest yearly return
Positive Months / Years	Share of profitable months / years

When a benchmark is provided, katsustats also reports Alpha, Beta, Correlation, Information Ratio, and Excess Return.