back-trader-python 1.4.0__py3-none-any.whl

backtrader/analyzers/annualreturn.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python
+"""Annual Return Analyzer Module - Annual return calculation.
+
+This module provides the AnnualReturn analyzer for calculating
+year-by-year returns of a strategy.
+
+Classes:
+    AnnualReturn: Analyzer that calculates annual returns.
+
+Example:
+    >>> cerebro = bt.Cerebro()
+    >>> cerebro.addanalyzer(bt.analyzers.AnnualReturn, _name='annret')
+    >>> results = cerebro.run()
+    >>> print(results[0].analyzers.annret.get_analysis())
+"""
+
+import math
+from collections import OrderedDict
+
+from ..analyzer import Analyzer
+from ..utils.date import num2date
+from ..utils.log_message import get_logger
+from ..utils.py3 import range
+
+logger = get_logger(__name__)
+
+
+# Calculate annual returns. The algorithm implementation is somewhat complex, so a pandas-based version MyAnnualReturn was written later with much simpler logic
+class AnnualReturn(Analyzer):
+    """
+    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)
+    """
+
+    def __init__(self):
+        """Initialize the AnnualReturn analyzer.
+
+        Initializes cache lists for storing dates and values during backtesting.
+        """
+        super().__init__()
+        # Cache data
+        self._dt_cache = []
+        self._value_cache = []
+
+    def next(self):
+        """Cache current date and account value on each bar.
+
+        Stores the current datetime and portfolio value for later
+        annual return calculation.
+        """
+        # Cache current date and account value each time next is called
+        dt_val = self.data.datetime[0]
+        value_val = self.strategy.broker.getvalue()
+        self._dt_cache.append(dt_val)
+        self._value_cache.append(value_val)
+
+    def stop(self):
+        """Calculate annual returns from cached data.
+
+        Iterates through cached date-value pairs to calculate returns
+        for each calendar year. Stores results in self.rets (list) and
+        self.ret (dictionary keyed by year).
+        """
+        # Must have stats.broker
+        # Current year
+        cur_year = -1
+        # Start value
+        value_start = 0.0
+        # End value
+        value_end = 0.0
+        # Save return data
+        setattr(self, "rets", [])
+        setattr(self, "ret", OrderedDict())
+
+        # Calculate using cached data
+        for i in range(len(self._dt_cache)):
+            dt_val = self._dt_cache[i]
+            value_cur = self._value_cache[i]
+
+            # Convert date
+            try:
+                dt = num2date(dt_val)
+            except (ValueError, TypeError, OverflowError) as e:
+                logger.warning("Failed to convert date value %s: %s", dt_val, e)
+                continue
+
+            # If the year at index i is greater than current year, if current year > 0, calculate return and save to self.ret, and start value equals end value
+            # When years are not equal, it indicates current i is a new year
+            if dt.year > cur_year:
+                if cur_year >= 0:
+                    annual_ret = self._safe_annual_return(value_start, value_end)
+                    self.rets.append(annual_ret)
+                    self.ret[cur_year] = annual_ret
+
+                    # changing between real years, use last value as new start
+                    value_start = value_end
+                else:
+                    # No value set whatsoever, use the currently loaded value
+                    value_start = value_cur
+
+                cur_year = dt.year
+
+            # No matter what, the last value is always the last loaded value
+            value_end = value_cur
+        # If current year hasn't ended and return hasn't been calculated, calculate at the end even if less than a full year
+        if cur_year >= 0 and cur_year not in self.ret:
+            # finish calculating pending data
+            annual_ret = self._safe_annual_return(value_start, value_end)
+            self.rets.append(annual_ret)
+            self.ret[cur_year] = annual_ret
+
+    @staticmethod
+    def _safe_annual_return(value_start, value_end):
+        """Compute (value_end/value_start - 1), returning 0.0 for any invalid
+        (zero/NaN/inf/complex) inputs or result. Shared by the year-boundary
+        and final-pending paths in stop()."""
+        try:
+            valid_values = (
+                value_start != 0 and math.isfinite(value_start) and math.isfinite(value_end)
+            )
+        except TypeError:
+            valid_values = False
+        if not valid_values:
+            return 0.0
+        try:
+            annual_ret = (value_end / value_start) - 1.0
+            if isinstance(annual_ret, complex) or not math.isfinite(annual_ret):
+                return 0.0
+            return annual_ret
+        except (ZeroDivisionError, TypeError, ValueError):
+            return 0.0
+
+    def get_analysis(self):
+        """Return the annual return analysis results.
+
+        Returns:
+            OrderedDict: Dictionary mapping years to their annual returns.
+        """
+        return self.ret
+
+
+class MyAnnualReturn(Analyzer):
+    """
+    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)
+    """
+
+    def stop(self):
+        """Calculate annual returns using pandas.
+
+        Uses pandas DataFrame operations to group data by year and
+        calculate annual returns based on beginning and ending values
+        for each year.
+
+        Note:
+            This method requires pandas to be installed.
+        """
+        # Container for saving data - dictionary
+        if not hasattr(self, "ret"):
+            setattr(self, "ret", OrderedDict())
+        # Get data time and convert to date
+        dt_list = self.data.datetime.get(0, size=len(self.data))
+        dt_list = [num2date(i) for i in dt_list]
+        # Get account assets
+        value_list = self.strategy.stats.broker.value.get(0, size=len(self.data))
+        # Convert to pandas format
+        import pandas as pd
+
+        df = pd.DataFrame([dt_list, value_list]).T
+        df.columns = ["datetime", "value"]
+        df["pre_value"] = df["value"].shift(1)
+        # Calculate simple returns for each year
+        df["year"] = [i.year for i in df["datetime"]]
+        for year, data in df.groupby("year"):
+            begin_value = list(data["pre_value"])[0]
+            end_value = list(data["value"])[-1]
+            try:
+                valid_values = math.isfinite(begin_value) and math.isfinite(end_value)
+            except TypeError:
+                valid_values = False
+            if not valid_values or begin_value == 0:
+                annual_return = 0.0
+            else:
+                try:
+                    annual_return = (end_value / begin_value) - 1
+                    if isinstance(annual_return, complex) or not math.isfinite(annual_return):
+                        annual_return = 0.0
+                except (ZeroDivisionError, TypeError, ValueError):
+                    annual_return = 0.0
+            self.ret[year] = annual_return
+
+    def get_analysis(self):
+        """Return the annual return analysis results.
+
+        Returns:
+            OrderedDict: Dictionary mapping years to their annual returns.
+        """
+        return self.ret

backtrader/analyzers/calmar.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python
+"""Calmar Ratio Analyzer Module - Calmar ratio calculation.
+
+This module provides the Calmar analyzer for calculating the Calmar
+ratio (annual return divided by maximum drawdown).
+
+Classes:
+    Calmar: Analyzer that calculates Calmar ratio.
+
+Example:
+    >>> cerebro = bt.Cerebro()
+    >>> cerebro.addanalyzer(bt.analyzers.Calmar, _name='calmar')
+    >>> results = cerebro.run()
+    >>> print(results[0].analyzers.calmar.get_analysis())
+"""
+
+import collections
+import math
+
+from ..analyzer import TimeFrameAnalyzerBase
+from ..dataseries import TimeFrame
+from ..metabase import OwnerContext
+from .drawdown import TimeDrawDown
+
+__all__ = ["Calmar"]
+
+
+# Calculate Calmar ratio. Overall, this Calmar calculation is not very successful, or the analyzer/observer series indicators are not very efficient in usage
+# Consider creating an analysis module similar to pyfolio
+class Calmar(TimeFrameAnalyzerBase):
+    """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 first 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 compression is None, then the compression of the first data in 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
+
+    See also:
+
+      - https://en.wikipedia.org/wiki/Calmar_ratio
+
+    Methods:
+      - ``get_analysis``
+
+        Returns a OrderedDict with a key for the time period and the
+        corresponding rolling Calmar ratio
+
+    Attributes:
+      - ``calmar`` the latest calculated calmar ratio
+    """
+
+    # Modules used
+    packages = (
+        "collections",
+        "math",
+    )
+    # Parameters
+    params = (
+        ("timeframe", TimeFrame.Months),  # default in calmar
+        ("period", 36),
+        ("fund", None),
+    )
+
+    # Calculate max drawdown
+    def __init__(self, *args, **kwargs):
+        """Initialize the Calmar analyzer.
+
+        Args:
+            *args: Positional arguments.
+            **kwargs: Keyword arguments for analyzer parameters.
+        """
+        # Call parent class __init__ method to support timeframe and compression parameters
+        super().__init__(*args, **kwargs)
+
+        self.calmar = None
+        self._fundmode = None
+        self._values = None
+        self._mdd = None
+        # Use OwnerContext so child analyzer can find this as its parent
+        with OwnerContext.set_owner(self):
+            self._maxdd = TimeDrawDown(timeframe=self.p.timeframe, compression=self.p.compression)
+
+    # Start
+    def start(self):
+        """Initialize the analyzer at the start of the backtest.
+
+        Sets up the maximum drawdown tracking, value history queue,
+        and fund mode.
+        """
+        # Max drawdown rate
+        self._mdd = float("-inf")
+        # Double-ended queue, saves period values, default is 36
+        self._values = collections.deque([float("Nan")] * self.p.period, maxlen=self.p.period)
+        # fundmode
+        if self.p.fund is None:
+            self._fundmode = self.strategy.broker.fundmode
+        else:
+            self._fundmode = self.p.fund
+        # Add different values to self._values based on fundmode
+        if not self._fundmode:
+            self._values.append(self.strategy.broker.getvalue())
+        else:
+            self._values.append(self.strategy.broker.fundvalue)
+
+    def on_dt_over(self):
+        """Calculate Calmar ratio when timeframe period ends.
+
+        Updates maximum drawdown and calculates Calmar ratio as
+        annualized return divided by maximum drawdown.
+        """
+        # Max drawdown rate
+        self._mdd = max(self._mdd, self._maxdd.maxdd)
+        # Add value to self._values
+        if not self._fundmode:
+            self._values.append(self.strategy.broker.getvalue())
+        else:
+            self._values.append(self.strategy.broker.fundvalue)
+        # Calculate average monthly return by default
+        try:
+            ratio = self._values[-1] / self._values[0]
+            if isinstance(ratio, complex) or not math.isfinite(ratio) or ratio <= 0:
+                raise ValueError(f"invalid calmar ratio input: {ratio}")
+            rann = math.log(ratio) / len(self._values)
+            if not math.isfinite(rann):
+                raise ValueError(f"invalid calmar annualized return: {rann}")
+        except (ZeroDivisionError, TypeError, ValueError):
+            rann = 0.0
+        # Calculate Calmar indicator
+        try:
+            self.calmar = calmar = rann / (self._mdd or float("Inf"))
+        except (ZeroDivisionError, TypeError, ValueError):
+            self.calmar = calmar = 0.0
+        if isinstance(calmar, complex) or not math.isfinite(calmar):
+            self.calmar = calmar = 0.0
+        # Save result
+        self.rets[self.dtkey] = calmar
+
+    def stop(self):
+        """Finalize the analysis when backtest ends.
+
+        Triggers one final Calmar ratio calculation.
+        """
+        self.on_dt_over()  # update last values

backtrader/analyzers/drawdown.py

@@ -0,0 +1,287 @@
+#!/usr/bin/env python
+"""DrawDown Analyzer Module - Drawdown statistics calculation.
+
+This module provides analyzers for calculating drawdown statistics including
+current drawdown, maximum drawdown, and drawdown duration.
+
+Classes:
+    DrawDown: Analyzer that calculates drawdown statistics.
+    TimeDrawDown: Time-frame based drawdown analyzer.
+
+Example:
+    >>> cerebro = bt.Cerebro()
+    >>> cerebro.addanalyzer(bt.analyzers.DrawDown, _name='dd')
+    >>> results = cerebro.run()
+    >>> print(results[0].analyzers.dd.get_analysis())
+"""
+
+import math
+
+from ..analyzer import Analyzer, TimeFrameAnalyzerBase
+from ..mathsupport import is_finite_real
+from ..utils import AutoOrderedDict
+
+__all__ = ["DrawDown", "TimeDrawDown"]
+
+
+# Analyze drawdown situation
+class DrawDown(Analyzer):
+    """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
+
+    Methods:
+
+      - ``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
+    """
+
+    params = (("fund", None),)
+
+    # Start, get fundmode
+    def start(self):
+        """Initialize the analyzer at the start of the backtest.
+
+        Sets the fund mode based on parameters or broker settings.
+        """
+        super().start()
+        if self.p.fund is None:
+            # self._fundmode = self.strategy.broker.fundmode
+            setattr(self, "_fundmode", self.strategy.broker.fundmode)
+        else:
+            # self._fundmode = self.p.fund
+            setattr(self, "_fundmode", self.p.fund)
+
+    # Create indicator values to analyze
+    def create_analysis(self):
+        """Create the analysis result data structure.
+
+        Initializes the results dictionary with all drawdown metrics set to zero.
+        """
+        self.rets = AutoOrderedDict()  # dict with. notation
+
+        self.rets.len = 0
+        self.rets.drawdown = 0.0
+        self.rets.moneydown = 0.0
+
+        self.rets.max.len = 0.0
+        self.rets.max.drawdown = 0.0
+        self.rets.max.moneydown = 0.0
+
+        self._maxvalue = float("-inf")  # any value will outdo it
+
+    # Stop
+    def stop(self):
+        """Finalize the analysis when backtest ends.
+
+        Closes the results dictionary to prevent further modifications.
+        """
+        self.rets._close()  # . notation cannot create more keys
+
+    # Notify fund situation
+    def notify_fund(self, cash, value, fundvalue, shares):
+        """Update drawdown calculation with current fund values.
+
+        Args:
+            cash: Current cash amount.
+            value: Current portfolio value.
+            fundvalue: Current fund value.
+            shares: Number of fund shares.
+        """
+        current_value = value if not self._fundmode else fundvalue
+        self._value = current_value
+        if is_finite_real(current_value):
+            if not is_finite_real(self._maxvalue):
+                self._maxvalue = current_value
+            else:
+                self._maxvalue = max(self._maxvalue, current_value)
+        elif not is_finite_real(self._maxvalue):
+            self._maxvalue = 0.0
+
+    def next(self):
+        """Calculate drawdown for the current period.
+
+        Updates current and maximum drawdown values and lengths.
+        """
+        # PERFORMANCE OPTIMIZATION: Cache attribute access to reduce lookups
+        # Called 688K+ times, attribute caching helps
+        r = self.rets
+        maxvalue = self._maxvalue
+        value = self._value
+        r_max = r.max
+
+        # calculate current drawdown values
+        if not (is_finite_real(maxvalue) and is_finite_real(value)):
+            moneydown = 0.0
+            drawdown = 0.0
+        else:
+            moneydown = maxvalue - value
+            drawdown = 100.0 * moneydown / maxvalue if maxvalue else 0.0
+            if isinstance(moneydown, complex) or not math.isfinite(moneydown):
+                moneydown = 0.0
+            if isinstance(drawdown, complex) or not math.isfinite(drawdown):
+                drawdown = 0.0
+
+        r.moneydown = moneydown
+        r.drawdown = drawdown
+
+        # maximum drawdown values
+        if moneydown > r_max.moneydown:
+            r_max.moneydown = moneydown
+        if drawdown > r_max.drawdown:
+            r_max.drawdown = drawdown
+
+        r.len = r.len + 1 if drawdown else 0
+        if r.len > r_max.len:
+            r_max.len = r.len
+
+
+# Analyze time drawdown situation (max drawdown)
+class TimeDrawDown(TimeFrameAnalyzerBase):
+    """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
+
+    Methods:
+
+      - ``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``
+    """
+
+    params = (("fund", None),)
+
+    def __init__(self, *args, **kwargs):
+        """Initialize the TimeDrawDown analyzer.
+
+        Args:
+            *args: Positional arguments.
+            **kwargs: Keyword arguments for analyzer parameters.
+        """
+        # Call parent class __init__ method to support timeframe and compression parameters
+        super().__init__(*args, **kwargs)
+
+        self.ddlen = None
+        self.peak = None
+        self.maxddlen = None
+        self.maxdd = None
+        self.dd = None
+        self._fundmode = None
+
+    def start(self):
+        """Initialize the analyzer at the start of the backtest.
+
+        Sets the fund mode and initializes drawdown tracking variables.
+        """
+        super().start()
+        # fundmode
+        if self.p.fund is None:
+            self._fundmode = self.strategy.broker.fundmode
+        else:
+            self._fundmode = self.p.fund
+        # Initialize parameters
+        self.dd = 0.0
+        self.maxdd = 0.0
+        self.maxddlen = 0
+        self.peak = float("-inf")
+        self.ddlen = 0
+
+    # Calculate max drawdown and max drawdown length
+    def on_dt_over(self):
+        """Called when a datetime period is over.
+
+        Updates drawdown calculations for the timeframe period.
+        """
+        if not self._fundmode:
+            value = self.strategy.broker.getvalue()
+        else:
+            value = self.strategy.broker.fundvalue
+        value_valid = is_finite_real(value)
+        if not is_finite_real(self.peak):
+            self.peak = 0.0
+
+        # update the maximum seen peak
+        if value_valid and value > self.peak:
+            self.peak = value
+            self.ddlen = 0  # start of streak
+
+        # calculate the current drawdown
+        try:
+            if value_valid and self.peak:
+                self.dd = dd = 100.0 * (self.peak - value) / self.peak
+                if isinstance(dd, complex) or not math.isfinite(dd):
+                    self.dd = dd = 0.0
+            else:
+                self.dd = dd = 0.0
+        except (TypeError, ValueError, ZeroDivisionError):
+            self.dd = dd = 0.0
+        self.ddlen += bool(dd)  # if peak == value -> dd = 0
+
+        # update the maxdrawdown if needed
+        self.maxdd = max(self.maxdd if is_finite_real(self.maxdd) else 0.0, dd)
+        self.maxddlen = max(self.maxddlen, self.ddlen)
+
+    # When stopping, add max drawdown and max drawdown length to dictionary
+    def stop(self):
+        """Finalize the analysis when backtest ends.
+
+        Stores the maximum drawdown and maximum drawdown period.
+        """
+        self.rets["maxdrawdown"] = self.maxdd
+        self.rets["maxdrawdownperiod"] = self.maxddlen