PyFolio API Reference

See also

get_backtest() and AlgorithmResult provide a higher-level interface for running pyfolio tearsheets on Quantopian backtests.

Quick Reference

Tear Sheets

create_bayesian_tear_sheet Generate a number of Bayesian distributions and a Bayesian cone plot of returns.
create_capacity_tear_sheet Generates a report detailing portfolio size constraints set by least liquid tickers.
create_full_tear_sheet Generate a number of tear sheets that are useful for analyzing a strategy's performance.
create_interesting_times_tear_sheet Generate a number of returns plots around interesting points in time, like the flash crash and 9/11.
create_perf_attrib_tear_sheet Generate plots and tables for analyzing a strategy's performance.
create_position_tear_sheet Generate a number of plots for analyzing a strategy's positions and holdings.
create_returns_tear_sheet Generate a number of plots for analyzing a strategy's returns.
create_risk_tear_sheet Creates risk tear sheet: computes and plots style factor exposures, sector exposures, market cap exposures and volume exposures.
create_round_trip_tear_sheet 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.
create_simple_tear_sheet Simpler version of create_full_tear_sheet; generates summary performance statistics and important plots as a single image.
create_txn_tear_sheet Generate a number of plots for analyzing a strategy's transactions.

Detailed Reference

Tear Sheets

pyfolio.create_bayesian_tear_sheet(*args, **kwargs)

Generate a number of Bayesian distributions and a Bayesian cone plot of returns.

Plots: Sharpe distribution, annual volatility distribution, annual alpha distribution, beta distribution, predicted 1 and 5 day returns distributions, and a cumulative returns cone plot.

Parameters:
  • returns (pd.Series) -- Daily returns of the strategy, noncumulative. See full explanation in create_full_tear_sheet.
  • benchmark_rets (pd.Series or pd.DataFrame, optional) -- Daily noncumulative returns of the benchmark. This is in the same style as returns.
  • live_start_date (datetime, optional) -- The point in time when the strategy began live trading, after its backtest period.
  • samples (int, optional) -- Number of posterior samples to draw.
  • return_fig (boolean, optional) -- If True, returns the figure that was plotted on.
  • set_context (boolean, optional) -- If True, set default plotting style context.
  • stoch_vol (boolean, optional) -- If True, run and plot the stochastic volatility model
pyfolio.create_capacity_tear_sheet(*args, **kwargs)

Generates a report detailing portfolio size constraints set by least liquid tickers. Plots a "capacity sweep," a curve describing projected sharpe ratio given the slippage penalties that are applied at various capital bases.

Parameters:
  • returns (pd.Series) --

    Daily returns of the strategy, noncumulative.

    See full explanation in create_full_tear_sheet.

  • 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.

  • market_data (pd.Panel) -- Panel with items axis of 'price' and 'volume' DataFrames. The major and minor axes should match those of the the passed positions DataFrame (same dates and symbols).
  • liquidation_daily_vol_limit (float) -- Max proportion of a daily bar that can be consumed in the process of liquidating a position in the "days to liquidation" analysis.
  • trade_daily_vol_limit (float) -- Flag daily transaction totals that exceed proportion of daily bar.
  • last_n_days (integer) -- Compute max position allocation and dollar volume for only the last N days of the backtest
  • days_to_liquidate_limit (integer) -- Display all tickers with greater max days to liquidation.
  • estimate_intraday (boolean or str, optional) -- Approximate returns for intraday strategies. See description in create_full_tear_sheet.
pyfolio.create_full_tear_sheet(returns, positions=None, transactions=None, market_data=None, benchmark_rets=None, slippage=None, live_start_date=None, sector_mappings=None, bayesian=False, round_trips=False, estimate_intraday='infer', hide_positions=False, cone_std=(1.0, 1.5, 2.0), bootstrap=False, unadjusted_returns=None, risk=False, style_factor_panel=None, sectors=None, caps=None, shares_held=None, volumes=None, percentile=None, turnover_denom='AGB', set_context=True, factor_returns=None, factor_loadings=None, pos_in_dollars=True, header_rows=None, factor_partitions={'sector': ['basic_materials', 'consumer_cyclical', 'financial_services', 'real_estate', 'consumer_defensive', 'health_care', 'utilities', 'communication_services', 'energy', 'industrials', 'technology'], 'style': ['momentum', 'size', 'value', 'reversal_short_term', 'volatility']})

Generate a number of tear sheets that are useful for analyzing a strategy's performance.

Fetches benchmarks if needed.

Creates tear sheets for returns, and significant events. If possible, also creates tear sheets for position analysis, transaction analysis, and Bayesian analysis.

Parameters:
  • returns (pd.Series) --

    Daily returns of the strategy, noncumulative. This is a time series with decimal returns.

    Example:

    --------------------------
    2015-07-16  |  -0.012143 |
    --------------------------
    2015-07-17  |   0.045350 |
    --------------------------
    2015-07-20  |   0.030957 |
    --------------------------
    2015-07-21  |   0.004902 |
    --------------------------
    
  • positions (pd.DataFrame, optional) --

    Daily net position values. This is a time series of dollar amount invested in each position and cash.

    Days where stocks are not held can be represented by 0 or NaN.

    Non-working capital is labelled 'cash'.

    Example:

    ----------------------------------------------------
          index |      'AAPL' |     'MSFT'  |     cash |
    ----------------------------------------------------
     2014-01-09 | 13939.3800  | -14012.9930 | 711.5585 |
    ----------------------------------------------------
     2014-01-12 | 14492.6300  | -14624.8700 | 27.1821  |
    ----------------------------------------------------
     2014-01-13 | -13853.2800 |  13653.6400 | -43.6375 |
    ----------------------------------------------------
    
  • transactions (pd.DataFrame, optional) --

    Executed trade volumes and fill prices.

    One row per trade. Trades on different names that occur at the same time will have identical indices.

    Example:

    ---------------------------------------------------
                   index | amount |   price |  symbol |
    ---------------------------------------------------
     2004-01-09 12:18:01 |    483 |  324.12 |  'AAPL' |
    ---------------------------------------------------
     2004-01-09 12:18:01 |    122 |   83.10 |  'MSFT' |
    ---------------------------------------------------
     2004-01-13 14:12:23 |    -75 |  340.43 |  'AAPL' |
    ---------------------------------------------------
    
  • market_data (pd.Panel, optional) -- Panel with items axis of 'price' and 'volume' DataFrames. The major and minor axes should match those of the the passed positions DataFrame (same dates and symbols).
  • slippage (int/float, optional) --

    Basis points of slippage to apply to returns before generating tearsheet stats and plots.

    If a value is provided, slippage parameter sweep plots will be generated from the unadjusted returns.

    Transactions and positions must also be passed.

    See txn.adjust_returns_for_slippage for more details.

  • live_start_date (datetime, optional) -- The point in time when the strategy began live trading, after its backtest period. This datetime should be normalized.
  • hide_positions (bool, optional) -- If True, will not output any symbol names.
  • bayesian (boolean, optional) -- If True, causes the generation of a Bayesian tear sheet.
  • round_trips (boolean, optional) -- If True, causes the generation of a round trip tear sheet.
  • sector_mappings (dict or pd.Series, optional) -- Security identifier to sector mapping. Security ids as keys, sectors as values.
  • estimate_intraday (boolean or str, optional) -- Instead of using the end-of-day positions, use the point in the day where we have the most $ invested. This will adjust positions to better approximate and represent how an intraday strategy behaves. By default, this is 'infer', and an attempt will be made to detect an intraday strategy. Specifying this value will prevent detection.
  • 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.

  • bootstrap (boolean (optional)) -- Whether to perform bootstrap analysis for the performance metrics. Takes a few minutes longer.
  • turnover_denom (str) --

    Either AGB or portfolio_value, default AGB.

    See full explanation in txn.get_turnover.

  • factor_returns (pd.Dataframe, optional) -- Returns by factor, with date as index and factors as columns
  • factor_loadings (pd.Dataframe, optional) -- Factor loadings for all days in the date range, with date and ticker as index, and factors as columns.
  • pos_in_dollars (boolean, optional) -- indicates whether positions is in dollars
  • header_rows (dict or OrderedDict, optional) -- Extra rows to display at the top of the perf stats table.
  • set_context (boolean, optional) --

    If True, set default plotting style context.

    See plotting.context().

  • factor_partitions (dict, optional) --

    dict specifying how factors should be separated in perf attrib factor returns and risk exposures plots

    See create_perf_attrib_tear_sheet().

pyfolio.create_interesting_times_tear_sheet(*args, **kwargs)

Generate a number of returns plots around interesting points in time, like the flash crash and 9/11.

Plots: returns around the dotcom bubble burst, Lehmann Brothers' failure, 9/11, US downgrade and EU debt crisis, Fukushima meltdown, US housing bubble burst, EZB IR, Great Recession (August 2007, March and September of 2008, Q1 & Q2 2009), flash crash, April and October 2014.

Parameters:
  • returns (pd.Series) --

    Daily returns of the strategy, noncumulative.

    See full explanation in create_full_tear_sheet.

  • benchmark_rets (pd.Series, optional) -- Daily noncumulative returns of the benchmark. This is in the same style as returns.
  • legend_loc (plt.legend_loc, optional) -- The legend's location.
  • return_fig (boolean, optional) -- If True, returns the figure that was plotted on.
  • set_context (boolean, optional) -- If True, set default plotting style context.
pyfolio.create_perf_attrib_tear_sheet(*args, **kwargs)

Generate plots and tables for analyzing a strategy's performance.

Parameters:
  • returns (pd.Series) -- Returns for each day in the date range.
  • positions (pd.DataFrame) -- Daily holdings (in dollars or percentages), indexed by date. Will be converted to percentages if positions are in dollars. Short positions show up as cash in the 'cash' column.
  • factor_returns (pd.DataFrame) -- Returns by factor, with date as index and factors as columns
  • factor_loadings (pd.DataFrame) -- Factor loadings for all days in the date range, with date and ticker as index, and factors as columns.
  • transactions (pd.DataFrame, optional) --

    Prices and amounts of executed trades. One row per trade.

    Default is None.

    See full explanation in create_full_tear_sheet.

  • pos_in_dollars (boolean, optional) -- Flag indicating whether positions are in dollars or percentages If True, positions are in dollars.
  • return_fig (boolean, optional) -- If True, returns the figure that was plotted on.
  • factor_partitions (dict) --

    dict specifying how factors should be separated in factor returns and risk exposures plots

    Example: { 'style': ['momentum', 'size', 'value', ...], 'sector': ['technology', 'materials', ... ]}

pyfolio.create_position_tear_sheet(*args, **kwargs)

Generate a number of plots for analyzing a strategy's positions and holdings.

Plots gross leverage, exposures, top positions, and holdings. Also prints the top positions held.

Parameters:
  • returns (pd.Series) --

    Daily returns of the strategy, noncumulative.

    See full explanation in create_full_tear_sheet.

  • positions (pd.DataFrame) --

    Daily net position values.

    See full explanation in create_full_tear_sheet.

  • show_and_plot_top_pos (int, optional) --

    By default, this is 2, and both prints and plots the top 10 positions.

    If this is 0, it will only plot; if 1, it will only print.

  • hide_positions (bool, optional) -- If True, will not output any symbol names. Overrides show_and_plot_top_pos to 0 to suppress text output.
  • return_fig (boolean, optional) -- If True, returns the figure that was plotted on.
  • sector_mappings (dict or pd.Series, optional) -- Security identifier to sector mapping. Security ids as keys, sectors as values.
  • transactions (pd.DataFrame, optional) --

    Prices and amounts of executed trades. One row per trade.

    See full explanation in create_full_tear_sheet.

  • estimate_intraday (boolean or str, optional) --

    Approximate returns for intraday strategies.

    See description in create_full_tear_sheet.

pyfolio.create_returns_tear_sheet(*args, **kwargs)

Generate a number of plots for analyzing a strategy's returns.

Fetches benchmarks, then creates the plots on a single figure.

Plots: rolling returns (with cone), rolling beta, rolling sharpe, rolling Fama-French risk factors, drawdowns, underwater plot, monthly and annual return plots, daily similarity plots, and return quantile box plot.

Will also print the start and end dates of the strategy, performance statistics, drawdown periods, and the return range.

Parameters:
  • returns (pd.Series) --

    Daily returns of the strategy, noncumulative.

    See full explanation in create_full_tear_sheet.

  • positions (pd.DataFrame, optional) --

    Daily net position values.

    See full explanation in create_full_tear_sheet.

  • transactions (pd.DataFrame, optional) --

    Executed trade volumes and fill prices.

    See full explanation in create_full_tear_sheet.

  • live_start_date (datetime, optional) -- The point in time when the strategy began live trading, after its backtest period.
  • 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) --

    Daily noncumulative returns of the benchmark.

    This is in the same style as returns.

  • bootstrap (boolean, optional) -- Whether to perform bootstrap analysis for the performance metrics. Takes a few minutes longer.
  • turnover_denom (str, optional) --

    Either AGB or portfolio_value, default AGB.

    See full explanation in txn.get_turnover.

  • header_rows (dict or OrderedDict, optional) -- Extra rows to display at the top of the perf stats table.
  • return_fig (boolean, optional) -- If True, returns the figure that was plotted on.
  • set_context (boolean, optional) -- If True, set default plotting style context.
pyfolio.create_risk_tear_sheet(*args, **kwargs)

Creates risk tear sheet: computes and plots style factor exposures, sector exposures, market cap exposures and volume exposures.

Parameters:
  • positions (pd.DataFrame) --

    Daily equity positions of algorithm, in dollars.

    DataFrame with dates as index, equities as columns. The last column is cash held.

    Example:

    --------------------------------------------------------------------
                | Equity(24 [AAPL]) |  Equity(62 [ABT]) |         cash |
    --------------------------------------------------------------------
    2014-01-01  |        -108062.40 |          4401.540 | 2.247757e+07 |
    --------------------------------------------------------------------
    2014-01-02  |        -108852.00 |          4373.820 | 2.540999e+07 |
    --------------------------------------------------------------------
    2014-01-03  |        -119968.66 |          4336.200 | 2.839812e+07 |
    --------------------------------------------------------------------
    
  • style_factor_panel (pd.Panel) --

    Panel where each item is a DataFrame that tabulates style factor per equity per day. Each item has dates as index, equities as columns.

    Example:

    -----------------------------------------------------
                | Equity(24 [AAPL]) |  Equity(62 [ABT]) |
    -----------------------------------------------------
    2017-04-03  |         -0.51284  |           1.39173 |
    -----------------------------------------------------
    2017-04-04  |          -0.73381 |           0.98149 |
    -----------------------------------------------------
    2017-04-05  |         -0.90132  |          1.13981  |
    -----------------------------------------------------
    
  • sectors (pd.DataFrame) --

    Sector labels (e.g. sector codes) per asset.

    DataFrame with dates as index and equities as columns.

    Example:

    -----------------------------------------------------
                | Equity(24 [AAPL]) |  Equity(62 [ABT]) |
    -----------------------------------------------------
    2017-04-03  |             311.0 |             206.0 |
    -----------------------------------------------------
    2017-04-04  |             311.0 |             206.0 |
    -----------------------------------------------------
    2017-04-05  |             311.0 |             206.0 |
    -----------------------------------------------------
    
  • caps (pd.DataFrame) --

    Daily market cap per asset.

    DataFrame with dates as index and equities as columns.

    Example:

    -----------------------------------------------------
                | Equity(24 [AAPL]) |  Equity(62 [ABT]) |
    -----------------------------------------------------
    2017-04-03  |      1.327160e+10 |      6.402460e+10 |
    -----------------------------------------------------
    2017-04-04  |      1.329620e+10 |      6.403694e+10 |
    -----------------------------------------------------
    2017-04-05  |      1.297464e+10 |      6.397187e+10 |
    -----------------------------------------------------
    
  • shares_held (pd.DataFrame) --

    Daily number of shares held by an algorithm.

    Example:

    -----------------------------------------------------
                | Equity(24 [AAPL]) |  Equity(62 [ABT]) |
    -----------------------------------------------------
    2017-04-03  |              1915 |             -2595 |
    -----------------------------------------------------
    2017-04-04  |              1968 |             -3272 |
    -----------------------------------------------------
    2017-04-05  |              2104 |             -3917 |
    -----------------------------------------------------
    
  • volumes (pd.DataFrame) --

    Daily volume per asset.

    DataFrame with dates as index and equities as columns.

    Example:

    -----------------------------------------------------
                | Equity(24 [AAPL]) |  Equity(62 [ABT]) |
    -----------------------------------------------------
    2017-04-03  |       34940859.00 |        4665573.80 |
    -----------------------------------------------------
    2017-04-04  |       35603329.10 |        4818463.90 |
    -----------------------------------------------------
    2017-04-05  |       41846731.75 |        4129153.10 |
    -----------------------------------------------------
    
  • percentile (float) --

    Percentile to use when computing and plotting volume exposures.

    Defaults to 10th percentile.

pyfolio.create_round_trip_tear_sheet(*args, **kwargs)

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:
  • returns (pd.Series) --

    Daily returns of the strategy, noncumulative.

    See full explanation in create_full_tear_sheet.

  • 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.
  • estimate_intraday (boolean or str, optional) -- Approximate returns for intraday strategies. See description in create_full_tear_sheet.
  • return_fig (boolean, optional) -- If True, returns the figure that was plotted on.
pyfolio.create_simple_tear_sheet(*args, **kwargs)

Simpler version of create_full_tear_sheet; generates summary performance statistics and important plots as a single image.

Plots: cumulative returns, rolling beta, rolling Sharpe, underwater, exposure, top 10 holdings, total holdings, long/short holdings, daily turnover, and transaction time distribution.

Does not accept market_data and sector_mappings input. Does not perform bootstrap analysis, does not attempt to infer intraday strategy, and doesn't hide positions on top 10 holdings plot. Always uses default cone_std ((1.0, 1.5, 2.0)).

Parameters:
  • returns (pd.Series) --

    Daily returns of the strategy, noncumulative. This is a time series with decimal returns.

    Example:

    --------------------------
    2015-07-16  |  -0.012143 |
    --------------------------
    2015-07-17  |   0.045350 |
    --------------------------
    2015-07-20  |   0.030957 |
    --------------------------
    2015-07-21  |   0.004902 |
    --------------------------
    
  • positions (pd.DataFrame, optional) --

    Daily net position values. This is a time series of dollar amount invested in each position and cash.

    Days where stocks are not held can be represented by 0 or NaN.

    Non-working capital is labelled 'cash'.

    Example:

    ----------------------------------------------------
          index |      'AAPL' |     'MSFT'  |     cash |
    ----------------------------------------------------
     2014-01-09 | 13939.3800  | -14012.9930 | 711.5585 |
    ----------------------------------------------------
     2014-01-12 | 14492.6300  | -14624.8700 | 27.1821  |
    ----------------------------------------------------
     2014-01-13 | -13853.2800 |  13653.6400 | -43.6375 |
    ----------------------------------------------------
    
  • transactions (pd.DataFrame, optional) --

    Executed trade volumes and fill prices.

    One row per trade. Trades on different names that occur at the same time will have identical indices.

    Example:

    ---------------------------------------------------
                   index | amount |   price |  symbol |
    ---------------------------------------------------
     2004-01-09 12:18:01 |    483 |  324.12 |  'AAPL' |
    ---------------------------------------------------
     2004-01-09 12:18:01 |    122 |   83.10 |  'MSFT' |
    ---------------------------------------------------
     2004-01-13 14:12:23 |    -75 |  340.43 |  'AAPL' |
    ---------------------------------------------------
    
  • benchmark_rets (pd.Series, optional) -- Daily returns of the benchmark, noncumulative. Defaults to SPY.
  • slippage (int/float, optional) --

    Basis points of slippage to apply to returns before generating tearsheet stats and plots.

    If a value is provided, slippage parameter sweep plots will be generated from the unadjusted returns.

    Transactions and positions must also be passed.

    See txn.adjust_returns_for_slippage for more details.

  • live_start_date (datetime, optional) -- The point in time when the strategy began live trading, after its backtest period. This datetime should be normalized.
  • turnover_denom (str, optional) --

    Either AGB or portfolio_value, default AGB.

    See full explanation in txn.get_turnover.

  • header_rows (dict or OrderedDict, optional) -- Extra rows to display at the top of the perf stats table.
  • set_context (boolean, optional) -- If True, set default plotting style context.
pyfolio.create_txn_tear_sheet(*args, **kwargs)

Generate a number of plots for analyzing a strategy's transactions.

Plots: turnover, daily volume, and a histogram of daily volume.

Parameters:
  • returns (pd.Series) --

    Daily returns of the strategy, noncumulative.

    See full explanation in create_full_tear_sheet.

  • 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.

  • unadjusted_returns (pd.Series, optional) --

    Daily unadjusted returns of the strategy, noncumulative. Will plot additional swippage sweep analysis.

    See pyfolio.plotting.plot_swippage_sleep and pyfolio.plotting.plot_slippage_sensitivity

  • estimate_intraday (boolean or str, optional) --

    Approximate returns for intraday strategies.

    See description in create_full_tear_sheet.

  • return_fig (boolean, optional) -- If True, returns the figure that was plotted on.