BacktestBuddy

Backtest sports-betting strategies in Python: a sequential bankroll simulation over your historical odds, with staking strategies, risk metrics, closing line value, and interactive Plotly charts.

Works with any data source: you pass a pandas DataFrame and tell BacktestBuddy which columns hold the odds, the outcome, the date, and your model output.

Python >= 3.9 · MIT license

Features

• Two ways to backtest: PredictionBacktest for predictions you already have, ModelBacktest to train an sklearn-style model walk-forward.
• Strategies: fixed stake, Kelly criterion, value betting, unit staking, edge-proportional staking, odds-band filter, and risk limits (stake caps, daily limits, loss pauses, drawdown stop).
• Strategy toolkit: combine any outcome selector with any stake sizer, e.g. value-bet selection with Kelly sizing, or write your own block in a few lines.
• Simultaneous matches: size same-day bets from the day's opening bankroll and cap their total Kelly stake.
• Metrics: ROI, Yield, CAGR, Sharpe, Sortino, Calmar, drawdown, calibration (Brier, log loss, ECE), and a market baseline.
• Closing line value: compare the odds you took with any later or sharper line.
• Margin removal: multiplicative, additive, power, and Shin methods.
• Odds stress test: re-run with 1%, 2%, 3% worse odds to see how robust the edge is.
• Hyperparameter tuning: evaluate() returns only the metrics an optimizer like Optuna needs, several times faster than a full run, plus a holdout split helper.
• Charts: bankroll and drawdown, reliability diagram, odds distribution.

Installation

pip install backtestbuddy

Quick example

import numpy as np
import pandas as pd
import backtestbuddy as btb

# One row per match: date, decimal odds per outcome, actual outcome (0-based), model output
rng = np.random.default_rng(0)
n = 500
p_home = rng.uniform(0.3, 0.7, n)
data = pd.DataFrame({
    "date": pd.date_range("2023-01-01", periods=n, freq="D"),
    "odds_home": np.round(0.95 / p_home, 2),
    "odds_away": np.round(0.95 / (1 - p_home), 2),
    "winner": (rng.uniform(size=n) > p_home).astype(int),  # 0 = home, 1 = away
})
model_p = np.clip(p_home + rng.normal(0, 0.05, n), 0.01, 0.99)
data["prob_home"] = model_p
data["prob_away"] = 1 - model_p
data["prediction"] = (model_p < 0.5).astype(int)

backtest = btb.PredictionBacktest(
    data=data,
    odds_columns=["odds_home", "odds_away"],
    outcome_column="winner",
    date_column="date",
    prediction_column="prediction",
    model_prob_columns=["prob_home", "prob_away"],
    strategy=btb.KellyCriterion(downscaling=0.5),
    initial_bankroll=1000,
)
backtest.run()

metrics = backtest.calculate_metrics()
print(metrics["ROI [%]"], metrics["Yield [%]"], metrics["Max Drawdown [%]"])
# This toy model is only noise around the true odds, so the 5% margin wins: expect a loss.
backtest.plot()  # interactive Plotly chart

Documentation

• Getting Started: data format and a first backtest, step by step
• Core Concepts: how the simulation works
• Backtest Module: classes, parameters, results columns, stress test
• Strategies Module
• Metrics Module: every metric with its formula
• Odds Module: margin removal
• Hyperparameter Tuning: fast evaluate(), holdout split, Optuna recipe
• Plots Module
• Examples
• Changelog

Browse the docs locally with pip install backtestbuddy[docs] and mkdocs serve.

Development

The project uses uv. From a clone of the repository:

uv run --extra test pytest          # full test suite, including every docs example
uv run --extra docs mkdocs serve    # docs at http://127.0.0.1:8000

GitHub Actions runs the tests on Python 3.9 to 3.13 and builds the docs for every pull request.