ENH Added round trip tearheet and supporting functions

Author: a-campbell

pyfolio/plotting.py

@@ -16,11 +16,13 @@
 
 import pandas as pd
 import numpy as np
+import scipy as sp
 
 import seaborn as sns
 import matplotlib
 import matplotlib.pyplot as plt
 from matplotlib.ticker import FuncFormatter
+import matplotlib.lines as mlines
 
 from sklearn import preprocessing
 
@@ -1402,3 +1404,116 @@ def cumulate_returns(x):
     ax.set_xticklabels(xticks_label)
 
     return ax
+
+
+def plot_round_trip_life_times(round_trips, ax=None):
+    """
+    Plots timespans and directions of round trip trades.
+
+    Parameters
+    ----------
+    round_trips : pd.DataFrame
+        DataFrame with one row per round trip trade.
+        - See full explanation in txn.extract_round_trips
+    ax : matplotlib.Axes, optional
+        Axes upon which to plot.
+    **kwargs, optional
+        Passed to seaborn plotting function.
+
+    Returns
+    -------
+    ax : matplotlib.Axes
+        The axes that were plotted on.
+    """
+    if ax is None:
+        ax = plt.subplot()
+
+    symbols = round_trips.symbol.unique()
+    symbol_idx = pd.Series(np.arange(len(symbols)), index=symbols)
+
+    for symbol, sym_round_trips in round_trips.groupby('symbol'):
+        for _, row in sym_round_trips.iterrows():
+            c = 'b' if row.long else 'r'
+            y_ix = symbol_idx[symbol]
+            ax.plot([row['open_dt'], row['close_dt']],
+                    [y_ix, y_ix], color=c)
+
+    ax.set_yticklabels(symbols)
+
+    red_line = mlines.Line2D([], [], color='r', label='Long')
+    blue_line = mlines.Line2D([], [], color='b', label='Short')
+    ax.legend(handles=[red_line, blue_line], loc=0)
+
+    return ax
+
+
+def show_profit_attribtion(round_trips):
+    """
+    Prints the share of total PnL contributed by each
+    traded name.
+
+    Parameters
+    ----------
+    round_trips : pd.DataFrame
+        DataFrame with one row per round trip trade.
+        - See full explanation in txn.extract_round_trips
+    ax : matplotlib.Axes, optional
+        Axes upon which to plot.
+    **kwargs, optional
+        Passed to seaborn plotting function.
+
+    Returns
+    -------
+    ax : matplotlib.Axes
+        The axes that were plotted on.
+    """
+
+    total_pnl = round_trips['pnl'].sum()
+    pct_profit_attribution = round_trips.groupby(
+        'symbol')['pnl'].sum() / total_pnl
+
+    print('\nProfitability (PnL / PnL total) per name:')
+    print(pct_profit_attribution.sort(inplace=False, ascending=False))
+
+
+def plot_prob_profit_trade(round_trips, ax=None):
+    """
+    Plots a probability distribution for the event of making
+    a profitable trade.
+
+    Parameters
+    ----------
+    round_trips : pd.DataFrame
+        DataFrame with one row per round trip trade.
+        - See full explanation in txn.extract_round_trips
+    ax : matplotlib.Axes, optional
+        Axes upon which to plot.
+    **kwargs, optional
+        Passed to seaborn plotting function.
+
+    Returns
+    -------
+    ax : matplotlib.Axes
+        The axes that were plotted on.
+    """
+
+    x = np.linspace(0, 1., 500)
+
+    round_trips['profitable'] = round_trips.pnl > 0
+
+    dist = sp.stats.beta(round_trips.profitable.sum(),
+                         (~round_trips.profitable).sum())
+    y = dist.pdf(x)
+    lower_perc = dist.ppf(.025)
+    upper_perc = dist.ppf(.975)
+
+    lower_plot = dist.ppf(.001)
+    upper_plot = dist.ppf(.999)
+    if ax is None:
+        ax = plt.subplot()
+    ax.plot(x, y)
+    ax.axvline(lower_perc, color='0.5')
+    ax.axvline(upper_perc, color='0.5')
+
+    ax.set(xlabel='Probability making a profitable decision', ylabel='Belief',
+           xlim=(lower_plot, upper_plot), ylim=(0, y.max() + 1.))

pyfolio/tears.py

@@ -167,6 +167,9 @@ def create_full_tear_sheet(returns, positions=None, transactions=None,
                                   unadjusted_returns=unadjusted_returns,
                                   set_context=set_context)
 
+            create_round_trip_tear_sheet(transactions, positions,
+                                         sector_mappings=sector_mappings)
+
     if bayesian:
         create_bayesian_tear_sheet(returns,
                                    live_start_date=live_start_date,
@@ -435,8 +438,6 @@ def create_txn_tear_sheet(returns, positions, transactions,
          - See full explanation in create_full_tear_sheet.
     return_fig : boolean, optional
         If True, returns the figure that was plotted on.
-    set_context : boolean, optional
-        If True, set default plotting style context.
     """
     vertical_sections = 5 if unadjusted_returns is not None else 3
 
@@ -479,6 +480,101 @@ def create_txn_tear_sheet(returns, positions, transactions,
         return fig
 
 
+@plotting_context
+def create_round_trip_tear_sheet(transactions, positions,
+                                 sector_mappings=None,
+                                 return_fig=False):
+    """
+    Generate a number of figures and plots describing the duration,
+    frequency, and profitability of trade "round trips."
+    A round trip is started when a new long or short position is
+    opened and is only completed when the number of shares in that
+    position returns to or crosses zero.
+
+    Parameters
+    ----------
+    positions : pd.DataFrame
+        Daily net position values.
+         - See full explanation in create_full_tear_sheet.
+    transactions : pd.DataFrame
+        Prices and amounts of executed trades. One row per trade.
+         - See full explanation in create_full_tear_sheet.
+    sector_mappings : dict or pd.Series, optional
+        Security identifier to sector mapping.
+        Security ids as keys, sectors as values.
+    return_fig : boolean, optional
+        If True, returns the figure that was plotted on.
+    """
+
+    transactions_closed = txn.add_closing_transactions(positions, transactions)
+    trades = txn.extract_round_trips(transactions_closed)
+
+    if len(trades) < 5:
+        warnings.warn(
+            """Fewer than 5 round-trip trades made.
+               Skipping round trip tearsheet.""", UserWarning)
+        return
+
+    ndays = len(positions)
+
+    print(trades.drop(['open_dt', 'close_dt', 'symbol'],
+                      axis='columns').describe())
+    print('Percent of trades profitable = {:.4}%'.format(
+          (trades.pnl > 0).mean() * 100))
+
+    winning_trades = trades[trades.pnl > 0]
+    losing_trades = trades[trades.pnl < 0]
+    print('Mean profits per winning trade = {:.4}'.format(
+        winning_trades.pnl.mean()))
+    print('Mean loss per losing trade = {:.4}').format(
+        losing_trades.pnl.abs().mean())
+
+    print('A decision is made every {:.4} days.'.format(ndays / len(trades)))
+    print('{:.4} trading decisions per day.'.format(len(trades) * 1. / ndays))
+    print('{:.4} trading decisions per month.'.format(
+        len(trades) * 1. / (ndays / 21)))
+
+    plotting.show_profit_attribtion(trades)
+
+    if sector_mappings is not None:
+        sector_trades = txn.apply_sector_mappings_to_round_trips(
+            trades, sector_mappings)
+        plotting.show_profit_attribtion(sector_trades)
+
+    fig = plt.figure(figsize=(14, 3 * 6))
+
+    fig = plt.figure(figsize=(14, 3 * 6))
+    gs = gridspec.GridSpec(3, 2, wspace=0.5, hspace=0.5)
+
+    ax_trade_lifetimes = plt.subplot(gs[0, :])
+    ax_prob_profit_trade = plt.subplot(gs[1, 0])
+    ax_holding_time = plt.subplot(gs[1, 1])
+    ax_pnl_per_round_trip_dollars = plt.subplot(gs[2, 0])
+    ax_pnl_per_round_trip_pct = plt.subplot(gs[2, 1])
+
+    plotting.plot_round_trip_life_times(trades, ax=ax_trade_lifetimes)
+
+    plotting.plot_prob_profit_trade(trades, ax=ax_prob_profit_trade)
+
+    trade_holding_times = [x.days for x in trades['duration']]
+    sns.distplot(trade_holding_times, kde=False, ax=ax_holding_time)
+    ax_holding_time.set(xlabel='holding time in days')
+
+    sns.distplot(trades.pnl, kde=False, ax=ax_pnl_per_round_trip_dollars)
+    ax_pnl_per_round_trip_dollars.set(xlabel='PnL per round-trip trade in $')
+
+    pnl_pct = trades.pnl / trades.pnl.sum() * 100
+    sns.distplot(pnl_pct, kde=False, ax=ax_pnl_per_round_trip_pct)
+    ax_pnl_per_round_trip_pct.set(
+        xlabel='PnL per round-trip trade in % of total profit')
+
+    gs.tight_layout(fig)
+
+    plt.show()
+    if return_fig:
+        return fig
+
+
 @plotting_context
 def create_interesting_times_tear_sheet(
         returns, benchmark_rets=None, legend_loc='best', return_fig=False):

pyfolio/tests/test_txn.py

@@ -1,17 +1,24 @@
+from nose_parameterized import parameterized
+
 from unittest import TestCase
 
 from pandas import (
     Series,
     DataFrame,
-    date_range
+    date_range,
+    Timedelta
 )
-from pandas.util.testing import (assert_series_equal)
+from pandas.util.testing import (assert_series_equal,
+                                 assert_frame_equal)
 
 from pyfolio.txn import (get_turnover,
-                         adjust_returns_for_slippage)
+                         adjust_returns_for_slippage,
+                         extract_round_trips,
+                         add_closing_transactions)
 
 
 class TransactionsTestCase(TestCase):
+    dates = date_range(start='2015-01-01', freq='D', periods=20)
 
     def test_get_turnover(self):
         """
@@ -80,3 +87,64 @@ def test_adjust_returns_for_slippage(self):
         result = adjust_returns_for_slippage(returns, turnover, slippage_bps)
 
         assert_series_equal(result, expected)
+
+    @parameterized.expand([
+        (DataFrame(data=[[2, 10, 'A'],
+                         [-2, 15, 'A']],
+                   columns=['amount', 'price', 'symbol'],
+                   index=dates[:2]),
+         DataFrame(data=[[dates[0], dates[1], Timedelta(days=1),
+                          10, True, 'A']],
+                   columns=['open_dt', 'close_dt',
+                            'duration', 'pnl', 'long', 'symbol'],
+                   index=[0])
+         ),
+        (DataFrame(data=[[2, 10, 'A'],
+                         [2, 15, 'A'],
+                         [-9, 10, 'A']],
+                   columns=['amount', 'price', 'symbol'],
+                   index=dates[:3]),
+         DataFrame(data=[[dates[0], dates[2], Timedelta(days=2),
+                          -10, True, 'A']],
+                   columns=['open_dt', 'close_dt',
+                            'duration', 'pnl', 'long', 'symbol'],
+                   index=[0])
+         ),
+        (DataFrame(data=[[2, 10, 'A'],
+                         [-4, 15, 'A'],
+                         [3, 20, 'A']],
+                   columns=['amount', 'price', 'symbol'],
+                   index=dates[:3]),
+         DataFrame(data=[[dates[0], dates[1], Timedelta(days=1),
+                          10, True, 'A'],
+                         [dates[1] + Timedelta(seconds=1), dates[2],
+                          Timedelta(days=1) - Timedelta(seconds=1),
+                          -10, False, 'A']],
+                   columns=['open_dt', 'close_dt',
+                            'duration', 'pnl', 'long', 'symbol'],
+                   index=[0, 1])
+         )
+    ])
+    def test_extract_round_trips(self, transactions, expected):
+        round_trips = extract_round_trips(transactions)
+        assert_frame_equal(round_trips, expected)
+
+    def test_add_closing_trades(self):
+        dates = date_range(start='2015-01-01', freq='D', periods=20)
+        transactions = DataFrame(data=[[2, 10, 'A'],
+                                       [-5, 10, 'A']],
+                                 columns=['amount', 'price', 'symbol'],
+                                 index=[dates[:2]])
+        positions = DataFrame(data=[[20, 0],
+                                    [-30, 30],
+                                    [-60, 30]],
+                              columns=['A', 'cash'],
+                              index=[dates[:3]])
+        expected = DataFrame(data=[[2, 10, 'A'],
+                                   [-5, 10, 'A'],
+                                   [3, 20., 'A']],
+                             columns=['amount', 'price', 'symbol'],
+                             index=[dates[:3]])
+
+        transactions_closed = add_closing_transactions(positions, transactions)
+        assert_frame_equal(transactions_closed, expected)