Skip to main content

Overfitting (Futures Backtesting)

Tests

Overfitting simulates a realistic crypto futures trading environment including

  • Liquidation, Margin, Leverage for stress testing
  • Multiple Currency Trading (e.g., backtesting BTC PERP & ETH PERP at the same time)
  • Four Different Order Types: LIMIT, MARKET, STOP_LIMIT, STOP_MARKET
  • Slippage/Commission Setting

Installation

$ pip install overfitting

Usage

Run from the repository root; the example reads the sample data in examples/data/.

import pandas as pd
from overfitting import Strategy
from overfitting.indicators import sma, crossover, crossunder

def load_data():
    df = pd.read_csv('examples/data/BTCUSDT.csv')
    benchamrk_df = pd.read_csv('examples/data/BTCUSDT.csv') # BTC buy and Hold
    df['timestamp'] = pd.to_datetime(df['timestamp'], unit='ms')
    df.set_index('timestamp', inplace=True)

    start_time = pd.to_datetime('2023-01-01 00:00:00')
    df = df.loc[start_time:]

    return df, benchamrk_df

class MyStrategy(Strategy):
    def init(self):
        self.asset = 'BTC'
        self.set_leverage(self.asset, 1)

        close = self.data[self.asset].close
        self.fast = self.I(sma, close, 20)
        self.slow = self.I(sma, close, 50)

    def next(self):
        position = self.get_position(self.asset)

        # Golden cross (entry)
        if crossover(self.fast, self.slow) and position.qty == 0:
            price = self.price(self.asset)
            lot_size = self.get_balance() // price
            self.limit_order(self.asset, lot_size, price)

        # Death cross (exit)
        elif crossunder(self.fast, self.slow) and position.qty > 0:
            self.market_order(self.asset, -position.qty)

price_df, benchmark_data = load_data()
strategy = MyStrategy(
    data={"BTC": price_df},
    benchmark=benchmark_data, # Default = None Optional
    initial_capital=100_000, # Default Optional
    commission_rate=0.0002, # Default Optional
    maint_margin_rate=0.005, # Default Optional
    maint_amount=50  # Default Optional
)
returns = strategy.run()
strategy.plot(returns)

Results

Performance Summary

Overview
  Start Date                                   2023-01-01 00:00
  End Date                                     2024-08-29 00:00
  Number of Years                                         1.663
  Initial Balance                                    100,000.00
  Final Balance                                      205,328.91
  Total Return                                          105.33%
  CAGR                                                   54.13%

Returns
  Annualized Mean Return                                 48.64%
  Best Day                                               10.08%
  Worst Day                                              -5.38%
  Best Month                                             27.88%
  Worst Month                                           -13.71%
  Positive Days                                          34.93%
  Positive Months                                        70.00%
  Average Up Day                                          1.59%
  Average Down Day                                       -0.95%
  Longest Winning Streak (days)                               7
  Longest Losing Streak (days)                                7

Risk
  Volatility (annualized)                                33.08%
  Downside Deviation (annualized)                        17.38%
  Sharpe Ratio                                            1.470
  Sortino Ratio                                           2.799
  Calmar Ratio                                            2.040
  Omega Ratio                                             1.316
  Gain to Pain Ratio                                      0.316
  Tail Ratio                                              1.569
  Common Sense Ratio                                      2.064
  Daily Value at Risk (95%)                              -2.19%
  Daily Value at Risk (99%)                              -3.74%
  Daily Expected Shortfall (95%)                         -3.16%
  Daily Expected Shortfall (99%)                         -4.17%
  Skew (daily)                                            1.804
  Excess Kurtosis (daily)                                 7.538
  Autocorrelation (1 day)                                 0.075
  Kelly Fraction                                          4.445

Drawdown
  Max Drawdown                                          -26.53%
  Current Drawdown                                      -20.56%
  Average Drawdown                                       -4.91%
  Longest Drawdown (days)                                   219
  Average Drawdown Duration (days)                       31.500
  Average Recovery Time (days)                            6.765
  Time Underwater                                        93.41%
  Ulcer Index                                            12.12%
  Pain Index                                              9.74%
  Recovery Factor                                         3.970
  Martin Ratio                                            4.465
  Drawdowns Deeper Than 5%                                    6
  Drawdowns Deeper Than 10%                                   2
  Drawdowns Deeper Than 20%                                   2

Sharpe Ratio Reliability
  Sharpe Standard Error                                   0.726
  Sharpe 95% Range (low)                                  0.047
  Sharpe 95% Range (high)                                 2.894
  Probability Sharpe Above 0                             97.86%
  Days Needed To Confirm Sharpe                             401

Benchmark
  Alpha (annualized)                                      3.44%
  Beta                                                    0.509
  Correlation                                             0.758
  R-Squared                                               0.574
  Tracking Error (annualized)                            32.39%
  Information Ratio                                      -1.238
  Excess Return (annualized)                            -61.21%
  Up Capture                                              0.493
  Down Capture                                            0.479
  Days Beating Benchmark                                 43.00%

Trades
  Total Trades                                              182
  Long Trades                                               182
  Short Trades                                                0
  Win Rate                                               37.36%
  Win Rate (long)                                        37.36%
  Win Rate (short)                                          n/a
  Average Win                                          5,837.17
  Average Loss                                        -2,557.89
  Largest Win                                         27,402.74
  Largest Loss                                       -10,211.93
  Payoff Ratio                                            2.282
  Profit Factor                                           1.361
  Expectancy per Trade                                   578.73
  Average Trade Return                                    0.52%
  Average Winning Return                                  3.94%
  Average Losing Return                                  -1.52%
  Expectancy (R)                                          0.226
  System Quality Number                                   1.220
  Average Holding Time (bars)                            43.352
  Median Holding Time (bars)                             33.000
  Longest Holding Time (bars)                               282
  Average Holding Time, Winners (bars)                   73.294
  Average Holding Time, Losers (bars)                    25.491
  Longest Winning Streak (trades)                             7
  Longest Losing Streak (trades)                              8
  Trades per Month                                        9.233
  Profit From Best Trade                                 26.02%
  Profit From Best 5 Trades                             119.77%
  Net Profit Without Best 5 Trades                   -20,822.32
  Gross Profit                                       396,927.83
  Gross Loss                                        -291,598.92
  Net Profit                                         105,328.91

Trade Quality
  Average Adverse Excursion                              -1.85%
  Average Favourable Excursion                            3.08%
  Edge Ratio                                              1.665
  Profit Captured                                        18.08%
  Average Profit Given Back                               2.52%
  Liquidations                                                0

Costs
  Total Commission                                    11,407.29
  Total Slippage                                           0.00
  Funding Paid                                             0.00
  Funding Received                                         0.00
  Total Costs                                         11,407.29
  Profit Before Costs                                116,736.20
  Costs as Share of Profit Before Costs                   9.77%
  Average Cost per Fill                                   31.34
  Break-Even Commission Multiple                         10.233
  Traded Value                                    57,036,444.00
  Turnover (times equity per year)                      196.244

Exposure and Margin
  Time in Market                                         54.25%
  Average Leverage                                        0.491
  Average Leverage in Market                              0.906
  Maximum Leverage                                        0.991
  Average Net Exposure                                   49.14%
  Average Margin Usage                                   48.02%
  Peak Margin Usage                                     102.54%
  Closest Distance to Liquidation                        99.50%
  Average Distance to Liquidation                        99.54%
  Liquidation Loss                                         0.00

Orders
  Orders Placed                                             364
  Orders Filled                                             364
  Orders Cancelled                                            0
  Orders Rejected                                             0
  Orders Still Open                                           0
  Fill Rate                                             100.00%
  Average Slippage per Fill                               0.00%

By Symbol
       Trades Win rate     Net PnL Average PnL Profit factor Share of profit Time held
Symbol                                                                                
BTC       182    37.4%  105,328.91      578.73          1.36          100.0%     54.2%

Worst Drawdowns
   Net drawdown in %  Peak date Valley date Recovery date  Duration (days)
0          26.533797 2024-03-13  2024-06-28           NaT              169
1          20.996185 2023-03-17  2023-09-12    2023-10-23              219
2           7.051091 2023-12-05  2024-01-22    2024-02-09               65
3           5.980692 2023-01-21  2023-02-13    2023-02-15               24
4           5.578214 2023-02-15  2023-03-07    2023-03-12               24
5           5.550106 2024-03-04  2024-03-06    2024-03-11                6
6           4.538401 2023-11-10  2023-11-16    2023-12-04               23
7           2.530832 2023-11-01  2023-11-03    2023-11-09                7
8           2.162228 2024-02-18  2024-02-23    2024-02-27                8
9           1.603446 2024-02-28  2024-02-29    2024-03-04                4

Indicators

An indicator is a plain function that takes price series and returns one value per bar. Declare it in init() with self.I, then read it in next() relative to the current bar:

from overfitting.indicators import sma, rsi, bollinger, crossover

def init(self):
    bars = self.data["BTC"]
    self.fast = self.I(sma, bars.close, 20)
    self.rsi = self.I(rsi, bars.close, 14)
    self.bands = self.I(bollinger, bars.close, 20, 2)    # several outputs

def next(self):
    self.fast[-1]            # value at the last completed bar
    self.fast[-2]            # the bar before
    self.bands.upper[-1]     # one output of a multi-output indicator
    crossover(self.rsi, 30)  # True when RSI just moved above 30
  • Inside next(), an indicator only shows bars that have finished. The bar being traded and later bars cannot be read, so there is no look-ahead to guard against.
  • Before there is enough history the value is NaN, and crossover / crossunder return False.
  • self.price("BTC") is the open of the current bar, the price a market order placed now fills at.
  • Built in: sma, ema, wma, rsi, macd, stochastic, bollinger, atr, donchian.
  • A custom indicator is any function of the same shape; see examples/donchian_breakout.py.

next(self, i) with the bar index is still supported. The class-based indicators (SMA, EMA, ...) and self.indicator(...) still work but are deprecated.

Slippage

MyStrategy(data, slippage=0.001)             # every fill is 0.1% worse than the order price

from overfitting.slippage import skewed
MyStrategy(data, slippage=skewed(0.15))      # slips 15% of the way from the open to the bar's extreme

MyStrategy(data, slippage=lambda order, bar: order.theoretical_price + 0.5)   # your own model

A slippage model is a function (order, bar) -> executed price. order.qty is positive for a buy, and bar has open, high, low and close. slippage_model= and Slippage.FixedPercent(f=...) still work but are deprecated.

Report and Charts

The summary has eleven sections: overview, returns, risk, drawdown, Sharpe ratio reliability, benchmark, trades, trade quality, costs, exposure and margin, and orders, followed by a per-symbol table and the worst drawdowns.

strategy.plot(returns) prints the summary above and shows 13 charts, one after another.

  • In a Jupyter or VS Code notebook the charts appear inline.
  • In a script each opens in a matplotlib window.
strategy.plot(returns)                         # print the summary and show the charts
strategy.plot(returns, save_path="results")    # also save each chart as a PNG in results/
strategy.plot(returns, title="SMA cross")      # name used on the charts
Chart Function in overfitting.analysis.plots Needs
Cumulative returns cumulative_returns
Cumulative returns, log scale cumulative_returns_log
Monthly returns heatmap monthly_heatmap
Yearly returns yearly_returns
Distribution of monthly returns monthly_distribution
Return quantiles (box plot of daily, weekly, monthly returns) return_quantiles
Rolling Sharpe rolling_sharpe
Rolling volatility rolling_volatility
Drawdown drawdown
Rolling beta rolling_beta a benchmark
Profit per trade profit_per_trade
Cost breakdown cost_breakdown
Distance to liquidation liquidation_distance

Rolling beta is skipped when no benchmark is given. Each chart is also available on its own, and every number behind them is in overfitting.analysis.metrics:

from overfitting.analysis import metrics, plots

daily = metrics.aggregate_returns(returns, "D")
plots.drawdown(daily).savefig("drawdown.png")
plots.profit_per_trade(strategy.fetch_round_trips())
metrics.summary(daily)       # 49 metrics as a pandas Series

metrics.trade_summary(strategy.fetch_round_trips())   # win rate, expectancy, streaks ...
metrics.by_symbol(strategy.fetch_round_trips())       # results per symbol
metrics.by_weekday(strategy.fetch_round_trips())      # results by entry weekday

The 13 charts, from the example above:

Cumulative returns Cumulative returns, log scale Monthly returns Yearly returns Distribution of monthly returns Return quantiles Rolling Sharpe ratio Rolling volatility Drawdown Rolling beta Profit per trade Cost breakdown Distance to liquidation

Trade and Account Data

After strategy.run(), everything that happened is available as pandas DataFrames:

strategy.fetch_round_trips()            # one row per completed trade
strategy.fetch_trades()                 # one row per fill
strategy.fetch_orders()                 # every order placed, with its status
strategy.fetch_account_history()        # the account on every bar
strategy.fetch_position_history("BTC")  # one symbol's position on every bar
strategy.fetch_funding()                # funding payments
  • Round trips run from opening a position until it is flat again or flips sides. Each row has entry and exit time and price, holding time, gross PnL, commission, funding, net PnL, and mae / mfe: how far the price moved against and in favour of the position while it was open, as a fraction of the entry price.
  • Orders carry a status of OPEN, FILLED, CANCELLED or REJECTED, a reject_reason when rejected, and the slippage cost of each fill.
  • Account history has cash, equity, margin in use, gross and net exposure, and leverage.
  • Position history has size, entry price, close, exposure, margin, liquidation price and unrealized PnL.

Liquidation Handling

The liquidation logic is based on isolated margin mode:

  • Initial Margin = Entry Price × Quantity / Leverage
  • Maintenance Margin = Entry Price × Quantity × Maintenance Margin Rate − Maintenance Amount
  • Liquidation Price is then calculated based on whether the position is long or short.
    • Long Position Liquidation Price => Entry Price - (Initial Margin - Maintenance Margin)
    • Short Position Liquidation Price => Entry Price + (Initial Margin - Maintenance Margin)

When the price crosses the calculated liquidation level, the position is force-closed and the entire initial margin is lost. Nothing more is charged on top, so an isolated position can never lose more than the margin posted for it. Liquidations are marked in the trade log with is_liquidation_order = True.

Margin Check

An order that opens or increases a position needs price × quantity / leverage of free margin, where free margin is the cash balance minus the margin locked in open positions.

  • If the account cannot afford the order when it is placed, InsufficientMargin is raised.
  • If the account can no longer afford a resting order when it fills, the order is dropped and listed in strategy.fetch_rejected_orders().
  • Orders that reduce or close a position are always accepted.

Equity Curve

strategy.run() returns are based on equity: cash plus the unrealized PnL of open positions, marked at each bar's close. Drawdown and Sharpe therefore include losses on positions that are still open.

returns = strategy.run()                       # mark-to-market (default)
returns = strategy.run(mark_to_market=False)   # realized only: moves when trades close

strategy.equity_curve        # cash + unrealized PnL per bar
strategy.realized_balances   # cash per bar

Funding Rate

Add a funding_rate column to a symbol's DataFrame to simulate funding. A non-zero value on a bar means funding is settled at that bar's open, on the position held into it:

payment = -position quantity × open price × funding rate

Longs pay and shorts receive when the rate is positive. Bars with 0 or NaN settle nothing. Payments change the cash balance and are listed in strategy.fetch_funding().

Supported Order Types

Supports four order types: LIMIT, MARKET, STOP LIMIT, and STOP MARKET. Each behaves according to standard trading conventions.

[NOTE] Rules

  • For MAKRET Orders, the system will automatically execute the trade with "open" price.
  • For STOP Orders, the system will automatically trigger the order when:
    • Long: Price (High) >= Stop Price
    • Short: Price (Low) <= Stop Price
  • Stop Order Immediate Rejection Rule: If a STOP LIMIT or STOP MARKET order would trigger immediately upon creation (because the current price already breaches the stop price), the system rejects the order with "STOP order would Immediately Trigger" message.
limit_order(symbol: str, qty: float, price: float)
market_order(symbol: str, qty: float)
stop_limit_order(symbol: str, qty: float, price: float, stop_price: float)
stop_market_order(symbol: str, qty: float, stop_price: float)

Multiple Currency Backtesting

You can simply test multiple currencies by passing data as dict[str, pd.DataFrame]. For examples, please refer to "multi_currency_sma_corss.ipynb" under "examples" folder.

Upcoming Features

  • Parameter Optimizer
    A simple optimizer to help find the best-performing strategy parameters (like SMA windows, thresholds, etc.) based on backtest results.

💡 Got feedback or suggestions? Feel free to open an issue or contribute via pull request.

Metadata

Release files for overfitting 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for overfitting 0.5.0
File Interpreter ABI Platform Actions
overfitting-0.5.0-1-py3-none-any.whl Python 3 none any Details for overfitting-0.5.0-1-py3-none-any.whl

Release files / overfitting-0.5.0-1-py3-none-any.whl

Download URL overfitting-0.5.0-1-py3-none-any.whl
Size 55.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3403828de2ce1064620acb362ab3c69feeaa099f49f489b89e43a92374217d69
BLAKE2b-256 checksum
How to use checksums
ec9cb1fac7e79b0b828178be7cad7ea1810abd1e3c04e7e906f507caf5906678
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.3

Security for overfitting 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page