Analyzers Reference

AnnualReturn

class backtrader.analyzers.AnnualReturn

This analyzer calculates the AnnualReturns by looking at the beginning and end of the year

Params:

  • (None)

Member Attributes:

  • rets: list of calculated annual returns
  • ret: dictionary (key: year) of annual returns

get_analysis:

  • Returns a dictionary of annual returns (key: year)

Calmar

class backtrader.analyzers.Calmar

This analyzer calculates the CalmarRatio timeframe which can be different from the one used in the underlying data Params:

  • timeframe (default: None) If None the timeframe of the 1st data in the system will be used

    Pass TimeFrame.NoTimeFrame to consider the entire dataset with no time constraints

  • compression (default: None)

    Only used for sub-day timeframes to for example work on an hourly timeframe by specifying “TimeFrame.Minutes” and 60 as compression

    If None then the compression of the 1st data of the system will be used

  • None

  • fund (default: None)

    If None the actual mode of the broker (fundmode - True/False) will be autodetected to decide if the returns are based on the total net asset value or on the fund value. See set_fundmode in the broker documentation

    Set it to True or False for a specific behavior

- ``get_analysis``

Returns a OrderedDict with a key for the time period and the corresponding rolling Calmar ratio

- ``calmar`` the latest calculated calmar ratio

DrawDown

class backtrader.analyzers.DrawDown

This analyzer calculates trading system drawdowns stats such as drawdown values in %s and in dollars, max drawdown in %s and in dollars, drawdown length and drawdown max length

Params:

  • fund (default: None)

    If None the actual mode of the broker (fundmode - True/False) will be autodetected to decide if the returns are based on the total net asset value or on the fund value. See set_fundmode in the broker documentation

    Set it to True or False for a specific behavior

- ``get_analysis``

Returns a dictionary (with . notation support and subdctionaries) with drawdown stats as values, the following keys/attributes are available:

  • drawdown - drawdown value in 0.xx %
  • moneydown - drawdown value in monetary units
  • len - drawdown length
  • max.drawdown - max drawdown value in 0.xx %
  • max.moneydown - max drawdown value in monetary units
  • max.len - max drawdown length

TimeDrawDown

class backtrader.analyzers.TimeDrawDown

This analyzer calculates trading system drawdowns on the chosen timeframe which can be different from the one used in the underlying data Params:

  • timeframe (default: None) If None the timeframe of the 1st data in the system will be used

    Pass TimeFrame.NoTimeFrame to consider the entire dataset with no time constraints

  • compression (default: None)

    Only used for sub-day timeframes to for example work on an hourly timeframe by specifying “TimeFrame.Minutes” and 60 as compression

    If None then the compression of the 1st data of the system will be used

  • None

  • fund (default: None)

    If None the actual mode of the broker (fundmode - True/False) will be autodetected to decide if the returns are based on the total net asset value or on the fund value. See set_fundmode in the broker documentation

    Set it to True or False for a specific behavior

- ``get_analysis``

Returns a dictionary (with . notation support and subdctionaries) with drawdown stats as values, the following keys/attributes are available:

  • drawdown - drawdown value in 0.xx %
  • maxdrawdown - drawdown value in monetary units
  • maxdrawdownperiod - drawdown length
- Those are available during runs as attributes
  • dd
  • maxdd
  • maxddlen

GrossLeverage

class backtrader.analyzers.GrossLeverage

This analyzer calculates the Gross Leverage of the current strategy on a timeframe basis

Params:

  • fund (default: None)

    If None the actual mode of the broker (fundmode - True/False) will be autodetected to decide if the returns are based on the total net asset value or on the fund value. See set_fundmode in the broker documentation

    Set it to True or False for a specific behavior

- get_analysis

Returns a dictionary with returns as values and the datetime points for each return as keys

PositionsValue

class backtrader.analyzers.PositionsValue

This analyzer reports the value of the positions of the current set of datas

Params:

  • timeframe (default: None) If None then the timeframe of the 1st data of the system will be used

  • compression (default: None)

    Only used for sub-day timeframes to for example work on an hourly timeframe by specifying “TimeFrame.Minutes” and 60 as compression

    If None then the compression of the 1st data of the system will be used

  • headers (default: False)

    Add an initial key to the dictionary holding the results with the names of the datas (‘Datetime’ as key

  • cash (default: False)

    Include the actual cash as an extra position (for the header ‘cash’ will be used as name)

- get_analysis

Returns a dictionary with returns as values and the datetime points for each return as keys

PyFolio

class backtrader.analyzers.PyFolio

This analyzer uses 4 children analyzers to collect data and transforms it in to a data set compatible with pyfolio

Children Analyzer

  • TimeReturn

    Used to calculate the returns of the global portfolio value

  • PositionsValue

    Used to calculate the value of the positions per data. It sets the headers and cash parameters to True

  • Transactions

    Used to record each transaction on a data (size, price, value). Sets the headers parameter to True

  • GrossLeverage

    Keeps track of the gross leverage (how much the strategy is invested)

Params:

These are passed transparently to the children

  • timeframe (default: bt.TimeFrame.Days)

    If None then the timeframe of the 1st data of the system will be used

  • compression (default: 1`)

    If None then the compression of the 1st data of the system will be used

Both timeframe and compression are set following the default behavior of pyfolio which is working with daily data and upsample it to obtaine values like yearly returns.

- get_analysis

Returns a dictionary with returns as values and the datetime points for each return as keys

get_pf_items()
Returns a tuple of 4 elements which can be used for further processing with

pyfolio

returns, positions, transactions, gross_leverage

Because the objects are meant to be used as direct input to pyfolio this method makes a local import of pandas to convert the internal backtrader results to pandas DataFrames which is the expected input by, for example, pyfolio.create_full_tear_sheet

The method will break if pandas is not installed

LogReturnsRolling

class backtrader.analyzers.LogReturnsRolling

This analyzer calculates rolling returns for a given timeframe and compression

Params:

  • timeframe (default: None) If None the timeframe of the 1st data in the system will be used

    Pass TimeFrame.NoTimeFrame to consider the entire dataset with no time constraints

  • compression (default: None)

    Only used for sub-day timeframes to for example work on an hourly timeframe by specifying “TimeFrame.Minutes” and 60 as compression

    If None then the compression of the 1st data of the system will be used

  • data (default: None)

    Reference asset to track instead of the portfolio value.

    Note

    this data must have been added to a cerebro instance with addata, resampledata or replaydata

  • firstopen (default: True)

    When tracking the returns of a data the following is done when crossing a timeframe boundary, for example Years:

    • Last close of previous year is used as the reference price to see the return in the current year

    The problem is the 1st calculation, because the data has** no previous** closing price. As such and when this parameter is True the opening price will be used for the 1st calculation.

    This requires the data feed to have an open price (for close the standard [0] notation will be used without reference to a field price)

    Else the initial close will be used.

  • fund (default: None)

    If None the actual mode of the broker (fundmode - True/False) will be autodetected to decide if the returns are based on the total net asset value or on the fund value. See set_fundmode in the broker documentation

    Set it to True or False for a specific behavior

- get_analysis

Returns a dictionary with returns as values and the datetime points for each return as keys

PeriodStats

class backtrader.analyzers.PeriodStats

Calculates basic statistics for given timeframe

Params:

  • timeframe (default: Years) If None the timeframe of the 1st data in the system will be used

    Pass TimeFrame.NoTimeFrame to consider the entire dataset with no time constraints

  • compression (default: 1)

    Only used for sub-day timeframes to for example work on an hourly timeframe by specifying “TimeFrame.Minutes” and 60 as compression

    If None then the compression of the 1st data of the system will be used

  • fund (default: None)

    If None the actual mode of the broker (fundmode - True/False) will be autodetected to decide if the returns are based on the total net asset value or on the fund value. See set_fundmode in the broker documentation

    Set it to True or False for a specific behavior

get_analysis returns a dictionary containing the keys:

  • average
  • stddev
  • positive
  • negative
  • nochange
  • best
  • worst

If the parameter zeroispos is set to True, periods with no change will be counted as positive

Returns

class backtrader.analyzers.Returns

Total, Average, Compound and Annualized Returns calculated using a logarithmic approach

See:

Params:

  • timeframe (default: None)

    If None the timeframe of the 1st data in the system will be used

    Pass TimeFrame.NoTimeFrame to consider the entire dataset with no time constraints

  • compression (default: None)

    Only used for sub-day timeframes to for example work on an hourly timeframe by specifying “TimeFrame.Minutes” and 60 as compression

    If None then the compression of the 1st data of the system will be used

  • tann (default: None)

    Number of periods to use for the annualization (normalization) of the

    namely:

    • days: 252
    • weeks: 52
    • months: 12
    • years: 1
  • fund (default: None)

    If None the actual mode of the broker (fundmode - True/False) will be autodetected to decide if the returns are based on the total net asset value or on the fund value. See set_fundmode in the broker documentation

    Set it to True or False for a specific behavior

- get_analysis

Returns a dictionary with returns as values and the datetime points for each return as keys

The returned dict the following keys:

  • rtot: Total compound return
  • ravg: Average return for the entire period (timeframe specific)
  • rnorm: Annualized/Normalized return
  • rnorm100: Annualized/Normalized return expressed in 100%

SharpeRatio

class backtrader.analyzers.SharpeRatio

This analyzer calculates the SharpeRatio of a strategy using a risk free asset which is simply an interest rate

Params:

  • timeframe: (default: TimeFrame.Years)

  • compression (default: 1)

    Only used for sub-day timeframes to for example work on an hourly timeframe by specifying “TimeFrame.Minutes” and 60 as compression

  • riskfreerate (default: 0.01 -> 1%)

    Expressed in annual terms (see convertrate below)

  • convertrate (default: True)

    Convert the riskfreerate from annual to monthly, weekly or daily rate. Sub-day conversions are not supported

  • factor (default: None)

    If None, the conversion factor for the riskfree rate from annual to the chosen timeframe will be chosen from a predefined table

    Days: 252, Weeks: 52, Months: 12, Years: 1

    Else the specified value will be used

  • annualize (default: False)

    If convertrate is True, the SharpeRatio will be delivered in the timeframe of choice.

    In most occasions the SharpeRatio is delivered in annualized form. Convert the riskfreerate from annual to monthly, weekly or daily rate. Sub-day conversions are not supported

  • stddev_sample (default: False)

    If this is set to True the standard deviation will be calculated decreasing the denominator in the mean by 1. This is used when calculating the standard deviation if it’s considered that not all samples are used for the calculation. This is known as the Bessels’ correction

  • daysfactor (default: None)

    Old naming for factor. If set to anything else than None and the timeframe is TimeFrame.Days it will be assumed this is old code and the value will be used

  • legacyannual (default: False)

    Use the AnnualReturn return analyzer, which as the name implies only works on years

  • fund (default: None)

    If None the actual mode of the broker (fundmode - True/False) will be autodetected to decide if the returns are based on the total net asset value or on the fund value. See set_fundmode in the broker documentation

    Set it to True or False for a specific behavior

- get_analysis

Returns a dictionary with key “sharperatio” holding the ratio

SharpeRatio_A

class backtrader.analyzers.SharpeRatio_A

Extension of the SharpeRatio which returns the Sharpe Ratio directly in annualized form

The following param has been changed from SharpeRatio

  • annualize (default: True)

SQN

class backtrader.analyzers.SQN

SQN or SystemQualityNumber. Defined by Van K. Tharp to categorize trading systems.

  • 1.6 - 1.9 Below average
  • 2.0 - 2.4 Average
  • 2.5 - 2.9 Good
  • 3.0 - 5.0 Excellent
  • 5.1 - 6.9 Superb
  • 7.0 - Holy Grail?

The formula:

  • SquareRoot(NumberTrades) * Average(TradesProfit) / StdDev(TradesProfit)

The sqn value should be deemed reliable when the number of trades >= 30

- get_analysis

Returns a dictionary with keys “sqn” and “trades” (number of considered trades)

TimeReturn

class backtrader.analyzers.TimeReturn

This analyzer calculates the Returns by looking at the beginning and end of the timeframe

Params:

  • timeframe (default: None) If None the timeframe of the 1st data in the system will be used

    Pass TimeFrame.NoTimeFrame to consider the entire dataset with no time constraints

  • compression (default: None)

    Only used for sub-day timeframes to for example work on an hourly timeframe by specifying “TimeFrame.Minutes” and 60 as compression

    If None then the compression of the 1st data of the system will be used

  • data (default: None)

    Reference asset to track instead of the portfolio value.

    Note

    this data must have been added to a cerebro instance with addata, resampledata or replaydata

  • firstopen (default: True)

    When tracking the returns of a data the following is done when crossing a timeframe boundary, for example Years:

    • Last close of previous year is used as the reference price to see the return in the current year

    The problem is the 1st calculation, because the data has** no previous** closing price. As such and when this parameter is True the opening price will be used for the 1st calculation.

    This requires the data feed to have an open price (for close the standard [0] notation will be used without reference to a field price)

    Else the initial close will be used.

  • fund (default: None)

    If None the actual mode of the broker (fundmode - True/False) will be autodetected to decide if the returns are based on the total net asset value or on the fund value. See set_fundmode in the broker documentation

    Set it to True or False for a specific behavior

- get_analysis

Returns a dictionary with returns as values and the datetime points for each return as keys

TradeAnalyzer

class backtrader.analyzers.TradeAnalyzer

Provides statistics on closed trades (keeps also the count of open ones)

  • Total Open/Closed Trades

  • Streak Won/Lost Current/Longest

  • ProfitAndLoss Total/Average

  • Won/Lost Count/ Total PNL/ Average PNL / Max PNL

  • Long/Short Count/ Total PNL / Average PNL / Max PNL

    • Won/Lost Count/ Total PNL/ Average PNL / Max PNL
  • Length (bars in the market)

    • Total/Average/Max/Min
    • Won/Lost Total/Average/Max/Min
    • Long/Short Total/Average/Max/Min
      • Won/Lost Total/Average/Max/Min

Note

The analyzer uses an “auto”dict for the fields, which means that if no trades are executed, no statistics will be generated.

In that case there will be a single field/subfield in the dictionary returned by get_analysis, namely:

  • dictname[‘total’][‘total’] which will have a value of 0 (the field is also reachable with dot notation dictname.total.total

Transactions

class backtrader.analyzers.Transactions

This analyzer reports the transactions occurred with each an every data in the system

It looks at the order execution bits to create a Position starting from 0 during each next cycle.

The result is used during next to record the transactions

Params:

  • headers (default: True)

    Add an initial key to the dictionary holding the results with the names of the datas

    This analyzer was modeled to facilitate the integration with pyfolio and the header names are taken from the samples used for it:

    'date', 'amount', 'price', 'sid', 'symbol', 'value'
    
- get_analysis

Returns a dictionary with returns as values and the datetime points for each return as keys

VWR

class backtrader.analyzers.VWR

Variability-Weighted Return: Better SharpeRatio with Log Returns

Alias:

  • VariabilityWeightedReturn

See:

Params:

  • timeframe (default: None) If None then the complete return over the entire backtested period will be reported

    Pass TimeFrame.NoTimeFrame to consider the entire dataset with no time constraints

  • compression (default: None)

    Only used for sub-day timeframes to for example work on an hourly timeframe by specifying “TimeFrame.Minutes” and 60 as compression

    If None then the compression of the 1st data of the system will be used

  • tann (default: None)

    Number of periods to use for the annualization (normalization) of the average returns. If None, then standard t values will be used, namely:

    • days: 252
    • weeks: 52
    • months: 12
    • years: 1
  • tau (default: 2.0)

    factor for the calculation (see the literature)

  • sdev_max (default: 0.20)

    max standard deviation (see the literature)

  • fund (default: None)

    If None the actual mode of the broker (fundmode - True/False) will be autodetected to decide if the returns are based on the total net asset value or on the fund value. See set_fundmode in the broker documentation

    Set it to True or False for a specific behavior

- get_analysis

Returns a dictionary with returns as values and the datetime points for each return as keys

The returned dict contains the following keys:

  • vwr: Variability-Weighted Return