ENH: Add Backtest.plot(plot_return=), akin to plot_equity=

Fixes #178

Author: kernc

backtesting/_plotting.py

@@ -147,7 +147,7 @@ def plot(*, results: pd.Series,
          df: pd.DataFrame,
          indicators: List[_Indicator],
          filename='', plot_width=None,
-         plot_equity=True, plot_pl=True,
+         plot_equity=True, plot_return=False, plot_pl=True,
          plot_volume=True, plot_drawdown=False,
          smooth_equity=False, relative_equity=True,
          superimpose=True, resample=True,
@@ -172,6 +172,7 @@ def plot(*, results: pd.Series,
 
     plot_volume = plot_volume and not df.Volume.isnull().all()
     plot_equity = plot_equity and not trades.empty
+    plot_return = plot_return and not trades.empty
     plot_pl = plot_pl and not trades.empty
     is_datetime_index = df.index.is_all_dates
 
@@ -274,7 +275,7 @@ def set_tooltips(fig, tooltips=(), vline=True, renderers=()):
             renderers=renderers, formatters=formatters,
             tooltips=tooltips, mode='vline' if vline else 'mouse'))
 
-    def _plot_equity_section():
+    def _plot_equity_section(is_return=False):
         """Equity section"""
         # Max DD Dur. line
         equity = equity_data['Equity'].copy()
@@ -307,10 +308,14 @@ def _plot_equity_section():
 
         if relative_equity:
             equity /= equity.iloc[0]
+        if is_return:
+            equity -= equity.iloc[0]
 
-        source.add(equity, 'equity')
+        yaxis_label = 'Return' if is_return else 'Equity'
+        source_key = 'eq_return' if is_return else 'equity'
+        source.add(equity, source_key)
         fig = new_indicator_figure(
-            y_axis_label="Equity",
+            y_axis_label=yaxis_label,
             **({} if plot_drawdown else dict(plot_height=110)))
 
         # High-watermark drawdown dents
@@ -322,16 +327,16 @@ def _plot_equity_section():
                   fill_color='#ffffea', line_color='#ffcb66')
 
         # Equity line
-        r = fig.line('index', 'equity', source=source, line_width=1.5, line_alpha=1)
+        r = fig.line('index', source_key, source=source, line_width=1.5, line_alpha=1)
         if relative_equity:
-            tooltip_format = '@equity{+0,0.[000]%}'
+            tooltip_format = f'@{source_key}{{+0,0.[000]%}}'
             tick_format = '0,0.[00]%'
             legend_format = '{:,.0f}%'
         else:
-            tooltip_format = '@equity{$ 0,0}'
+            tooltip_format = f'@{source_key}{{$ 0,0}}'
             tick_format = '$ 0.0 a'
             legend_format = '${:,.0f}'
-        set_tooltips(fig, [('Equity', tooltip_format)], renderers=[r])
+        set_tooltips(fig, [(yaxis_label, tooltip_format)], renderers=[r])
         fig.yaxis.formatter = NumeralTickFormatter(format=tick_format)
 
         # Peaks
@@ -569,6 +574,9 @@ def __eq__(self, other):
     if plot_equity:
         _plot_equity_section()
 
+    if plot_return:
+        _plot_equity_section(is_return=True)
+
     if plot_drawdown:
         figs_above_ohlc.append(_plot_drawdown_section())
 

backtesting/backtesting.py

@@ -1459,7 +1459,7 @@ def __repr__(self):
                 return super().__repr__()
 
     def plot(self, *, results: pd.Series = None, filename=None, plot_width=None,
-             plot_equity=True, plot_pl=True,
+             plot_equity=True, plot_return=False, plot_pl=True,
              plot_volume=True, plot_drawdown=False,
              smooth_equity=False, relative_equity=True,
              superimpose: Union[bool, str] = True,
@@ -1483,7 +1483,12 @@ def plot(self, *, results: pd.Series = None, filename=None, plot_width=None,
         currently non-adjustable.
 
         If `plot_equity` is `True`, the resulting plot will contain
-        an equity (cash plus assets) graph section.
+        an equity (initial cash plus assets) graph section. This is the same
+        as `plot_return` plus initial 100%.
+
+        If `plot_return` is `True`, the resulting plot will contain
+        a cumulative return graph section. This is the same
+        as `plot_equity` minus initial 100%.
 
         If `plot_pl` is `True`, the resulting plot will contain
         a profit/loss (P/L) indicator section.
@@ -1548,6 +1553,7 @@ def plot(self, *, results: pd.Series = None, filename=None, plot_width=None,
             filename=filename,
             plot_width=plot_width,
             plot_equity=plot_equity,
+            plot_return=plot_return,
             plot_pl=plot_pl,
             plot_volume=plot_volume,
             plot_drawdown=plot_drawdown,

backtesting/test/_test.py

@@ -563,6 +563,7 @@ def test_params(self):
         with _tempfile() as f:
             for p in dict(plot_volume=False,
                           plot_equity=False,
+                          plot_return=True,
                           plot_pl=False,
                           plot_drawdown=True,
                           superimpose=False,