BacktestBuddy

Open-source Python package for sports-betting backtests: sequential bankroll simulation, Fixed Stake and Kelly sizing, and risk metrics (ROI, CAGR, Sharpe, Sortino, Calmar, drawdown).

Requires Python >= 3.9. License: MIT.

Stock and crypto backtests are planned; sports betting is the supported surface today.

Features

• PredictionBacktest and ModelBacktest with walk-forward CV
• Fixed-stake and Kelly Criterion strategies
• Performance metrics aligned to documented formulas
• Plotly bankroll, ROI, and odds-distribution charts

Documentation

Full docs live in the GitHub repository:

• Getting Started
• Core Concepts
• Backtest Module
• Metrics Module
• Strategies Module
• Plots Module
• Examples

Local docs: pip install backtestbuddy[docs] then mkdocs serve.

Installation

To install BacktestBuddy, run the following command:

pip install backtestbuddy

Quick Example

Here's a simple example of how to use BacktestBuddy for a sports betting backtest:

from backtestbuddy.strategies.sport_strategies import FixedStake
from backtestbuddy.backtest.sport_backtest import PredictionBacktest

# Prepare your data

data = ... # Your historical betting data

# Define your strategy

strategy = FixedStake(stake=10)

# Create a backtest object
backtest = PredictionBacktest(
    data=data,
    date_column='date',
    odds_columns=['odds_team_a', 'odds_team_b'],
    outcome_column='actual_winner',
    prediction_column='model_predictions',
    initial_bankroll=1000,
    strategy=strategy,
    model_prob_columns=['prob_team_a', 'prob_team_b'] # Needed for PredictionBacktest in combination with Kelly Strategy. Not needed for ModelBacktest in combination with Kelly Strategy, because the model probabiliies will be calculated by the model or if the Strategy does not require model probabilities, like Fixed Stake.
)

# Run the backtest
backtest.run()    

# Show the detailed match results
backtest.detailed_results
# or
bookie_results = backtest.get_detailed_results()
bookie_results

# Show Bookie Results
bookie_results = backtest.get_bookie_results()
bookie_results

# Calculate Performance Metrics
backtest.calculate_metrics()

# Visualize the Backtest Results
backtest.plot()

# Visualize the Odds Distribution etc...
backtest.plot_odds_distribution()

Changelog

Version 0.1.13 (2026-08-26)

⚠️ Breaking Changes:

• Sharpe / Sortino / Calmar: Period returns compound with prod(1+r)-1 instead of summing simple returns; empty calendar days are no longer filled with zeros. Numeric values change vs 0.1.12.
• Placed bets: Metrics count a bet only when bt_stake > 0 and bt_bet_on != -1.
• Calmar / Risk-Adjusted Annual ROI: Return inf when there is no drawdown and return is positive; 0 when return is also 0.
• FixedStake.get_bet_details: Uses select_bet (model probabilities override a class prediction). Unused initial_bankroll attribute removed.

Improvements:

• Bankroll max drawdown uses the last peak before the trough; plot overlay matches that window.
• Kelly fraction is 0 when decimal odds are <= 1 (no division by zero).
• PyPI metadata: SPDX MIT license, Python 3.13 classifier, tighter project description.

Testing / docs:

• Independent numeric tests for Sharpe, Sortino, Calmar, same-day compounding, and the bet filter.
• Metrics and strategies docs rewritten to match the implementations.

Version 0.1.12 (2025-11-07)

⚠️ Breaking Changes:

• Risk-Adjusted Annual ROI: Fixed critical units mismatch - now returns unitless ratio (e.g., 0.667) instead of percentage-based values (e.g., 66.67). Values are reduced by 100x. Update any code comparing or thresholding this metric.

Improvements:

• Sortino Ratio: Enhanced calculation with proper downside deviation formula and edge case handling (inf when downside deviation is zero and mean excess return is positive; 0.0 when both are zero)
• Calmar Ratio: Improved calculation using geometric annual return for better accuracy in risk-adjusted performance metrics
• Max Drawdown Duration: Fixed calculation to correctly identify last peak before trough (duration = end - start + 1 from last peak)

Infrastructure:

• Migrated to uv package manager for faster dependency resolution
• Updated minimum Python version to 3.9 (removed support for 3.6, 3.7, 3.8)
• Modernized dependencies:
  • numpy: 1.13.3 → 1.26.0
  • pandas: 0.25 → 1.3.0
  • matplotlib: 3.0.0 → 3.5.0
  • scipy: 1.0.0 → 1.7.0
  • plotly: 4.14.0 → 5.0.0
  • scikit-learn: 0.24.0 → 1.0.0
  • nbformat: 4.2.0 → 5.0.0
• Added Python 3.12 support
• Fixed package metadata for PyPI compatibility (license field configuration)
• Updated metrics documentation with precise mathematical formulas

Testing:

• Added comprehensive test suites for Sortino Ratio, Calmar Ratio, and Risk-Adjusted Annual ROI
• Enhanced test coverage for edge cases and error handling

Version 0.1.10 (2025-01-23)

• Fixed Risk-Adjusted Annual ROI calculation to use macro ROI and handle negative values correctly
• Kelly fractions are now always returned in bet details regardless of min_kelly and min_prob filters
• Added Compound Annual Growth Rate (CAGR) metric 'CAGR [%]'

Version 0.1.9 (2025-01-19)

• Added micro/macro perspectives for annual ROI:
  • 'Avg. ROI per Year [%]' → 'Avg. ROI per Year [%] (micro)' - averages individual yearly ROIs
  • Added 'Avg. ROI per Year [%] (macro)' - total ROI divided by number of years

Version 0.1.8 (2025-01-19)

• Improved ROI metrics clarity:
  • Renamed ROI metrics for better understanding:
    • 'Avg. ROI per Bet [%]' → 'Avg. ROI per Bet [%] (micro)' - averages individual bet ROIs
    • Added 'Avg. ROI per Bet [%] (macro)' - total ROI divided by number of bets

Version 0.1.7 (2025-01-19)

• Fixed ROI calculations:
  • Modified calculate_avg_roi_per_year to calculate annual ROI by dividing total ROI by number of years
  • Improved handling of empty DataFrames in ROI calculations
  • Added better handling of edge cases (same day, zero years) in ROI calculations
  • Added proper docstrings and test cases for ROI calculations

Version 0.1.6 (2025-01-19)

• Fixed ROI calculations:
  • Average ROI per Bet now correctly calculates per-bet returns
  • Average ROI per Year now uses total profits and stakes per year
  • Risk-Adjusted Annual ROI improved to handle edge cases

Version 0.1.5 (2025-01-19)

• Fixed pandas SettingWithCopyWarning in metrics calculation

Version 0.1.4 (2025-01-19)

• Added new metrics:
  • Average ROI per Year [%]
  • Risk-Adjusted Annual ROI [-] (Avg. ROI per Year / Max Drawdown)

Version 0.1.3 (2025-01-18)

• Added new metric:
  • Average ROI per Bet [%]

Version 0.1.2 (2023-11-28)

• Added bookie simulation functionality
• Enhanced plotting capabilities
• Improved documentation

Version 0.1.1 (2023-11-18)

• Initial release with sports betting functionality
• Basic metrics and visualization tools
• Core backtesting framework