polars-backtest 0.1.7

Polars extension for portfolio backtesting

polars_backtest

High-performance portfolio backtesting extension for Polars, implemented in Rust.

Installation

uv add polars_backtest
# or
pip install polars_backtest

Quick Start

import polars as pl
import polars_backtest as pl_bt

# Long format: one row per (date, symbol)
df = pl.DataFrame({
    "date": ["2024-01-01", "2024-01-01", "2024-01-02", "2024-01-02"],
    "symbol": ["2330", "2317", "2330", "2317"],
    "close": [100.0, 50.0, 102.0, 51.0],
    "weight": [0.6, 0.4, 0.6, 0.4],
})

# Function API
result = pl_bt.backtest(df, trade_at_price="close", position="weight")

# Or DataFrame namespace
result = df.bt.backtest(trade_at_price="close", position="weight")

With Report

report = pl_bt.backtest_with_report(df, trade_at_price="adj_close", resample="M")
report

BacktestReport(
  creturn_len=4219,
  trades_count=6381,
  total_return=8761.03%,
  cagr=29.85%,
  max_drawdown=-35.21%,
  sharpe=1.13,
  win_ratio=46.33%
)

Visualization

Interactive, self-contained HTML report — no extra dependencies, works offline:

pl_bt.viz.show(report)                      # browser tab, or inline in notebooks
pl_bt.viz.save_html(report, "report.html")  # standalone shareable file
pl_bt.viz.report_data(report)               # JSON-safe payload for custom dashboards

Includes equity curve (benchmark overlay, log scale, range presets), drawdown, monthly return heatmap, trade return distribution, MAE scatter, and full stats. Light/dark mode follows the system.

report.get_stats()  # or report.stats

shape: (1, 15)
┌────────────┬────────────┬──────┬──────────────┬──────────┬──────────────┬──────────────┐
│ start      ┆ end        ┆ rf   ┆ total_return ┆ cagr     ┆ max_drawdown ┆ avg_drawdown │
│ ---        ┆ ---        ┆ ---  ┆ ---          ┆ ---      ┆ ---          ┆ ---          │
│ date       ┆ date       ┆ f64  ┆ f64          ┆ f64      ┆ f64          ┆ f64          │
╞════════════╪════════════╪══════╪══════════════╪══════════╪══════════════╪══════════════╡
│ 2008-10-31 ┆ 2025-12-31 ┆ 0.02 ┆ 87.610293    ┆ 0.298538 ┆ -0.352092    ┆ -0.042957    │
└────────────┴────────────┴──────┴──────────────┴──────────┴──────────────┴──────────────┘
┌────────────┬───────────┬──────────────┬───────────────┬──────────┬───────────┬─────────┬───────────┐
│ daily_mean ┆ daily_vol ┆ daily_sharpe ┆ daily_sortino ┆ best_day ┆ worst_day ┆ calmar  ┆ win_ratio │
│ ---        ┆ ---       ┆ ---          ┆ ---           ┆ ---      ┆ ---       ┆ ---     ┆ ---       │
│ f64        ┆ f64       ┆ f64          ┆ f64           ┆ f64      ┆ f64       ┆ f64     ┆ f64       │
╞════════════╪═══════════╪══════════════╪═══════════════╪══════════╪═══════════╪═════════╪═══════════╡
│ 0.300815   ┆ 0.249645  ┆ 1.131947     ┆ 1.834553      ┆ 0.195416 ┆ -0.160707 ┆ 0.84784 ┆ 0.463303  │
└────────────┴───────────┴──────────────┴───────────────┴──────────┴───────────┴─────────┴───────────┘

report.creturn   # Cumulative returns DataFrame
report.trades    # Trade records with MAE/MFE metrics
report.stats     # Statistics (same as get_stats())

Benchmark Comparison

# Use a symbol from your data as benchmark
report = df.bt.backtest_with_report(position="weight", benchmark="0050")

# Or provide a benchmark DataFrame with (date, creturn) columns
report = df.bt.backtest_with_report(position="weight", benchmark=benchmark_df)

# get_metrics includes alpha, beta, m12WinRate when benchmark is set
metrics = report.get_metrics()

Statistics Expressions

from polars_backtest import daily_returns, cumulative_returns, sharpe_ratio, max_drawdown

df.with_columns(
    ret=daily_returns("close"),
    creturn=cumulative_returns("ret"),
)

df.select(
    sharpe=sharpe_ratio("ret"),
    mdd=max_drawdown("creturn"),
)

Features

• Zero-copy Arrow FFI - Direct memory sharing between Polars and Rust
• T+1 execution - Realistic trading simulation
• Stop loss / Take profit / Trailing stop - Risk management
• Resample support - D, W, W-FRI, M, Q, Y

Resample Options

Value	Description
None	Only rebalance when position changes
'D'	Daily
'W'	Weekly (Sunday)
'W-FRI'	Weekly (Friday)
'M'	Monthly
'Q'	Quarterly
'Y'	Yearly

Development

# Setup
uv sync

# Build
uv run maturin develop --release

# Test
uv run pytest tests/ -v                       # Fast tests (default)
uv run pytest tests/ -v -m slow               # Slow tests (finlab)
uv run pytest tests/test_wide_vs_finlab.py -v # Wide vs Finlab
uv run pytest tests/test_long_vs_wide.py -v   # Long vs Wide

License

PolyForm Noncommercial 1.0.0

For commercial use, please contact the author to obtain a commercial license.