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

backtrader/indicators/priceops_ext.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python
+"""Price transform and simple signal indicators.
+
+This module hosts small price-derived indicators migrated from functional
+strategy tests. They are intentionally lightweight and depend only on the
+standard Backtrader line API so they can be reused as ``bt.indicators.Xxx``.
+"""
+
+from . import Indicator
+from .sma import SMA
+
+__all__ = [
+    "HighLowAverage",
+    "MedianPrice",
+    "PercentReturnsPeriod",
+    "SMACloseSignal",
+    "TypicalPrice",
+    "WeightedPrice",
+]
+
+
+class WeightedPrice(Indicator):
+    """Weighted price ``(high + low + 2 * close) / 4``.
+
+    The indicator exposes both ``value`` and ``weighted`` lines because the
+    migrated functional tests used both names for the same formula.
+    """
+
+    lines = ("value", "weighted")
+
+    def __init__(self):
+        """Wire the weighted price series into both ``value`` and ``weighted`` lines."""
+        weighted = (self.data.high + self.data.low + self.data.close * 2.0) / 4.0
+        self.lines.value = weighted
+        self.lines.weighted = weighted
+
+
+class MedianPrice(Indicator):
+    """Median price ``(high + low) / 2``."""
+
+    lines = ("value", "median")
+
+    def __init__(self):
+        """Wire the median-price series into both ``value`` and ``median`` lines."""
+        median = (self.data.high + self.data.low) / 2.0
+        self.lines.value = median
+        self.lines.median = median
+
+
+class TypicalPrice(Indicator):
+    """Typical price ``(high + low + close) / 3``."""
+
+    lines = ("typical", "value")
+
+    def __init__(self):
+        """Wire the typical-price series into both ``typical`` and ``value`` lines."""
+        typical = (self.data.high + self.data.low + self.data.close) / 3.0
+        self.lines.typical = typical
+        self.lines.value = typical
+
+
+class HighLowAverage(Indicator):
+    """Rolling average of the high-low range."""
+
+    lines = ("avg",)
+    params = (("period", 50),)
+
+    def __init__(self):
+        """Reserve the rolling window used for the high-low range average."""
+        self.addminperiod(self.p.period)
+
+    def next(self):
+        """Write the mean high-low range over the configured window to ``avg``.
+
+        Sums ``high - low`` for each of the last ``period`` bars
+        (current inclusive) and divides by ``period``. The output
+        line is updated in place; no value is returned.
+        """
+        total = 0.0
+        for i in range(self.p.period):
+            total += float(self.data.high[-i] - self.data.low[-i])
+        self.lines.avg[0] = total / self.p.period
+
+
+class PercentReturnsPeriod(Indicator):
+    """Percentage return over ``period`` bars using the close line."""
+
+    lines = ("returns",)
+    params = (("period", 40),)
+
+    def __init__(self):
+        """Reserve the rolling window used for the percentage return."""
+        self.addminperiod(self.p.period)
+
+    def next(self):
+        """Write ``(close - close[-period]) / close[-period]`` to ``returns``.
+
+        Uses the close at ``-period`` as the baseline so the value
+        is the simple percentage change over the configured window.
+        When the baseline is zero the value is forced to ``0`` to
+        avoid a division-by-zero error.
+        """
+        previous = self.data.close[-self.p.period]
+        if previous != 0:
+            self.lines.returns[0] = (self.data.close[0] - previous) / previous
+        else:
+            self.lines.returns[0] = 0
+
+
+class SMACloseSignal(Indicator):
+    """Signal line equal to current price minus its SMA."""
+
+    lines = ("signal",)
+    params = (("period", 30),)
+
+    def __init__(self):
+        """Compute ``data - SMA(data, period)`` and bind it to the ``signal`` line.
+
+        The line goes positive when the close is above its SMA and
+        negative when it is below, making it a simple momentum
+        proxy.
+        """
+        self.lines.signal = self.data - SMA(self.data, period=self.p.period)

backtrader/indicators/priceoscillator.py

@@ -0,0 +1,262 @@
+#!/usr/bin/env python
+"""Price Oscillator Module - Price oscillators.
+
+This module provides Price Oscillator indicators that measure the
+difference between two moving averages.
+
+Classes:
+    _PriceOscBase: Base class for price oscillators.
+    PriceOscillator: Price difference (aliases: PriceOsc, APO, AbsPriceOsc).
+    PercentagePriceOscillator: Percentage price oscillator (aliases: PPO, PercPriceOsc).
+    PercentagePriceOscillatorShort: PPO with short denominator (aliases: PPOShort).
+
+Example:
+    class MyStrategy(bt.Strategy):
+        def __init__(self):
+            self.ppo = bt.indicators.PPO(self.data, period1=12, period2=26)
+
+        def next(self):
+            if self.ppo.ppo[0] > self.ppo.signal[0]:
+                self.buy()
+            elif self.ppo.ppo[0] < self.ppo.signal[0]:
+                self.sell()
+"""
+
+import math
+
+from . import Indicator, MovAv
+
+
+class _PriceOscBase(Indicator):
+    params = (
+        ("period1", 12),
+        ("period2", 26),
+        ("_movav", MovAv.Exponential),
+    )
+
+    plotinfo = {"plothlines": [0.0]}
+
+    def __init__(self):
+        """Initialize the price oscillator base class.
+
+        Creates two moving averages with configured periods.
+        """
+        super().__init__()
+        self.ma1 = self.p._movav(self.data, period=self.p.period1)
+        self.ma2 = self.p._movav(self.data, period=self.p.period2)
+
+    def next(self):
+        """Calculate oscillator value: ma1 - ma2."""
+        self.lines[0][0] = self.ma1[0] - self.ma2[0]
+
+    def once(self, start, end):
+        """Calculate oscillator in runonce mode."""
+        ma1_array = self.ma1.lines[0].array
+        ma2_array = self.ma2.lines[0].array
+        larray = self.lines[0].array
+
+        while len(larray) < end:
+            larray.append(float("nan"))
+
+        for i in range(start, min(end, len(ma1_array), len(ma2_array))):
+            ma1_val = ma1_array[i] if i < len(ma1_array) else 0.0
+            ma2_val = ma2_array[i] if i < len(ma2_array) else 0.0
+
+            if (
+                isinstance(ma1_val, float)
+                and math.isnan(ma1_val)
+                or isinstance(ma2_val, float)
+                and math.isnan(ma2_val)
+            ):
+                larray[i] = float("nan")
+            else:
+                larray[i] = ma1_val - ma2_val
+
+
+# Moving average difference
+class PriceOscillator(_PriceOscBase):
+    """
+    Shows the difference between a short and long exponential moving
+    averages expressed in points.
+
+    Formula:
+      - po = ema(short) - ema(long)
+
+    See:
+      - http://www.metastock.com/Customer/Resources/TAAZ/?c=3&p=94
+    """
+
+    alias = (
+        "PriceOsc",
+        "AbsolutePriceOscillator",
+        "APO",
+        "AbsPriceOsc",
+    )
+    lines = ("po",)
+
+
+# Similar to MACD indicator, expressed in percentage
+class PercentagePriceOscillator(_PriceOscBase):
+    """
+    Shows the difference between a short and long exponential moving
+    averages expressed in percentage. The MACD does the same but expressed in
+    absolute points.
+
+    Expressing the difference in percentage allows to compare the indicator at
+    different points in time when the underlying value has significatnly
+    different values.
+
+    Formula:
+      - po = 100 * (ema(short) - ema(long)) / ema(long)
+
+    See:
+      - http://stockcharts.com/school/doku.php?id=chart_school:technical_indicators:price_oscillators_ppo
+    """
+
+    _long = True
+
+    alias = (
+        "PPO",
+        "PercPriceOsc",
+    )
+
+    lines = ("ppo", "signal", "histo")
+    params = (("period_signal", 9),)
+
+    plotlines = {"histo": {"_method": "bar", "alpha": 0.50, "width": 1.0}}
+
+    def __init__(self):
+        """Initialize the PPO indicator.
+
+        Sets up signal line EMA parameters.
+        """
+        super().__init__()
+        self.signal_alpha = 2.0 / (1.0 + self.p.period_signal)
+        self.signal_alpha1 = 1.0 - self.signal_alpha
+
+    def next(self):
+        """Calculate PPO, signal, and histogram for current bar.
+
+        PPO = 100 * (ma1 - ma2) / ma2
+        Signal = EMA(PPO)
+        Histogram = PPO - Signal
+        """
+        # Calculate base PO
+        po_val = self.ma1[0] - self.ma2[0]
+
+        # Calculate PPO
+        den = self.ma2[0] if self._long else self.ma1[0]
+        if den != 0:
+            ppo_val = 100.0 * po_val / den
+        else:
+            ppo_val = 0.0
+        self.lines.ppo[0] = ppo_val
+
+        # Calculate signal (EMA of PPO)
+        self.lines.signal[0] = (
+            self.lines.signal[-1] * self.signal_alpha1 + ppo_val * self.signal_alpha
+        )
+
+        # Calculate histogram
+        self.lines.histo[0] = self.lines.ppo[0] - self.lines.signal[0]
+
+    def nextstart(self):
+        """Seed PPO calculation on first valid bar.
+
+        Initializes signal line with first PPO value.
+        """
+        # Calculate base PO
+        po_val = self.ma1[0] - self.ma2[0]
+
+        # Calculate PPO
+        den = self.ma2[0] if self._long else self.ma1[0]
+        if den != 0:
+            ppo_val = 100.0 * po_val / den
+        else:
+            ppo_val = 0.0
+        self.lines.ppo[0] = ppo_val
+
+        # Seed signal with PPO
+        self.lines.signal[0] = ppo_val
+
+        # Calculate histogram
+        self.lines.histo[0] = 0.0
+
+    def once(self, start, end):
+        """Calculate PPO in runonce mode."""
+        ma1_array = self.ma1.lines[0].array
+        ma2_array = self.ma2.lines[0].array
+        ppo_array = self.lines.ppo.array
+        signal_array = self.lines.signal.array
+        histo_array = self.lines.histo.array
+        signal_alpha = self.signal_alpha
+        signal_alpha1 = self.signal_alpha1
+        use_long = self._long
+
+        for arr in [ppo_array, signal_array, histo_array]:
+            while len(arr) < end:
+                arr.append(float("nan"))
+
+        prev_signal = 0.0
+        for i in range(start, min(end, len(ma1_array), len(ma2_array))):
+            ma1_val = ma1_array[i] if i < len(ma1_array) else 0.0
+            ma2_val = ma2_array[i] if i < len(ma2_array) else 0.0
+
+            if isinstance(ma1_val, float) and math.isnan(ma1_val):
+                ppo_array[i] = float("nan")
+                signal_array[i] = float("nan")
+                histo_array[i] = float("nan")
+                continue
+            if isinstance(ma2_val, float) and math.isnan(ma2_val):
+                ppo_array[i] = float("nan")
+                signal_array[i] = float("nan")
+                histo_array[i] = float("nan")
+                continue
+
+            po_val = ma1_val - ma2_val
+
+            den = ma2_val if use_long else ma1_val
+            if den != 0:
+                ppo_val = 100.0 * po_val / den
+            else:
+                ppo_val = 0.0
+            ppo_array[i] = ppo_val
+
+            # Update signal
+            if i > 0 and i - 1 < len(signal_array):
+                prev_val = signal_array[i - 1]
+                if not (isinstance(prev_val, float) and math.isnan(prev_val)):
+                    prev_signal = prev_val
+
+            prev_signal = prev_signal * signal_alpha1 + ppo_val * signal_alpha
+            signal_array[i] = prev_signal
+
+            histo_array[i] = ppo_val - prev_signal
+
+
+class PercentagePriceOscillatorShort(PercentagePriceOscillator):
+    """
+    Shows the difference between a short and long exponential moving
+    averages expressed in percentage. The MACD does the same but expressed in
+    absolute points.
+
+    Expressing the difference in percentage allows to compare the indicator at
+    different points in time when the underlying value has significatnly
+    different values.
+
+    Most on-line literature shows the percentage calculation having the long
+    exponential moving average as the denominator. Some sources like MetaStock
+    use the short one.
+
+    Formula:
+      - po = 100 * (ema(short) - ema(long)) / ema(short)
+
+    See:
+      - http://www.metastock.com/Customer/Resources/TAAZ/?c=3&p=94
+    """
+
+    _long = False
+    alias = (
+        "PPOShort",
+        "PercPriceOscShort",
+    )

backtrader/indicators/psar.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python
+"""PSAR Indicator Module - Parabolic SAR.
+
+This module provides the Parabolic SAR (Stop and Reverse) indicator
+developed by J. Welles Wilder, Jr. for trend following and reversal signals.
+
+Classes:
+    ParabolicSAR: Parabolic SAR indicator (alias: PSAR).
+
+Example:
+    class MyStrategy(bt.Strategy):
+        def __init__(self):
+            self.psar = bt.indicators.PSAR(self.data)
+
+        def next(self):
+            # PSAR dots below price indicate uptrend
+            if self.psar.psar[0] < self.data.low[0]:
+                self.buy()
+            # PSAR dots above price indicate downtrend
+            elif self.psar.psar[0] > self.data.high[0]:
+                self.sell()
+"""
+
+from . import PeriodN
+
+__all__ = ["ParabolicSAR", "PSAR"]
+
+
+class _SarStatus:
+    """Internal status holder for Parabolic SAR calculations.
+
+    Attributes:
+        sar: Stop and Reverse value for the current period.
+        tr: Trend direction (True for long/up, False for short/down).
+        af: Acceleration factor, controlling how quickly SAR responds.
+        ep: Extreme point - highest high in uptrend or lowest low in downtrend.
+    """
+
+    sar = None
+    tr = None
+    af = 0.0
+    ep = 0.0
+
+    def __str__(self):
+        """Return a string representation of the SAR status.
+
+        Returns:
+            str: Multi-line string containing sar, tr, af, and ep values.
+        """
+        txt = []
+        txt.append(f"sar: {self.sar}")
+        txt.append(f"tr: {self.tr}")
+        txt.append(f"af: {self.af}")
+        txt.append(f"ep: {self.ep}")
+        return "\n".join(txt)
+
+
+class ParabolicSAR(PeriodN):
+    """Parabolic SAR (Stop and Reverse) indicator.
+
+    Defined by J. Welles Wilder, Jr. in 1978 in his book *New Concepts in
+    Technical Trading Systems*. SAR stands for Stop and Reverse, and the
+    indicator is meant as a signal for entry (and reverse).
+
+    The indicator places dots above or below price bars to indicate the
+    current trend direction. When the dots flip from above to below (or
+    vice versa), it signals a potential trend reversal.
+
+    The initial trend direction is determined by comparing the close price
+    of the second bar to the first bar. The SAR value accelerates toward
+    the price as the trend extends, using the acceleration factor.
+
+    See:
+        https://en.wikipedia.org/wiki/Parabolic_SAR
+        http://stockcharts.com/school/doku.php?id=chart_school:technical_indicators:parabolic_sar
+
+    Attributes:
+        psar: Line containing the calculated Parabolic SAR values.
+
+    Args:
+        period: Bar number from which to start showing values (default: 2).
+        af: Acceleration factor (default: 0.02).
+        afmax: Maximum acceleration factor (default: 0.20).
+    """
+
+    alias = ("PSAR",)
+    lines = ("psar",)
+    params = (
+        ("period", 2),  # when to start showing values
+        ("af", 0.02),
+        ("afmax", 0.20),
+    )
+
+    plotinfo = {"subplot": False}
+    plotlines = {
+        "psar": {"marker": ".", "markersize": 4.0, "color": "black", "fillstyle": "full", "ls": ""},
+    }
+
+    def prenext(self):
+        """Handle calculations before minimum period is reached.
+
+        Initializes status tracking and calculates initial PSAR values.
+        """
+        if len(self) == 1:
+            self._status = []  # empty status
+            return  # not enough data to do anything
+
+        if len(self) == 2:
+            self.nextstart()  # kickstart calculation
+        else:
+            self.next()  # regular calc
+
+        self.lines.psar[0] = float("NaN")  # no return yet still prenext
+
+    def nextstart(self):
+        """Initialize PSAR calculation on first valid bar.
+
+        Determines initial trend direction and sets up status tracking.
+        """
+        if self._status:  # some states have been calculated
+            self.next()  # delegate
+            return
+
+        # Prepare a status holding array, for current and previous lengths
+        self._status = [_SarStatus(), _SarStatus()]
+
+        # Start by looking if price has gone up/down (close) in the 2nd day to
+        # get an *entry* signal and configure the values as they would have
+        # been in the previous trend, including a sar value which is
+        # immediately invalidated in next, which reverses and sets the trend to
+        # the actual up/down value calculated with the close
+        # Put the 4 status variables in a Status holder
+        plenidx = (len(self) - 1) % 2  # previous length index (0 or 1)
+        status = self._status[plenidx]
+
+        # Calculate the status for previous length
+        status.sar = (self.data.high[0] + self.data.low[0]) / 2.0
+
+        status.af = self.p.af
+        if self.data.close[0] >= self.data.close[-1]:  # uptrend
+            status.tr = not True  # uptrend when reversed
+            status.ep = self.data.low[-1]  # ep from prev trend
+        else:
+            status.tr = not False  # downtrend when reversed
+            status.ep = self.data.high[-1]  # ep from prev trend
+
+        # With the fake prev trend in place and a sar which will be invalidated
+        # go to next to get the calculation done
+        self.next()
+
+    def next(self):
+        """Calculate PSAR for the current bar.
+
+        Updates the stop-and-reverse point based on trend direction,
+        extreme price, and acceleration factor.
+        """
+        hi = self.data.high[0]
+        lo = self.data.low[0]
+
+        plenidx = (len(self) - 1) % 2  # previous length index (0 or 1)
+        status = self._status[plenidx]  # use prev status for calculations
+
+        tr = status.tr
+        sar = status.sar
+
+        # Check if the sar penetrated the price to switch the trend
+        if (tr and sar >= lo) or (not tr and sar <= hi):
+            tr = not tr  # reverse the trend
+            sar = status.ep  # new sar is prev SIP (Significant price)
+            ep = hi if tr else lo  # select new SIP / Extreme Price
+            af = self.p.af  # reset acceleration factor
+
+        else:  # use the precalculated values
+            ep = status.ep
+            af = status.af
+
+        # Update sar value for today
+        self.lines.psar[0] = sar
+
+        # Update ep and af if needed
+        if tr:  # long trade
+            if hi > ep:
+                ep = hi
+                af = min(af + self.p.af, self.p.afmax)
+
+        else:  # downtrend
+            if lo < ep:
+                ep = lo
+                af = min(af + self.p.af, self.p.afmax)
+
+        sar = sar + af * (ep - sar)  # calculate the sar for tomorrow
+
+        # make sure sar doesn't go into hi/lows
+        if tr:  # long trade
+            lo1 = self.data.low[-1]
+            if sar > lo or sar > lo1:
+                sar = min(lo, lo1)  # sar not above last 2 lows -> lower
+        else:
+            hi1 = self.data.high[-1]
+            if sar < hi or sar < hi1:
+                sar = max(hi, hi1)  # sar not below last 2 highs -> highest
+
+        # new status has been calculated, keep it in current length
+        # will be used when length moves forward
+        newstatus = self._status[not plenidx]
+        newstatus.tr = tr
+        newstatus.sar = sar
+        newstatus.ep = ep
+        newstatus.af = af
+
+
+PSAR = ParabolicSAR

backtrader/indicators/rmi.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python
+"""Relative Momentum Index Module - RMI indicator.
+
+This module provides the Relative Momentum Index (RMI) developed by
+Roger Altman as a variation of RSI.
+
+Classes:
+    RelativeMomentumIndex: RMI indicator (alias: RMI).
+
+Example:
+    class MyStrategy(bt.Strategy):
+        def __init__(self):
+            self.rmi = bt.indicators.RMI(self.data, period=20, lookback=5)
+
+        def next(self):
+            # RMI above 70 indicates overbought
+            if self.rmi.rmi[0] > 70:
+                self.sell()
+            # RMI below 30 indicates oversold
+            elif self.rmi.rmi[0] < 30:
+                self.buy()
+"""
+
+from . import RSI
+
+
+class RelativeMomentumIndex(RSI):
+    """
+    Description:
+    The Relative Momentum Index was developed by Roger Altman and was
+    introduced in his article in the February 1993 issue of Technical Analysis
+    of Stocks & Commodities magazine.
+
+    While your typical RSI counts up and down days from close to close, the
+    Relative Momentum Index counts up and down days from the close relative to
+    a close x number of days ago. The result is an RSI that is a bit smoother.
+
+    Usage:
+    Use in the same way you would any other RSI. There are overbought and
+    oversold zones, and can also be used for divergence and trend analysis.
+
+    See:
+      - https://www.marketvolume.com/technicalanalysis/relativemomentumindex.asp
+      - https://www.tradingview.com/script/UCm7fIvk-FREE-INDICATOR-Relative-Momentum-Index-RMI/
+      - https://www.prorealcode.com/prorealtime-indicators/relative-momentum-index-rmi/
+
+    """
+
+    alias = ("RMI",)
+
+    linealias = (
+        (
+            "rsi",
+            "rmi",
+        ),
+    )  # add an alias for this class rmi -> rsi
+    plotlines = {"rsi": {"_name": "rmi"}}  # change line plotting name
+
+    params = (
+        ("period", 20),
+        ("lookback", 5),
+    )
+
+    def _plotlabel(self):
+        # override to always print the lookback label and do it before movav
+        plabels = [self.p.period]
+        plabels += [self.p.lookback]
+        plabels += [self.p.movav] * self.p.notdefault("movav")
+        return plabels