Merge branch 'master' into feature/fix_auto_close

Author: Benouare

CONTRIBUTING.md

@@ -33,7 +33,7 @@ first [fork the project]. Then:
 
     git clone git@github.com:YOUR_USERNAME/backtesting.py
     cd backtesting.py
-    pip3 install -e .[doc,test,dev]
+    pip3 install -e '.[doc,test,dev]'
 
 [fork the project]: https://help.github.com/articles/fork-a-repo/
 

README.md

@@ -2,7 +2,7 @@
 
 Backtesting.py
 ==============
-[![Build Status](https://img.shields.io/github/workflow/status/kernc/backtesting.py/CI/master?style=for-the-badge)](https://github.com/kernc/backtesting.py/actions)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/kernc/backtesting.py/ci.yml?branch=master&style=for-the-badge)](https://github.com/kernc/backtesting.py/actions)
 [![Code Coverage](https://img.shields.io/codecov/c/gh/kernc/backtesting.py.svg?style=for-the-badge)](https://codecov.io/gh/kernc/backtesting.py)
 [![Backtesting on PyPI](https://img.shields.io/pypi/v/backtesting.svg?color=blue&style=for-the-badge)](https://pypi.org/project/backtesting)
 [![PyPI downloads](https://img.shields.io/pypi/dd/backtesting.svg?color=skyblue&style=for-the-badge)](https://pypi.org/project/backtesting)

backtesting/_plotting.py

@@ -145,7 +145,7 @@ def f(s, new_index=pd.Index(df.index.view(int)), bars=trades[column]):
             if s.size:
                 # Via int64 because on pandas recently broken datetime
                 mean_time = int(bars.loc[s.index].view(int).mean())
-                new_bar_idx = new_index.get_loc(mean_time, method='nearest')
+                new_bar_idx = new_index.get_indexer([mean_time], method='nearest')[0]
                 return new_bar_idx
         return f
 
@@ -166,7 +166,7 @@ def plot(*, results: pd.Series,
          indicators: List[_Indicator],
          filename='', plot_width=None,
          plot_equity=True, plot_return=False, plot_pl=True,
-         plot_volume=True, plot_drawdown=False,
+         plot_volume=True, plot_drawdown=False, plot_trades=True,
          smooth_equity=False, relative_equity=True,
          superimpose=True, resample=True,
          reverse_indicators=True,
@@ -609,7 +609,8 @@ def __eq__(self, other):
         _plot_superimposed_ohlc()
 
     ohlc_bars = _plot_ohlc()
-    _plot_ohlc_trades()
+    if plot_trades:
+        _plot_ohlc_trades()
     indicator_figs = _plot_indicators()
     if reverse_indicators:
         indicator_figs = indicator_figs[::-1]

backtesting/_stats.py

@@ -65,6 +65,7 @@ def compute_stats(
             'ReturnPct': [t.pl_pct for t in trades],
             'EntryTime': [t.entry_time for t in trades],
             'ExitTime': [t.exit_time for t in trades],
+            'Tag': [t.tag for t in trades],
         })
         trades_df['Duration'] = trades_df['ExitTime'] - trades_df['EntryTime']
     del trades
@@ -127,7 +128,8 @@ def _round_timedelta(value, _period=_data_period(index)):
     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
+    win_rate = np.nan if not n_trades else (pl > 0).mean()
+    s.loc['Win Rate [%]'] = win_rate * 100
     s.loc['Best Trade [%]'] = returns.max() * 100
     s.loc['Worst Trade [%]'] = returns.min() * 100
     mean_return = geometric_mean(returns)
@@ -137,8 +139,7 @@ def _round_timedelta(value, _period=_data_period(index)):
     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)
-    win_prob = (pl > 0).sum() / n_trades
-    s.loc['Kelly Criterion'] = win_prob - (1 - win_prob) / (pl[pl > 0].mean() / pl[pl < 0].mean())  # noqa: E501
+    s.loc['Kelly Criterion'] = win_rate - (1 - win_rate) / (pl[pl > 0].mean() / -pl[pl < 0].mean())
 
     s.loc['_strategy'] = strategy_instance
     s.loc['_equity_curve'] = equity_df

backtesting/_util.py

@@ -136,7 +136,7 @@ def _update(self):
         self.__arrays['__index'] = index
 
     def __repr__(self):
-        i = min(self.__i, len(self.__df) - 1)
+        i = min(self.__i, len(self.__df)) - 1
         index = self.__arrays['__index'][i]
         items = ', '.join(f'{k}={v}' for k, v in self.__df.iloc[i].items())
         return f'<Data i={i} ({index}) {items}>'

backtesting/backtesting.py

@@ -80,7 +80,7 @@ def I(self,  # noqa: E743
           name=None, plot=True, overlay=None, color=None, scatter=False,
           **kwargs) -> np.ndarray:
         """
-        Declare indicator. An indicator is just an array of values,
+        Declare an indicator. An indicator is just an array of values,
         but one that is revealed gradually in
         `backtesting.backtesting.Strategy.next` much like
         `backtesting.backtesting.Strategy.data` is.
@@ -133,7 +133,7 @@ def init():
 
         if value is not None:
             value = try_(lambda: np.asarray(value, order='C'), None)
-        is_arraylike = value is not None
+        is_arraylike = bool(value is not None and value.shape)
 
         # Optionally flip the array if the user returned e.g. `df.values`
         if is_arraylike and np.argmax(value.shape) == 0:
@@ -142,7 +142,7 @@ def init():
         if not is_arraylike or not 1 <= value.ndim <= 2 or value.shape[-1] != len(self._data.Close):
             raise ValueError(
                 'Indicators must return (optionally a tuple of) numpy.arrays of same '
-                f'length as `data` (data shape: {self._data.Close.shape}; indicator "{name}"'
+                f'length as `data` (data shape: {self._data.Close.shape}; indicator "{name}" '
                 f'shape: {getattr(value, "shape" , "")}, returned value: {value})')
 
         if plot and overlay is None and np.issubdtype(value.dtype, np.number):
@@ -199,7 +199,8 @@ def buy(self, *,
             limit: Optional[float] = None,
             stop: Optional[float] = None,
             sl: Optional[float] = None,
-            tp: Optional[float] = None):
+            tp: Optional[float] = None,
+            tag: object = None):
         """
         Place a new long order. For explanation of parameters, see `Order` and its properties.
 
@@ -209,14 +210,15 @@ def buy(self, *,
         """
         assert 0 < size < 1 or round(size) == size, \
             "size must be a positive fraction of equity, or a positive whole number of units"
-        return self._broker.new_order(size, limit, stop, sl, tp)
+        return self._broker.new_order(size, limit, stop, sl, tp, tag)
 
     def sell(self, *,
              size: float = _FULL_EQUITY,
              limit: Optional[float] = None,
              stop: Optional[float] = None,
              sl: Optional[float] = None,
-             tp: Optional[float] = None):
+             tp: Optional[float] = None,
+             tag: object = None):
         """
         Place a new short order. For explanation of parameters, see `Order` and its properties.
 
@@ -228,7 +230,7 @@ def sell(self, *,
         """
         assert 0 < size < 1 or round(size) == size, \
             "size must be a positive fraction of equity, or a positive whole number of units"
-        return self._broker.new_order(-size, limit, stop, sl, tp)
+        return self._broker.new_order(-size, limit, stop, sl, tp, tag)
 
     @property
     def equity(self) -> float:
@@ -386,7 +388,8 @@ def __init__(self, broker: '_Broker',
                  stop_price: Optional[float] = None,
                  sl_price: Optional[float] = None,
                  tp_price: Optional[float] = None,
-                 parent_trade: Optional['Trade'] = None):
+                 parent_trade: Optional['Trade'] = None,
+                 tag: object = None):
         self.__broker = broker
         assert size != 0
         self.__size = size
@@ -395,6 +398,7 @@ def __init__(self, broker: '_Broker',
         self.__sl_price = sl_price
         self.__tp_price = tp_price
         self.__parent_trade = parent_trade
+        self.__tag = tag
 
     def _replace(self, **kwargs):
         for k, v in kwargs.items():
@@ -410,6 +414,7 @@ def __repr__(self):
                                                  ('sl', self.__sl_price),
                                                  ('tp', self.__tp_price),
                                                  ('contingent', self.is_contingent),
+                                                 ('tag', self.__tag),
                                              ) if value is not None))
 
     def cancel(self):
@@ -481,6 +486,14 @@ def tp(self) -> Optional[float]:
     def parent_trade(self):
         return self.__parent_trade
 
+    @property
+    def tag(self):
+        """
+        Arbitrary value (such as a string) which, if set, enables tracking
+        of this order and the associated `Trade` (see `Trade.tag`).
+        """
+        return self.__tag
+
     __pdoc__['Order.parent_trade'] = False
 
     # Extra properties
@@ -515,7 +528,7 @@ class Trade:
     When an `Order` is filled, it results in an active `Trade`.
     Find active trades in `Strategy.trades` and closed, settled trades in `Strategy.closed_trades`.
     """
-    def __init__(self, broker: '_Broker', size: int, entry_price: float, entry_bar):
+    def __init__(self, broker: '_Broker', size: int, entry_price: float, entry_bar, tag):
         self.__broker = broker
         self.__size = size
         self.__entry_price = entry_price
@@ -524,10 +537,12 @@ def __init__(self, broker: '_Broker', size: int, entry_price: float, entry_bar):
         self.__exit_bar: Optional[int] = None
         self.__sl_order: Optional[Order] = None
         self.__tp_order: Optional[Order] = None
+        self.__tag = tag
 
     def __repr__(self):
         return f'<Trade size={self.__size} time={self.__entry_bar}-{self.__exit_bar or ""} ' \
-               f'price={self.__entry_price}-{self.__exit_price or ""} pl={self.pl:.0f}>'
+               f'price={self.__entry_price}-{self.__exit_price or ""} pl={self.pl:.0f}' \
+               f'{" tag="+str(self.__tag) if self.__tag is not None else ""}>'
 
     def _replace(self, **kwargs):
         for k, v in kwargs.items():
@@ -541,7 +556,7 @@ def close(self, portion: float = 1.):
         """Place new `Order` to close `portion` of the trade at next market price."""
         assert 0 < portion <= 1, "portion must be a fraction between 0 and 1"
         size = copysign(max(1, round(abs(self.__size) * portion)), -self.__size)
-        order = Order(self.__broker, size, parent_trade=self)
+        order = Order(self.__broker, size, parent_trade=self, tag=self.__tag)
         self.__broker.orders.insert(0, order)
 
     # Fields getters
@@ -574,6 +589,19 @@ def exit_bar(self) -> Optional[int]:
         """
         return self.__exit_bar
 
+    @property
+    def tag(self):
+        """
+        A tag value inherited from the `Order` that opened
+        this trade.
+
+        This can be used to track trades and apply conditional
+        logic / subgroup analysis.
+
+        See also `Order.tag`.
+        """
+        return self.__tag
+
     @property
     def _sl_order(self):
         return self.__sl_order
@@ -665,7 +693,7 @@ def __set_contingent(self, type, price):
             order.cancel()
         if price:
             kwargs = {'stop': price} if type == 'sl' else {'limit': price}
-            order = self.__broker.new_order(-self.size, trade=self, **kwargs)
+            order = self.__broker.new_order(-self.size, trade=self, tag=self.tag, **kwargs)
             setattr(self, attr, order)
 
 
@@ -700,6 +728,7 @@ def new_order(self,
                   stop: Optional[float] = None,
                   sl: Optional[float] = None,
                   tp: Optional[float] = None,
+                  tag: object = None,
                   *,
                   trade: Optional[Trade] = None):
         """
@@ -725,7 +754,7 @@ def new_order(self,
                     "Short orders require: "
                     f"TP ({tp}) < LIMIT ({limit or stop or adjusted_price}) < SL ({sl})")
 
-        order = Order(self, size, limit, stop, sl, tp, trade)
+        order = Order(self, size, limit, stop, sl, tp, trade, tag)
         # Put the new order in the order queue,
         # inserting SL/TP/trade-closing orders in-front
         if trade:
@@ -905,7 +934,12 @@ def _process_orders(self):
 
             # Open a new trade
             if need_size:
-                self._open_trade(adjusted_price, need_size, order.sl, order.tp, time_index)
+                self._open_trade(adjusted_price,
+                                 need_size,
+                                 order.sl,
+                                 order.tp,
+                                 time_index,
+                                 order.tag)
 
                 # We need to reprocess the SL/TP orders newly added to the queue.
                 # This allows e.g. SL hitting in the same bar the order was open.
@@ -964,8 +998,8 @@ def _close_trade(self, trade: Trade, price: float, time_index: int):
         self._cash += trade.pl
 
     def _open_trade(self, price: float, size: int,
-                    sl: Optional[float], tp: Optional[float], time_index: int):
-        trade = Trade(self, size, price, time_index)
+                    sl: Optional[float], tp: Optional[float], time_index: int, tag):
+        trade = Trade(self, size, price, time_index, tag)
         self.trades.append(trade)
         # Create SL/TP (bracket) orders.
         # Make sure SL order is created first so it gets adversarially processed before TP order
@@ -1143,6 +1177,13 @@ def run(self, **kwargs) -> pd.Series:
             _equity_curve                           Eq...
             _trades                       Size  EntryB...
             dtype: object
+
+        .. warning::
+            You may obtain different results for different strategy parameters.
+            E.g. if you use 50- and 200-bar SMA, the trading simulation will
+            begin on bar 201. The actual length of delay is equal to the lookback
+            period of the `Strategy.I` indicator which lags the most.
+            Obviously, this can affect results.
         """
         data = _Data(self._data.copy(deep=False))
         broker: _Broker = self._broker(data=data)
@@ -1518,7 +1559,7 @@ def _mp_task(backtest_uuid, batch_index):
 
     def plot(self, *, results: pd.Series = None, filename=None, plot_width=None,
              plot_equity=True, plot_return=False, plot_pl=True,
-             plot_volume=True, plot_drawdown=False,
+             plot_volume=True, plot_drawdown=False, plot_trades=True,
              smooth_equity=False, relative_equity=True,
              superimpose: Union[bool, str] = True,
              resample=True, reverse_indicators=False,
@@ -1557,6 +1598,9 @@ def plot(self, *, results: pd.Series = None, filename=None, plot_width=None,
         If `plot_drawdown` is `True`, the resulting plot will contain
         a separate drawdown graph section.
 
+        If `plot_trades` is `True`, the stretches between trade entries
+        and trade exits are marked by hash-marked tractor beams.
+
         If `smooth_equity` is `True`, the equity graph will be
         interpolated between fixed points at trade closing times,
         unaffected by any interim asset volatility.
@@ -1615,6 +1659,7 @@ def plot(self, *, results: pd.Series = None, filename=None, plot_width=None,
             plot_pl=plot_pl,
             plot_volume=plot_volume,
             plot_drawdown=plot_drawdown,
+            plot_trades=plot_trades,
             smooth_equity=smooth_equity,
             relative_equity=relative_equity,
             superimpose=superimpose,

backtesting/test/_test.py

@@ -276,7 +276,7 @@ def test_compute_stats(self):
                 'Return [%]': 414.2298999999996,
                 'Volatility (Ann.) [%]': 36.49390889140787,
                 'SQN': 1.0766187356697705,
-                'Kelly Criterion': 0.7875234266909678,
+                'Kelly Criterion': 0.1518705127029717,
                 'Sharpe Ratio': 0.5803778344714113,
                 'Sortino Ratio': 1.0847880675854096,
                 'Start': pd.Timestamp('2004-08-19 00:00:00'),
@@ -304,7 +304,7 @@ def almost_equal(a, b):
         self.assertSequenceEqual(
             sorted(stats['_trades'].columns),
             sorted(['Size', 'EntryBar', 'ExitBar', 'EntryPrice', 'ExitPrice',
-                    'PnL', 'ReturnPct', 'EntryTime', 'ExitTime', 'Duration']))
+                    'PnL', 'ReturnPct', 'EntryTime', 'ExitTime', 'Duration', 'Tag']))
 
     def test_compute_stats_bordercase(self):
 
@@ -531,6 +531,18 @@ def coroutine(self):
         stats = self._Backtest(coroutine, close_all_at_end=True).run()
         self.assertEqual(len(stats._trades), 1)
 
+    def test_order_tag(self):
+        def coroutine(self):
+            yield self.buy(size=2, tag=1)
+            yield self.sell(size=1, tag='s')
+            yield self.sell(size=1)
+
+            yield self.buy(tag=2)
+            yield self.position.close()
+
+        stats = self._Backtest(coroutine).run()
+        self.assertEqual(list(stats._trades.Tag), [1, 1, 2])
+
 
 class TestOptimize(TestCase):
     def test_optimize(self):
@@ -663,6 +675,7 @@ def test_params(self):
                           plot_return=True,
                           plot_pl=False,
                           plot_drawdown=True,
+                          plot_trades=False,
                           superimpose=False,
                           resample='1W',
                           smooth_equity=False,

setup.py

@@ -46,11 +46,11 @@
             'test': [
                 'seaborn',
                 'matplotlib',
-                'scikit-learn',
+                'scikit-learn <= 1.1.3',  # Pinned due to boken scikit-optimize
                 'scikit-optimize',
             ],
             'dev': [
-                'ruff',
+                'ruff==0.0.160',
                 'coverage',
                 'mypy',
             ],