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

backtrader/analyzers/leverage.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python
+"""Leverage Analyzer Module - Gross leverage calculation.
+
+This module provides the GrossLeverage analyzer for calculating the
+gross leverage (ratio of used capital to portfolio value).
+
+Classes:
+    GrossLeverage: Analyzer that calculates gross leverage.
+
+Example:
+    >>> cerebro = bt.Cerebro()
+    >>> cerebro.addanalyzer(bt.analyzers.GrossLeverage, _name='lev')
+    >>> results = cerebro.run()
+    >>> print(results[0].analyzers.lev.get_analysis())
+"""
+
+import math
+
+from ..analyzer import Analyzer
+from ..mathsupport import is_finite_real
+
+
+# Ratio of used capital
+class GrossLeverage(Analyzer):
+    """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
+
+    Methods:
+
+      - Get_analysis
+
+        Returns a dictionary with returns as values and the datetime points for
+        each return as keys
+    """
+
+    # Parameters
+    params = (("fund", None),)
+
+    # Start
+    def __init__(self, *args, **kwargs):
+        """Initialize the GrossLeverage analyzer.
+
+        Args:
+            *args: Positional arguments.
+            **kwargs: Keyword arguments for analyzer parameters.
+        """
+        # CRITICAL FIX: Call super().__init__() first to initialize self.p
+        super().__init__(*args, **kwargs)
+        self._value = None
+        self._cash = None
+        self._fundmode = None
+
+    def start(self):
+        """Initialize the analyzer at the start of the backtest.
+
+        Sets the fund mode based on parameters or broker settings.
+        """
+        if self.p.fund is None:
+            self._fundmode = self.strategy.broker.fundmode
+        else:
+            self._fundmode = self.p.fund
+
+    # Fund notification
+    def notify_fund(self, cash, value, fundvalue, shares):
+        """Update cash and value from fund notification.
+
+        Args:
+            cash: Current cash amount.
+            value: Current portfolio value.
+            fundvalue: Current fund value.
+            shares: Number of fund shares.
+        """
+        self._cash = cash
+        if not self._fundmode:
+            self._value = value
+        else:
+            self._value = fundvalue
+
+    # Run once per bar, get ratio of used capital
+    def next(self):
+        """Calculate and record the gross leverage for the current bar.
+
+        Gross leverage is calculated as (value - cash) / value.
+        Returns 0.0 if 100% in cash, 1.0 if fully invested without shorting.
+        """
+        # Updates the leverage for "dtkey" (see base class) for each cycle
+        # 0.0 if 100% in cash, 1.0 if no short selling and fully invested
+        try:
+            if is_finite_real(self._value) and self._value != 0.0 and is_finite_real(self._cash):
+                lev = (self._value - self._cash) / self._value
+                if isinstance(lev, complex) or not math.isfinite(lev):
+                    lev = 0.0
+            else:
+                lev = 0.0
+        except (TypeError, ValueError, ZeroDivisionError):
+            lev = 0.0
+
+        if isinstance(lev, complex) or not math.isfinite(lev):
+            lev = 0.0
+
+        self.rets[self.data0.datetime.datetime()] = lev

backtrader/analyzers/logreturnsrolling.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python
+"""LogReturnsRolling Analyzer Module - Rolling log returns calculation.
+
+This module provides the LogReturnsRolling analyzer for calculating
+rolling log returns over a specified timeframe.
+
+Classes:
+    LogReturnsRolling: Analyzer that calculates rolling log returns.
+
+Example:
+    >>> cerebro = bt.Cerebro()
+    >>> cerebro.addanalyzer(bt.analyzers.LogReturnsRolling)
+"""
+
+import collections
+import math
+
+from ..analyzer import TimeFrameAnalyzerBase
+from ..utils.log_message import get_logger, throttled_warning
+
+logger = get_logger(__name__)
+
+__all__ = ["LogReturnsRolling"]
+
+
+class LogReturnsRolling(TimeFrameAnalyzerBase):
+    """This analyzer calculates rolling returns for a given timeframe and
+    compression
+
+    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 `None`, then the compression of the first data in 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 `data` the following is done when
+        crossing a timeframe boundary, for example, ``Years``:
+
+          - Last ``close`` the previous year is used as the reference price to
+            see the return in the current year
+
+        The problem is the first 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 first calculation.
+
+        This requires the data feed to have an ``open`` price (for ``close``
+        the standard [0] notations will be used without a 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
+
+    Methods:
+
+      - Get_analysis
+
+        Returns a dictionary with returns as values and the datetime points for
+        each return as keys
+    """
+
+    # Parameters
+    params = (
+        ("data", None),
+        ("firstopen", True),
+        ("fund", None),
+    )
+
+    # Start
+    def __init__(self, *args, **kwargs):
+        """Initialize the LogReturnsRolling 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._value = None
+        self._lastvalue = None
+        self._values = None
+        self._fundmode = None
+
+    def start(self):
+        """Initialize the analyzer at the start of the backtest.
+
+        Sets the fund mode and initializes the rolling value queue
+        with size controlled by compression parameter.
+        """
+        super().start()
+        if self.p.fund is None:
+            self._fundmode = self.strategy.broker.fundmode
+        else:
+            self._fundmode = self.p.fund
+        # The special part is that self._values is set as a queue, where self.compression parameter controls how many elements the queue saves
+        # Note: use self.compression (set in _start from data) not self.p.compression (which may be None)
+        self._values = collections.deque([float("Nan")] * self.compression, maxlen=self.compression)
+
+        if self.p.data is None:
+            # keep the initial portfolio value if not tracing data
+            if not self._fundmode:
+                self._lastvalue = self.strategy.broker.getvalue()
+            else:
+                self._lastvalue = self.strategy.broker.fundvalue
+
+    def notify_fund(self, cash, value, fundvalue, shares):
+        """Update current value from fund notification.
+
+        Args:
+            cash: Current cash amount.
+            value: Current portfolio value.
+            fundvalue: Current fund value.
+            shares: Number of fund shares.
+        """
+        if not self._fundmode:
+            self._value = value if self.p.data is None else self.p.data[0]
+        else:
+            self._value = fundvalue if self.p.data is None else self.p.data[0]
+
+    # Called once in a new timeframe
+    def on_dt_over(self):
+        """Handle timeframe boundary crossing.
+
+        Updates the rolling value queue when entering a new period.
+        """
+        # next is called in a new timeframe period
+        if self.p.data is None or len(self.p.data) > 1:
+            # Not tracking a data feed or data feed has data already
+            vst = self._lastvalue  # update value_start to last
+        else:
+            # The 1st tick has no previous reference, use the opening price
+            vst = self.p.data.open[0] if self.p.firstopen else self.p.data[0]
+
+        self._values.append(vst)  # push values backwards (and out)
+
+    def next(self):
+        """Calculate and store the rolling log return for the current period.
+
+        Calculates log(current_value / oldest_value) from the rolling window.
+        """
+        # Calculate the return
+        super().next()
+        # When the strategy is running, if there are too many losses, self._value / self._values[0] might be 0, avoid this situation
+        try:
+            start_value = self._values[0]
+            ratio = self._value / start_value
+            if isinstance(ratio, complex) or not math.isfinite(ratio) or ratio <= 0:
+                raise ValueError(f"invalid log return ratio: {ratio}")
+            log_return = math.log(ratio)
+            if not math.isfinite(log_return):
+                raise ValueError(f"invalid log return value: {log_return}")
+            self.rets[self.dtkey] = log_return
+        except (TypeError, ValueError, ZeroDivisionError, OverflowError) as e:
+            throttled_warning(
+                logger,
+                "rolling_log_return",
+                "Log return calculation failed: %s",
+                e,
+                exc_info=False,
+            )
+            self.rets[self.dtkey] = 0.0
+        self._lastvalue = self._value  # keep last value

backtrader/analyzers/periodstats.py

@@ -0,0 +1,153 @@
+#!/usr/bin/env python
+"""Period Statistics Analyzer Module - Basic statistics by period.
+
+This module provides the PeriodStats analyzer for calculating basic
+statistics (average, standard deviation, etc.) for a given timeframe.
+
+Classes:
+    PeriodStats: Analyzer that calculates period statistics.
+
+Example:
+    >>> cerebro = bt.Cerebro()
+    >>> cerebro.addanalyzer(bt.analyzers.PeriodStats, _name='stats')
+    >>> results = cerebro.run()
+    >>> print(results[0].analyzers.stats.get_analysis())
+"""
+
+import math
+
+from ..analyzer import Analyzer
+from ..dataseries import TimeFrame
+from ..mathsupport import average, standarddev
+from ..metabase import OwnerContext
+from ..utils.py3 import itervalues
+from .timereturn import TimeReturn
+
+__all__ = ["PeriodStats"]
+
+
+# Period statistics
+class PeriodStats(Analyzer):
+    """Calculates basic statistics for given timeframe
+
+    Params:
+
+      - ``timeframe`` (default: ``Years``)
+        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: ``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 first data in 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
+    """
+
+    # Parameters
+    params = (
+        ("timeframe", TimeFrame.Years),
+        ("compression", 1),
+        ("zeroispos", False),
+        ("fund", None),
+    )
+
+    # Initialize, call TimeReturn
+    def __init__(self, *args, **kwargs):
+        """Initialize the PeriodStats analyzer.
+
+        Args:
+            *args: Positional arguments.
+            **kwargs: Keyword arguments for analyzer parameters.
+        """
+        # CRITICAL FIX: Call super().__init__() first to initialize self.p
+        super().__init__(*args, **kwargs)
+        # Use OwnerContext so child analyzer can find this as its parent
+        with OwnerContext.set_owner(self):
+            self._tr = TimeReturn(
+                timeframe=self.p.timeframe, compression=self.p.compression, fund=self.p.fund
+            )
+
+    # Stop
+    def stop(self):
+        """Calculate period statistics when backtest ends.
+
+        Computes average, standard deviation, and count of positive/negative/
+        zero returns for the specified timeframe period.
+        """
+        # Get returns, default is annual
+        trets = self._tr.get_analysis()  # dict key = date, value = ret
+        # Count years with positive, negative, and zero returns
+        pos = nul = neg = 0
+        sanitized_trets = []
+        for tret in itervalues(trets):
+            try:
+                tret = float(tret)
+            except (TypeError, ValueError):
+                tret = 0.0
+            if not math.isfinite(tret):
+                tret = 0.0
+            sanitized_trets.append(tret)
+        trets = sanitized_trets
+        if not trets:
+            self.rets["average"] = 0.0
+            self.rets["stddev"] = 0.0
+            self.rets["positive"] = 0
+            self.rets["negative"] = 0
+            self.rets["nochange"] = 0
+            self.rets["best"] = 0.0
+            self.rets["worst"] = 0.0
+            return
+
+        for tret in trets:
+            if tret > 0.0:
+                pos += 1
+            elif tret < 0.0:
+                neg += 1
+            else:
+                # Whether 0 is considered positive return
+                if self.p.zeroispos:
+                    pos += tret == 0.0
+                else:
+                    nul += tret == 0.0
+        # Average return
+        self.rets["average"] = avg = average(trets)
+        # Return standard deviation
+        self.rets["stddev"] = standarddev(trets, avg)
+        # Number of positive years
+        self.rets["positive"] = pos
+        # Number of negative years
+        self.rets["negative"] = neg
+        # Number of unchanged years
+        self.rets["nochange"] = nul
+        # Best year return
+        self.rets["best"] = max(trets)
+        # Worst year return
+        self.rets["worst"] = min(trets)

backtrader/analyzers/positions.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python
+"""Positions Analyzer Module - Position value tracking.
+
+This module provides the PositionsValue analyzer for tracking the
+value of positions across all data feeds.
+
+Classes:
+    PositionsValue: Analyzer that reports position values over time.
+
+Example:
+    >>> cerebro = bt.Cerebro()
+    >>> cerebro.addanalyzer(bt.analyzers.PositionsValue, _name='posval')
+    >>> results = cerebro.run()
+    >>> print(results[0].analyzers.posval.get_analysis())
+"""
+
+import math
+
+from ..analyzer import Analyzer
+from ..dataseries import TimeFrame
+
+
+def _finite_real_or_zero(value):
+    try:
+        if isinstance(value, complex) or not math.isfinite(value):
+            return 0.0
+    except TypeError:
+        return 0.0
+    return value
+
+
+# Position value
+class PositionsValue(Analyzer):
+    """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 first 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 first data in the system will be
+        used
+
+      - headers (default: ``False``)
+
+        Add an initial key to the dictionary holding the results with the names
+        of the data 'Datetime' as a key
+
+      - cash (default: ``False``)
+
+        Include the actual cash as an extra position (for the header 'cash'
+        will be used as name)
+
+    Methods:
+
+      - get_analysis
+
+        Returns a dictionary with returns as values and the datetime points for
+        each return as keys
+    """
+
+    # Parameters
+    params = (
+        ("headers", False),
+        ("cash", False),
+    )
+
+    # Start
+    def __init__(self, *args, **kwargs):
+        """Initialize the PositionsValue analyzer.
+
+        Args:
+            *args: Positional arguments.
+            **kwargs: Keyword arguments for analyzer parameters.
+        """
+        # CRITICAL FIX: Call super().__init__() first to initialize self.p
+        super().__init__(*args, **kwargs)
+        self._usedate = None
+
+    def start(self):
+        """Initialize the analyzer at the start of the backtest.
+
+        Sets up headers for the results dictionary and determines whether
+        to use date or datetime as the key based on the timeframe.
+        """
+        # If headers parameter is True, use each data's name as header
+        if self.p.headers:
+            headers = [d._name or "Data%d" % i for i, d in enumerate(self.datas)]
+            # If cash is True, also save cash
+            self.rets["Datetime"] = headers + ["cash"] * self.p.cash
+        # Time period
+        tf = min(d._timeframe for d in self.datas)
+        # If time period >= Days, set usedate parameter to True
+        self._usedate = tf >= TimeFrame.Days
+
+    # Called once per bar
+    def next(self):
+        """Record position values for the current bar.
+
+        Gets the value of positions for each data feed and optionally
+        includes cash. Stores results keyed by date or datetime.
+        """
+        # Get value for each data
+        pvals = [_finite_real_or_zero(self.strategy.broker.get_value([d])) for d in self.datas]
+        # If cash is True, save cash
+        if self.p.cash:
+            pvals.append(_finite_real_or_zero(self.strategy.broker.get_cash()))
+        # If usedate is True, use date as key, otherwise use datetime as key
+        if self._usedate:
+            self.rets[self.strategy.datetime.date()] = pvals
+        else:
+            self.rets[self.strategy.datetime.datetime()] = pvals