Merge branch 'master' into feature/fix_auto_close

Author: Bénouare

.github/issue_template.md

@@ -17,6 +17,12 @@
 2.
 3.
 
+```python
+
+python code goes here
+
+```
+
 ### Additional info
 
 <!-- screenshots, code snippets, ... -->

CHANGELOG.md

@@ -3,9 +3,21 @@ What's New
 
 These were the major changes contributing to each release:
 
+=======
+### 0.x.x
+
+### 0.3.3
+* new param on "run()" to manage if trades should be close at end, or not. (#273)
 
 ### 0.3.2
-* new param on run to manage close, or not the trades at end (#273)
+(2021-08-03)
+
+* New strategy performance method [`backtesting.lib.compute_stats`](https://kernc.github.io/backtesting.py/doc/backtesting/lib.html#backtesting.lib.compute_stats) (#281)
+* Improve plotting speed (#329) and optimization performance (#295) on large datasets.
+* Commission constraints now allow for market-maker's rebates.
+* [`Backtest.plot`](https://kernc.github.io/backtesting.py/doc/backtesting/backtesting.html#backtesting.backtesting.Backtest.plot)
+  now returns the bokeh figure object for further processing.
+* Other small bugs and fixes.
 
 
 ### 0.3.1

backtesting/_plotting.py

@@ -99,11 +99,23 @@ def _maybe_resample_data(resample_rule, df, indicators, equity_data, trades):
         if resample_rule is False or len(df) <= _MAX_CANDLES:
             return df, indicators, equity_data, trades
 
-        from_index = dict(day=-2, hour=-6, minute=1, second=0, millisecond=0,
-                          microsecond=0, nanosecond=0)[df.index.resolution]
-        FREQS = ('1T', '5T', '10T', '15T', '30T', '1H', '2H', '4H', '8H', '1D', '1W', '1M')
-        freq = next((f for f in FREQS[from_index:]
-                     if len(df.resample(f)) <= _MAX_CANDLES), FREQS[-1])
+        freq_minutes = pd.Series({
+            "1T": 1,
+            "5T": 5,
+            "10T": 10,
+            "15T": 15,
+            "30T": 30,
+            "1H": 60,
+            "2H": 60*2,
+            "4H": 60*4,
+            "8H": 60*8,
+            "1D": 60*24,
+            "1W": 60*24*7,
+            "1M": np.inf,
+        })
+        timespan = df.index[-1] - df.index[0]
+        require_minutes = (timespan / _MAX_CANDLES).total_seconds() // 60
+        freq = freq_minutes.where(freq_minutes >= require_minutes).first_valid_index()
         warnings.warn(f"Data contains too many candlesticks to plot; downsampling to {freq!r}. "
                       "See `Backtest.plot(resample=...)`")
 

backtesting/_stats.py

@@ -0,0 +1,153 @@
+from typing import List, TYPE_CHECKING, Union
+
+import numpy as np
+import pandas as pd
+
+from ._util import _data_period
+
+if TYPE_CHECKING:
+    from .backtesting import Strategy, Trade
+
+
+def compute_drawdown_duration_peaks(dd: pd.Series):
+    iloc = np.unique(np.r_[(dd == 0).values.nonzero()[0], len(dd) - 1])
+    iloc = pd.Series(iloc, index=dd.index[iloc])
+    df = iloc.to_frame('iloc').assign(prev=iloc.shift())
+    df = df[df['iloc'] > df['prev'] + 1].astype(int)
+
+    # If no drawdown since no trade, avoid below for pandas sake and return nan series
+    if not len(df):
+        return (dd.replace(0, np.nan),) * 2
+
+    df['duration'] = df['iloc'].map(dd.index.__getitem__) - df['prev'].map(dd.index.__getitem__)
+    df['peak_dd'] = df.apply(lambda row: dd.iloc[row['prev']:row['iloc'] + 1].max(), axis=1)
+    df = df.reindex(dd.index)
+    return df['duration'], df['peak_dd']
+
+
+def geometric_mean(returns: pd.Series) -> float:
+    returns = returns.fillna(0) + 1
+    if np.any(returns <= 0):
+        return 0
+    return np.exp(np.log(returns).sum() / (len(returns) or np.nan)) - 1
+
+
+def compute_stats(
+        trades: Union[List['Trade'], pd.DataFrame],
+        equity: np.ndarray,
+        ohlc_data: pd.DataFrame,
+        strategy_instance: 'Strategy',
+        risk_free_rate: float = 0,
+) -> pd.Series:
+    assert -1 < risk_free_rate < 1
+
+    index = ohlc_data.index
+    dd = 1 - equity / np.maximum.accumulate(equity)
+    dd_dur, dd_peaks = compute_drawdown_duration_peaks(pd.Series(dd, index=index))
+
+    equity_df = pd.DataFrame({
+        'Equity': equity,
+        'DrawdownPct': dd,
+        'DrawdownDuration': dd_dur},
+        index=index)
+
+    if isinstance(trades, pd.DataFrame):
+        trades_df = trades
+    else:
+        # Came straight from Backtest.run()
+        trades_df = pd.DataFrame({
+            'Size': [t.size for t in trades],
+            'EntryBar': [t.entry_bar for t in trades],
+            'ExitBar': [t.exit_bar for t in trades],
+            'EntryPrice': [t.entry_price for t in trades],
+            'ExitPrice': [t.exit_price for t in trades],
+            'PnL': [t.pl for t in trades],
+            'ReturnPct': [t.pl_pct for t in trades],
+            'EntryTime': [t.entry_time for t in trades],
+            'ExitTime': [t.exit_time for t in trades],
+        })
+        trades_df['Duration'] = trades_df['ExitTime'] - trades_df['EntryTime']
+    del trades
+
+    pl = trades_df['PnL']
+    returns = trades_df['ReturnPct']
+    durations = trades_df['Duration']
+
+    def _round_timedelta(value, _period=_data_period(index)):
+        if not isinstance(value, pd.Timedelta):
+            return value
+        resolution = getattr(_period, 'resolution_string', None) or _period.resolution
+        return value.ceil(resolution)
+
+    s = pd.Series(dtype=object)
+    s.loc['Start'] = index[0]
+    s.loc['End'] = index[-1]
+    s.loc['Duration'] = s.End - s.Start
+
+    have_position = np.repeat(0, len(index))
+    for t in trades_df.itertuples(index=False):
+        have_position[t.EntryBar:t.ExitBar + 1] = 1
+
+    s.loc['Exposure Time [%]'] = have_position.mean() * 100  # In "n bars" time, not index time
+    s.loc['Equity Final [$]'] = equity[-1]
+    s.loc['Equity Peak [$]'] = equity.max()
+    s.loc['Return [%]'] = (equity[-1] - equity[0]) / equity[0] * 100
+    c = ohlc_data.Close.values
+    s.loc['Buy & Hold Return [%]'] = (c[-1] - c[0]) / c[0] * 100  # long-only return
+
+    gmean_day_return: float = 0
+    day_returns = np.array(np.nan)
+    annual_trading_days = np.nan
+    if isinstance(index, pd.DatetimeIndex):
+        day_returns = equity_df['Equity'].resample('D').last().dropna().pct_change()
+        gmean_day_return = geometric_mean(day_returns)
+        annual_trading_days = float(
+            365 if index.dayofweek.to_series().between(5, 6).mean() > 2/7 * .6 else
+            252)
+
+    # Annualized return and risk metrics are computed based on the (mostly correct)
+    # assumption that the returns are compounded. See: https://dx.doi.org/10.2139/ssrn.3054517
+    # Our annualized return matches `empyrical.annual_return(day_returns)` whereas
+    # our risk doesn't; they use the simpler approach below.
+    annualized_return = (1 + gmean_day_return)**annual_trading_days - 1
+    s.loc['Return (Ann.) [%]'] = annualized_return * 100
+    s.loc['Volatility (Ann.) [%]'] = np.sqrt((day_returns.var(ddof=int(bool(day_returns.shape))) + (1 + gmean_day_return)**2)**annual_trading_days - (1 + gmean_day_return)**(2*annual_trading_days)) * 100  # noqa: E501
+    # s.loc['Return (Ann.) [%]'] = gmean_day_return * annual_trading_days * 100
+    # s.loc['Risk (Ann.) [%]'] = day_returns.std(ddof=1) * np.sqrt(annual_trading_days) * 100
+
+    # Our Sharpe mismatches `empyrical.sharpe_ratio()` because they use arithmetic mean return
+    # and simple standard deviation
+    s.loc['Sharpe Ratio'] = np.clip((s.loc['Return (Ann.) [%]'] - risk_free_rate) / (s.loc['Volatility (Ann.) [%]'] or np.nan), 0, np.inf)  # noqa: E501
+    # Our Sortino mismatches `empyrical.sortino_ratio()` because they use arithmetic mean return
+    s.loc['Sortino Ratio'] = np.clip((annualized_return - risk_free_rate) / (np.sqrt(np.mean(day_returns.clip(-np.inf, 0)**2)) * np.sqrt(annual_trading_days)), 0, np.inf)  # noqa: E501
+    max_dd = -np.nan_to_num(dd.max())
+    s.loc['Calmar Ratio'] = np.clip(annualized_return / (-max_dd or np.nan), 0, np.inf)
+    s.loc['Max. Drawdown [%]'] = max_dd * 100
+    s.loc['Avg. Drawdown [%]'] = -dd_peaks.mean() * 100
+    s.loc['Max. Drawdown Duration'] = _round_timedelta(dd_dur.max())
+    s.loc['Avg. Drawdown Duration'] = _round_timedelta(dd_dur.mean())
+    s.loc['# Trades'] = n_trades = len(trades_df)
+    s.loc['Win Rate [%]'] = np.nan if not n_trades else (pl > 0).sum() / n_trades * 100  # noqa: E501
+    s.loc['Best Trade [%]'] = returns.max() * 100
+    s.loc['Worst Trade [%]'] = returns.min() * 100
+    mean_return = geometric_mean(returns)
+    s.loc['Avg. Trade [%]'] = mean_return * 100
+    s.loc['Max. Trade Duration'] = _round_timedelta(durations.max())
+    s.loc['Avg. Trade Duration'] = _round_timedelta(durations.mean())
+    s.loc['Profit Factor'] = returns[returns > 0].sum() / (abs(returns[returns < 0].sum()) or np.nan)  # noqa: E501
+    s.loc['Expectancy [%]'] = returns.mean() * 100
+    s.loc['SQN'] = np.sqrt(n_trades) * pl.mean() / (pl.std() or np.nan)
+
+    s.loc['_strategy'] = strategy_instance
+    s.loc['_equity_curve'] = equity_df
+    s.loc['_trades'] = trades_df
+
+    s = _Stats(s)
+    return s
+
+
+class _Stats(pd.Series):
+    def __repr__(self):
+        # Prevent expansion due to _equity and _trades dfs
+        with pd.option_context('max_colwidth', 20):
+            return super().__repr__()