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

backtrader/analyzers/timereturn.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python
+"""TimeReturn Analyzer Module - Time-based returns calculation.
+
+This module provides the TimeReturn analyzer for calculating returns
+over specified time periods.
+
+Classes:
+    TimeReturn: Analyzer that calculates returns by timeframe.
+
+Example:
+    >>> cerebro = bt.Cerebro()
+    >>> cerebro.addanalyzer(bt.analyzers.TimeReturn, timeframe=bt.TimeFrame.Years)
+"""
+
+import math
+
+from ..analyzer import TimeFrameAnalyzerBase
+
+
+class TimeReturn(TimeFrameAnalyzerBase):
+    """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 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.
+        # When calculating returns for the first period, whether to use the first opening price. If parameter is False, the first closing price 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),
+    )
+
+    # __init__ method to support parameter initialization after metaclass removal
+    def __init__(self, *args, **kwargs):
+        """Initialize the TimeReturn analyzer.
+
+        Args:
+            *args: Positional arguments.
+            **kwargs: Keyword arguments for analyzer parameters.
+        """
+        super().__init__(*args, **kwargs)
+
+    # Start
+    def start(self):
+        """Initialize the analyzer at the start of the backtest.
+
+        Sets the fund mode and initializes the starting value for return
+        calculations.
+        """
+        super().start()
+        if self.p.fund is None:
+            self._fundmode = self.strategy.broker.fundmode
+        else:
+            self._fundmode = self.p.fund
+        # PERFORMANCE OPTIMIZATION: Cache p.data reference (called 691K+ times)
+        self._p_data = self.p.data
+        # Start value
+        self._value_start = 0.0
+        # End value
+        self._lastvalue = None
+        # If parameter data is None
+        if self._p_data is None:
+            # keep the initial portfolio value if not tracing a data
+            if not self._fundmode:
+                self._lastvalue = self.strategy.broker.getvalue()
+            else:
+                self._lastvalue = self.strategy.broker.fundvalue
+
+    # Notify fund information
+    def notify_fund(self, cash, value, fundvalue, shares):
+        """Update current value based on fund notification.
+
+        Args:
+            cash: Current cash amount.
+            value: Current portfolio value.
+            fundvalue: Current fund value.
+            shares: Number of fund shares.
+        """
+        # PERFORMANCE OPTIMIZATION: Use cached _p_data reference
+        p_data = self._p_data
+        if not self._fundmode:
+            # Record current value
+            if p_data is None:
+                self._value = value  # the portofolio value if tracking no data
+            else:
+                self._value = p_data[0]  # the data value if tracking data
+        else:
+            if p_data is None:
+                self._value = fundvalue  # the fund value if tracking no data
+            else:
+                self._value = p_data[0]  # the data value if tracking data
+
+    # On datetime over
+    def on_dt_over(self):
+        """Handle timeframe boundary crossing.
+
+        Updates the starting value for return calculation when crossing
+        into a new timeframe period.
+        """
+        # next is called in a new timeframe period
+        # PERFORMANCE OPTIMIZATION: Use cached _p_data reference
+        p_data = self._p_data
+        if p_data is None or self._lastvalue is not None:
+            self._value_start = self._lastvalue  # update value_start to last
+
+        else:
+            # The 1st tick has no previous reference, use the opening price
+            if self.p.firstopen:
+                self._value_start = p_data.open[0]
+            else:
+                self._value_start = p_data[0]
+
+    # Call next
+    def next(self):
+        """Calculate and store the return for the current period.
+
+        Calculates the return as (current_value / start_value) - 1 and
+        stores it in the results dictionary keyed by datetime.
+        """
+        # Calculate the return
+        super().next()
+        # self.dtkey is an attribute set in analyzer, usually the end date of a period
+        if self._value_start:
+            try:
+                ret = (self._value / self._value_start) - 1.0
+                if isinstance(ret, complex) or not math.isfinite(ret):
+                    ret = 0.0
+            except (ZeroDivisionError, TypeError, ValueError):
+                ret = 0.0
+            self.rets[self.dtkey] = ret
+        else:
+            self.rets[self.dtkey] = 0.0
+        # self.rets[self.dtkey] = (float(self._value) / float(self._value_start)) - 1.0
+        self._lastvalue = self._value  # keep last value

backtrader/analyzers/total_value.py

@@ -0,0 +1,75 @@
+"""TotalValue Analyzer Module - Portfolio value tracking.
+
+This module provides the TotalValue analyzer for tracking the total
+portfolio value over time.
+
+Classes:
+    TotalValue: Analyzer that records portfolio value at each step.
+
+Example:
+    >>> cerebro = bt.Cerebro()
+    >>> cerebro.addanalyzer(bt.analyzers.TotalValue, _name='val')
+    >>> results = cerebro.run()
+    >>> print(results[0].analyzers.val.get_analysis())
+"""
+
+import math
+from collections import OrderedDict
+from typing import Optional
+
+from ..analyzer import Analyzer
+
+
+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
+
+
+class TotalValue(Analyzer):
+    """This analyzer will get total value from every next.
+
+    Params:
+    Methods:
+
+      - Get_analysis
+
+        Returns a dictionary with returns as values and the datetime points for
+        each return as keys
+    """
+
+    params = ()
+    rets: Optional[dict] = None
+
+    def start(self):
+        """Initialize the analyzer at the start of the backtest.
+
+        Creates the ordered dictionary to store value history.
+        """
+        super().start()
+        self.rets = OrderedDict()
+        # PERFORMANCE OPTIMIZATION: Cache broker reference
+        self._broker = self.strategy.broker
+
+    # PERFORMANCE OPTIMIZATION: Cache attribute access, called 522K+ times
+    def next(self):
+        """Record the total portfolio value for the current bar.
+
+        Gets the current portfolio value from the broker and stores it
+        keyed by datetime.
+        """
+        # Calculate the return
+        super().next()
+        # Cache attribute access for performance
+        self.rets[self.datas[0].datetime.datetime()] = _finite_real_or_zero(self._broker.getvalue())
+
+    def get_analysis(self):
+        """Return the total value analysis results.
+
+        Returns:
+            OrderedDict: Dictionary mapping datetimes to portfolio values.
+        """
+        return self.rets

backtrader/analyzers/tradeanalyzer.py

@@ -0,0 +1,278 @@
+#!/usr/bin/env python
+"""Trade Analyzer Module - Detailed trade statistics.
+
+This module provides the TradeAnalyzer for calculating comprehensive
+trade statistics including win/loss ratios, streaks, and PnL metrics.
+
+Classes:
+    TradeAnalyzer: Analyzer that calculates detailed trade statistics.
+
+Example:
+    >>> cerebro = bt.Cerebro()
+    >>> cerebro.addanalyzer(bt.analyzers.TradeAnalyzer, _name='ta')
+    >>> results = cerebro.run()
+    >>> print(results[0].analyzers.ta.get_analysis())
+"""
+
+from ..analyzer import Analyzer
+from ..utils import AutoDict, AutoOrderedDict
+from ..utils.py3 import MAXINT
+
+
+# Analyze trades
+class TradeAnalyzer(Analyzer):
+    """
+    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 autodict 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
+    """
+
+    # rets is created in create_analysis(); declared here for typing only.
+    rets: AutoOrderedDict
+
+    # Create analysis
+    def create_analysis(self):
+        """Create the analysis result data structure.
+
+        Initializes the AutoOrderedDict with a total counter set to zero.
+        """
+        self.rets = AutoOrderedDict()
+        self.rets.total.total = 0
+
+    # Stop
+    def stop(self):
+        """Finalize the analysis when backtest ends.
+
+        Closes the results dictionary to prevent further modifications.
+        """
+        super().stop()
+        self.rets._close()
+
+    # Trade notification
+    def notify_trade(self, trade):
+        """Process trade notifications to build detailed statistics.
+
+        Updates all trade statistics including win/loss counts, streaks,
+        PnL metrics, and trade duration for both long and short positions.
+
+        Args:
+            trade: The trade object with status and PnL information.
+        """
+        # If trade just opened
+        if trade.justopened:
+            # Trade just opened
+            self.rets.total.total += 1
+            self.rets.total.open += 1
+        # If trade is closed
+        elif trade.status == trade.Closed:
+            self._on_trade_closed(trade)
+
+    def _on_trade_closed(self, trade):
+        """Update all closed-trade statistics (streak / pnl / won-lost /
+        long-short / length) for a single closed trade.
+
+        Extracted verbatim from notify_trade's Closed branch to keep that
+        dispatcher trivial; no behavior change. Split into per-category
+        helpers (streak / pnl / won-lost / long-short / length) to reduce
+        complexity; the computation order and shared ``res``/``trades``
+        state are preserved exactly.
+        """
+        trades = self.rets
+
+        res = AutoDict()
+        # Trade just closed
+        # Profit
+        res.won = int(trade.pnlcomm >= 0.0)
+        # Loss
+        res.lost = int(not res.won)
+        # Long position
+        res.tlong = trade.long
+        # Short position
+        res.tshort = not trade.long
+        # Opened trade
+        trades.total.open -= 1
+        # Closed trade
+        trades.total.closed += 1
+
+        self._update_streak(trades, res)
+        self._update_gross_net_pnl(trades, trade)
+        self._update_won_lost(trades, trade, res)
+        self._update_long_short(trades, trade, res)
+        self._update_length(trades, trade)
+        self._update_length_won_lost(trades, trade, res)
+        self._update_length_long_short(trades, trade, res)
+
+    @staticmethod
+    def _update_streak(trades, res):
+        """Streak: consecutive win and loss counts."""
+        for wlname in ["won", "lost"]:
+            # Current win/loss status
+            wl = res[wlname]
+            # Current consecutive win or loss count
+            trades.streak[wlname].current *= wl
+            trades.streak[wlname].current += wl
+            # Get maximum consecutive win or loss count
+            ls = trades.streak[wlname].longest or 0
+            # Recalculate
+            trades.streak[wlname].longest = max(ls, trades.streak[wlname].current)
+
+    @staticmethod
+    def _update_gross_net_pnl(trades, trade):
+        """Aggregate gross/net total and average trade pnl."""
+        # Trade profit/loss
+        trpnl = trades.pnl
+        # Total trade profit/loss
+        trpnl.gross.total += trade.pnl
+        # Average profit/loss
+        trpnl.gross.average = trades.pnl.gross.total / trades.total.closed
+        # Net trade profit/loss
+        trpnl.net.total += trade.pnlcomm
+        # Average net profit/loss
+        trpnl.net.average = trades.pnl.net.total / trades.total.closed
+
+    @staticmethod
+    def _update_won_lost(trades, trade, res):
+        """Won/Lost statistics: counts and pnl per win/loss bucket."""
+        for wlname in ["won", "lost"]:
+            # Current win/loss
+            wl = res[wlname]
+            # Historical win/loss
+            trwl = trades[wlname]
+            # Win/loss count
+            trwl.total += wl  # won.total / lost.total
+            # Total and average profit/loss
+            trwlpnl = trwl.pnl
+            pnlcomm = trade.pnlcomm * wl
+
+            trwlpnl.total += pnlcomm
+            trwlpnl.average = trwlpnl.total / (trwl.total or 1.0)
+            # Maximum profit or minimum loss (largest losing trade)
+            wm = trwlpnl.max or 0.0
+            func = max if wlname == "won" else min
+            trwlpnl.max = func(wm, pnlcomm)
+
+    @staticmethod
+    def _update_long_short(trades, trade, res):
+        """Long/Short statistics: counts and pnl per direction and win/loss."""
+        for tname in ["long", "short"]:
+            # Long and short
+            trls = trades[tname]
+            # Current trade's long and short
+            ls = res["t" + tname]
+            # Calculate long and short counts
+            trls.total += ls  # long.total / short.total
+            # Calculate total pnl for long and short
+            trls.pnl.total += trade.pnlcomm * ls
+            # Calculate average profit for long and short
+            trls.pnl.average = trls.pnl.total / (trls.total or 1.0)
+            # Analyze win/loss status for long and short
+            for wlname in ["won", "lost"]:
+                wl = res[wlname]
+                pnlcomm = trade.pnlcomm * wl * ls
+
+                trls[wlname] += wl * ls  # long.won / short.won
+
+                trls.pnl[wlname].total += pnlcomm
+                trls.pnl[wlname].average = trls.pnl[wlname].total / (trls[wlname] or 1.0)
+
+                wm = trls.pnl[wlname].max or 0.0
+                func = max if wlname == "won" else min
+                trls.pnl[wlname].max = func(wm, pnlcomm)
+
+    @staticmethod
+    def _update_length(trades, trade):
+        """Length: total/average/max/min bars across all closed trades."""
+        # Number of bars occupied by trade
+        trades.len.total += trade.barlen
+        # Average number of bars per trade
+        trades.len.average = trades.len.total / trades.total.closed
+        # Maximum number of bars occupied by trade
+        ml = trades.len.max or 0
+        trades.len.max = max(ml, trade.barlen)
+        # Minimum number of bars occupied by trade
+        ml = trades.len.min or MAXINT
+        trades.len.min = min(ml, trade.barlen)
+
+    @staticmethod
+    def _update_length_won_lost(trades, trade, res):
+        """Length split by win/loss bucket."""
+        # Number of bars for winning/losing trades, similar to above but separated by profit and loss
+        for wlname in ["won", "lost"]:
+            trwl = trades.len[wlname]
+            wl = res[wlname]
+
+            trwl.total += trade.barlen * wl
+            trwl.average = trwl.total / (trades[wlname].total or 1.0)
+
+            m = trwl.max or 0
+            trwl.max = max(m, trade.barlen * wl)
+            if trade.barlen * wl:
+                m = trwl.min or MAXINT
+                trwl.min = min(m, trade.barlen * wl)
+
+    @staticmethod
+    def _update_length_long_short(trades, trade, res):
+        """Length split by direction and win/loss bucket."""
+        # Distinguish long and short lengths
+        for lsname in ["long", "short"]:
+            trls = trades.len[lsname]  # trades.len.long
+            ls = res["t" + lsname]  # tlong/tshort
+
+            barlen = trade.barlen * ls
+
+            trls.total += barlen  # trades.len.long.total
+            total_ls = trades[lsname].total  # trades.long.total
+            trls.average = trls.total / (total_ls or 1.0)
+
+            # max/min
+            m = trls.max or 0
+            trls.max = max(m, barlen)
+            m = trls.min or MAXINT
+            trls.min = min(m, barlen or m)
+            # Distinguish winning and losing lengths for long and short
+            for wlname in ["won", "lost"]:
+                wl = res[wlname]  # won/lost
+
+                barlen2 = trade.barlen * ls * wl
+
+                trls_wl = trls[wlname]  # trades.len.long.won
+                trls_wl.total += barlen2  # trades.len.long.won.total
+
+                trls_wl.average = trls_wl.total / (trades[lsname][wlname] or 1.0)
+
+                # max/min
+                m = trls_wl.max or 0
+                trls_wl.max = max(m, barlen2)
+                m = trls_wl.min or MAXINT
+                trls_wl.min = min(m, barlen2 or m)

backtrader/analyzers/transactions.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python
+"""Transactions Analyzer Module - Transaction logging.
+
+This module provides the Transactions analyzer for recording all
+transactions (order executions) during backtesting.
+
+Classes:
+    Transactions: Analyzer that records transaction history.
+
+Example:
+    >>> cerebro = bt.Cerebro()
+    >>> cerebro.addanalyzer(bt.analyzers.Transactions, _name='txn')
+    >>> results = cerebro.run()
+    >>> print(results[0].analyzers.txn.get_analysis())
+"""
+
+import collections
+
+from ..analyzer import Analyzer
+from ..order import Order
+from ..position import Position
+
+
+# Transactions
+class Transactions(Analyzer):
+    """This analyzer reports the transactions occurred with each 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'
+
+    Methods:
+
+      - Get_analysis
+
+        Returns a dictionary with returns as values and the datetime points for
+        each return as keys
+    """
+
+    # Parameters
+    params = (
+        ("headers", False),
+        ("_pfheaders", ("date", "amount", "price", "sid", "symbol", "value")),
+    )
+
+    # Initialize
+    def __init__(self, *args, **kwargs):
+        """Initialize the Transactions 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._idnames = None
+        self._positions = None
+
+    def start(self):
+        """Initialize the analyzer at the start of the backtest.
+
+        Sets up the results structure and initializes position tracking
+        for each data feed.
+        """
+        super().start()
+        # If headers is True, initialize rets
+        if self.p.headers:
+            self.rets[self.p._pfheaders[0]] = [list(self.p._pfheaders[1:])]
+        # Positions
+        self._positions = collections.defaultdict(Position)
+        # Index and data names
+        self._idnames = list(enumerate(self.strategy.getdatanames()))
+
+    # Order information processing
+    def notify_order(self, order):
+        """Process order execution notifications.
+
+        Updates the position tracking when orders are executed or partially
+        executed. Collected positions are recorded in the next() method.
+
+        Args:
+            order: The order object with execution information.
+        """
+        # An order could have several partial executions per cycle (unlikely
+        # but possible) and therefore: collect each new execution notification
+        # and let the work for the next
+
+        # We use a fresh Position object for each round to get a summary of what
+        # the execution bits have done in that round
+        # If order is not executed, ignore
+        if order.status not in [Order.Partial, Order.Completed]:
+            return  # It's not an execution
+        # Get position of the data that generated the order
+        pos = self._positions[order.data._name]
+        # Loop
+        for exbit in order.executed.iterpending():
+            # If execution info is None, break
+            if exbit is None:
+                break  # end of pending reached
+            # Update position information
+            pos.update(exbit.size, exbit.price)
+
+    # Called once per bar
+    def next(self):
+        """Record transactions for the current bar.
+
+        Collects position changes from all data feeds and records them
+        in the results dictionary keyed by datetime.
+        """
+        # super(Transactions, self).next()  # let dtkey update
+        # Entries
+        entries = []
+        # For index and data names
+        for i, dname in self._idnames:
+            # Get position of the data
+            pos = self._positions.get(dname, None)
+            # If position is not None, if position is not 0, save position related data
+            if pos is not None:
+                size, price = pos.size, pos.price
+                if size:
+                    entries.append([size, price, i, dname, -size * price])
+        # If position is not 0, update current bar's position data
+        if entries:
+            self.rets[self.strategy.datetime.datetime()] = entries
+        # Clear self._positions
+        self._positions.clear()