wbt 0.1.7

Weight-based backtesting engine for quantitative trading

wbt Python Package

Python API for the wbt Rust backtesting engine.

中文文档

Development Objectives

This Python subproject aims to provide a practical research-facing interface for weight-based backtesting while keeping the heavy computation in Rust.

Design priorities:

1. Keep data input flexible for common research formats.
2. Return analysis-friendly outputs as pandas objects.
3. Preserve one consistent metric schema across stats outputs.
4. Provide plotting utilities that work directly on backtest outputs.

Project Layout

This directory is an independent Python subproject.

python/
|-- pyproject.toml
|-- README.md
|-- scripts/
|-- tests/
`-- wbt/

The Rust crate remains one level up at ../Cargo.toml. maturin builds the extension module from there.

Installation And Local Setup

Requirements:

• Rust toolchain
• Python 3.10+
• uv

Setup:

cd python
uv sync --extra dev
uv run maturin develop --release

Quick Start

import pandas as pd
from wbt import WeightBacktest

df = pd.DataFrame(
    {
        "dt": [
            "2024-01-02 09:01:00",
            "2024-01-02 09:02:00",
            "2024-01-02 09:03:00",
            "2024-01-02 09:04:00",
        ],
        "symbol": ["AAPL", "AAPL", "AAPL", "AAPL"],
        "weight": [0.5, 0.2, 0.0, -0.3],
        "price": [185.0, 186.0, 186.5, 184.5],
    }
)

wb = WeightBacktest(
    df,
    digits=2,
    fee_rate=0.0002,
    n_jobs=4,
    weight_type="ts",   # "ts" or "cs"
    yearly_days=252,
)

print("all:", wb.stats)
print("long:", wb.long_stats)
print("short:", wb.short_stats)

print(wb.daily_return.head())
print(wb.dailys.head())
print(wb.pairs.head())

print(wb.segment_stats("2024-01-01", "2024-12-31", kind="多空"))
print(wb.long_alpha_stats)

Accepted Inputs

The data argument accepts:

• pandas.DataFrame
• polars.DataFrame
• polars.LazyFrame
• file path as str or Path

Supported file formats from path input:

• csv
• parquet
• feather
• arrow

Required columns:

Column	Type	Meaning
dt	datetime-like	Bar end time
symbol	str	Instrument code
weight	float	Target position weight
price	float	Price used for return calculation

Notes:

• Null values are not allowed.
• weight is rounded by digits before backtest.

Main API Surface

Imports:

from wbt import WeightBacktest, backtest, daily_performance

Primary class and helper:

• WeightBacktest(...): main entry.
• backtest(...): convenience wrapper returning WeightBacktest.
• daily_performance(...): standalone metric utility.

Core properties and methods:

• stats, long_stats, short_stats
• daily_return, long_daily_return, short_daily_return
• dailys, pairs
• alpha, alpha_stats, bench_stats
• segment_stats(sdt, edt, kind)
• long_alpha_stats
• get_symbol_daily(symbol), get_symbol_pairs(symbol)

Plotting Utilities

All plotting helpers are under wbt.plotting.

from wbt.plotting import (
    plot_backtest_overview,
    plot_cumulative_returns,
    plot_daily_return_dist,
    plot_drawdown,
    plot_long_short_comparison,
    plot_monthly_heatmap,
    plot_pairs_analysis,
    plot_symbol_returns,
)

Typical usage:

fig1 = plot_cumulative_returns(wb.daily_return)
fig2 = plot_drawdown(wb.daily_return)
fig3 = plot_pairs_analysis(wb.pairs)

# Optional HTML export
html = plot_backtest_overview(wb.daily_return, to_html=True)

Quality And Testing

Run checks from python/:

uv run pytest -v
uv run ruff format --check .
uv run ruff check . --no-fix
uv run basedpyright

Architecture Snapshot

repo-root/
|-- Cargo.toml
|-- src/
`-- python/
    `-- wbt/
        |-- __init__.py
        |-- _df_convert.py
        |-- _wbt.pyi
        |-- backtest.py
        `-- plotting/
            |-- __init__.py
            |-- _common.py
            |-- returns.py
            |-- risk.py
            |-- trades.py
            `-- overview.py

License

MIT