ENH add ability to plot multiple stdev regions for the OOS cone in plotting.plot_rolling_returns. Update calling functions to use default of plotting these multiple regions: 1.0, 1.5, 2.0 stdevs

Author: Justin Lent

pyfolio/plotting.py

@@ -552,8 +552,9 @@ def plot_rolling_returns(
     live_start_date : datetime, optional
         The point in time when the strategy began live trading, after
         its backtest period.
-    cone_std : float, optional
-        The standard deviation to use for the cone plots.
+    cone_std : float, or tuple, optional
+        If float, The standard deviation to use for the cone plots.
+        If tuple, Tuple of standard deviation values to use for the cone plots
          - The cone is a normal distribution with this standard deviation
              centered around a linear regression.
     legend_loc : matplotlib.loc, optional
@@ -573,6 +574,23 @@ def plot_rolling_returns(
         The axes that were plotted on.
 
 """
+    def draw_cone(returns, num_stdev, live_start_date, ax):
+        cone_df = timeseries.cone_rolling(
+            returns,
+            num_stdev=num_stdev,
+            cone_fit_end_date=live_start_date)
+
+        cone_in_sample = cone_df[cone_df.index < live_start_date]
+        cone_out_of_sample = cone_df[cone_df.index > live_start_date]
+        cone_out_of_sample = cone_out_of_sample[
+            cone_out_of_sample.index < returns.index[-1]]
+
+        ax.fill_between(cone_out_of_sample.index,
+                        cone_out_of_sample.sd_down,
+                        cone_out_of_sample.sd_up,
+                        color='steelblue', alpha=0.25)
+
+        return cone_in_sample, cone_out_of_sample
 
     if ax is None:
         ax = plt.gca()
@@ -582,12 +600,9 @@ def plot_rolling_returns(
                          'factor_returns.')
     elif volatility_match and factor_returns is not None:
         bmark_vol = factor_returns.loc[returns.index].std()
-        df_cum_rets = timeseries.cum_returns(
-            (returns / returns.std()) * bmark_vol,
-            1.0
-        )
-    else:
-        df_cum_rets = timeseries.cum_returns(returns, 1.0)
+        returns = (returns / returns.std()) * bmark_vol
+
+    df_cum_rets = timeseries.cum_returns(returns, 1.0)
 
     y_axis_formatter = FuncFormatter(utils.one_dec_places)
     ax.yaxis.set_major_formatter(FuncFormatter(y_axis_formatter))
@@ -611,25 +626,27 @@ def plot_rolling_returns(
             label='Live', ax=ax, **kwargs)
 
         if cone_std is not None:
-            cone_df = timeseries.cone_rolling(
-                returns,
-                num_stdev=cone_std,
-                cone_fit_end_date=live_start_date)
-
-            cone_df_fit = cone_df[cone_df.index < live_start_date]
-
-            cone_df_live = cone_df[cone_df.index > live_start_date]
-            cone_df_live = cone_df_live[cone_df_live.index < returns.index[-1]]
-
-            cone_df_fit['line'].plot(
+            # check to see if cone_std was passed as a single value and,
+            # if so, just convert to list automatically
+            if isinstance(cone_std, float):
+                cone_std = [cone_std]
+
+            for cone_i in cone_std:
+                cone_in_sample, cone_out_of_sample = draw_cone(
+                    returns,
+                    cone_i,
+                    live_start_date,
+                    ax)
+
+            cone_in_sample['line'].plot(
                 ax=ax,
                 ls='--',
                 label='Backtest trend',
                 lw=2,
                 color='forestgreen',
                 alpha=0.7,
                 **kwargs)
-            cone_df_live['line'].plot(
+            cone_out_of_sample['line'].plot(
                 ax=ax,
                 ls='--',
                 label='Predicted trend',
@@ -638,11 +655,6 @@ def plot_rolling_returns(
                 alpha=0.7,
                 **kwargs)
 
-            ax.fill_between(cone_df_live.index,
-                            cone_df_live.sd_down,
-                            cone_df_live.sd_up,
-                            color='red', alpha=0.30)
-
     ax.axhline(1.0, linestyle='--', color='black', lw=2)
     ax.set_ylabel('Cumulative returns')
     ax.set_title('Cumulative Returns')

pyfolio/tears.py

@@ -43,7 +43,7 @@ def create_full_tear_sheet(returns, positions=None, transactions=None,
                            gross_lev=None,
                            live_start_date=None, bayesian=False,
                            sector_mappings=None,
-                           cone_std=1.0, set_context=True):
+                           cone_std=(1.0, 1.5, 2.0), set_context=True):
     """
     Generate a number of tear sheets that are useful
     for analyzing a strategy's performance.
@@ -95,8 +95,9 @@ def create_full_tear_sheet(returns, positions=None, transactions=None,
         after its backtest period.
     bayesian: boolean, optional
         If True, causes the generation of a Bayesian tear sheet.
-    cone_std : float, optional
-        The standard deviation to use for the cone plots.
+    cone_std : float, or tuple, optional
+        If float, The standard deviation to use for the cone plots.
+        If tuple, Tuple of standard deviation values to use for the cone plots
          - The cone is a normal distribution with this standard deviation
              centered around a linear regression.
     set_context : boolean, optional
@@ -126,7 +127,6 @@ def create_full_tear_sheet(returns, positions=None, transactions=None,
     if positions is not None:
         create_position_tear_sheet(returns, positions,
                                    gross_lev=gross_lev,
-                                   sector_mappings=sector_mappings,
                                    set_context=set_context)
 
         if transactions is not None:
@@ -142,7 +142,7 @@ def create_full_tear_sheet(returns, positions=None, transactions=None,
 
 @plotting_context
 def create_returns_tear_sheet(returns, live_start_date=None,
-                              cone_std=1.0,
+                              cone_std=(1.0, 1.5, 2.0),
                               benchmark_rets=None,
                               return_fig=False):
     """
@@ -164,8 +164,9 @@ def create_returns_tear_sheet(returns, live_start_date=None,
     live_start_date : datetime, optional
         The point in time when the strategy began live trading,
         after its backtest period.
-    cone_std : float, optional
-        The standard deviation to use for the cone plots.
+    cone_std : float, or tuple, optional
+        If float, The standard deviation to use for the cone plots.
+        If tuple, Tuple of standard deviation values to use for the cone plots
          - The cone is a normal distribution with this standard deviation
              centered around a linear regression.
     benchmark_rets : pd.Series, optional
@@ -232,7 +233,7 @@ def create_returns_tear_sheet(returns, live_start_date=None,
         returns,
         factor_returns=benchmark_rets,
         live_start_date=live_start_date,
-        cone_std=cone_std,
+        cone_std=None,
         volatility_match=True,
         ax=ax_rolling_returns_vol_match)
     ax_rolling_returns_vol_match.set_title(