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

backtrader/indicators/myind.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python
+"""Custom Indicators Module - User-defined indicators.
+
+This module contains custom indicator algorithms including:
+- MaBetweenHighAndLow: Check if MA is within price range
+- BarsLast: Count bars since condition was met
+- NewDiff: Guotai Junan alpha factor indicator
+
+Example:
+    To use these custom indicators in your strategy::
+
+        import backtrader as bt
+
+        class MyStrategy(bt.Strategy):
+            def __init__(self):
+                # Create MA Between High and Low indicator
+                self.ma_hl = bt.indicators.MaBetweenHighAndLow(
+                    self.data, period=5
+                )
+
+                # Create Bars Last indicator
+                self.bars_last = bt.indicators.BarsLast(
+                    self.data, period=5
+                )
+
+                # Create NewDiff indicator (Guotai Junan alpha factor)
+                self.new_diff = bt.indicators.NewDiff(
+                    self.data, period=6
+                )
+
+            def next(self):
+                # Use the indicators in your trading logic
+                if self.ma_hl.target[0] > 0:
+                    # MA is within high-low range
+                    self.buy()
+
+                if self.bars_last.bar_num[0] < 3:
+                    # Condition was met less than 3 bars ago
+                    self.sell()
+
+                # Access the alpha factor value
+                alpha_value = self.new_diff.factor[0]
+"""
+
+import math
+
+import numpy as np
+
+from . import SMA, If, Indicator, Max, Min
+
+# This file contains some custom indicator algorithms
+
+
+class MaBetweenHighAndLow(Indicator):
+    """Check if moving average is between high and low prices.
+
+    Returns 1.0 when SMA is within the bar's high-low range,
+    0.0 otherwise.
+    """
+
+    # Check if moving average is between high and low prices
+    lines = ("target",)
+    params = (("period", 5),)
+
+    def __init__(self):
+        """Initialize the MA Between High and Low indicator.
+
+        Creates SMA for comparison with high/low range.
+        """
+        super().__init__()
+        self.ma = SMA(self.data.close, period=self.p.period)
+
+    def next(self):
+        """Check if MA is between high and low for current bar.
+
+        Returns 1.0 if MA is within range, 0.0 otherwise.
+        """
+        ma_val = self.ma[0]
+        high_val = self.data.high[0]
+        low_val = self.data.low[0]
+        self.lines.target[0] = 1.0 if (ma_val < high_val and ma_val > low_val) else 0.0
+
+    def once(self, start, end):
+        """Check MA against high/low range in runonce mode.
+
+        Returns 1.0 where MA is within range, 0.0 otherwise.
+        """
+        ma_array = self.ma.lines[0].array
+        high_array = self.data.high.array
+        low_array = self.data.low.array
+        larray = self.lines.target.array
+
+        while len(larray) < end:
+            larray.append(float("nan"))
+
+        for i in range(start, min(end, len(ma_array), len(high_array), len(low_array))):
+            ma_val = ma_array[i] if i < len(ma_array) else 0.0
+            high_val = high_array[i] if i < len(high_array) else 0.0
+            low_val = low_array[i] if i < len(low_array) else 0.0
+
+            if isinstance(ma_val, float) and math.isnan(ma_val):
+                larray[i] = float("nan")
+            else:
+                larray[i] = 1.0 if (ma_val < high_val and ma_val > low_val) else 0.0
+
+
+class BarsLast(Indicator):
+    """Count bars since condition was last met.
+
+    Tracks the number of bars that have passed since a specified
+    condition (default: MaBetweenHighAndLow) was last true.
+    """
+
+    # This indicator analyzes the number of bars since the last condition was met
+    lines = ("bar_num",)
+    params = (("period", 5), ("func", MaBetweenHighAndLow))
+
+    def __init__(self):
+        """Initialize the Bars Last indicator.
+
+        Creates target function for condition checking.
+        """
+        self.target = self.p.func(self.data, period=self.p.period)
+        self.num = np.nan
+
+    def next(self):
+        """Count bars since condition was last met.
+
+        Resets to 0 when condition is true, increments otherwise.
+        """
+        if self.target[0]:
+            self.num = 0
+        self.lines.bar_num[0] = self.num
+        self.num = self.num + 1
+
+
+class NewDiff(Indicator):
+    """Guotai Junan alpha factor indicator.
+
+    Calculates a proprietary alpha factor based on price movement
+    relative to previous close and the high/low range.
+
+    Formula:
+        SUM((CLOSE==DELAY(CLOSE,1)?0:CLOSE-(CLOSE>DELAY(CLOSE,1)?
+        MIN(LOW,DELAY(CLOSE,1)):MAX(HIGH,DELAY(CLOSE,1)))), period)
+    """
+
+    # Indicator based on Guotai Junan alpha factor
+    # : SUM((CLOSE=DELAY(CLOSE,1)?0:CLOSE-(CLOSE>DELAY(CLOSE,1)?MIN(LOW,DELAY(CLOSE,1)):MAX(HIGH,DELAY(CLOSE,1)))),6)
+    # - e = MIN(LOW, DELAY(CLOSE, 1))
+    # - f = MAX(HIGH, DELAY(CLOSE, 1))
+    # - h = CLOSE > DELAY(CLOSE, 1)
+    # - b = h?e: f
+    # - a = CLOSE = DELAY(CLOSE, 1)?0: CLOSE - b
+    # - c = SUM(a, 6)
+    lines = ("factor",)
+    params = (("period", 5),)
+
+    def __init__(self):
+        """Initialize the NewDiff indicator.
+
+        Sets up alpha factor calculation based on Guotai Junan formula.
+        """
+        close = self.data.close
+        pre_close = self.data.close(-1)
+        e = Min(self.data.low, pre_close)
+        f = Max(self.data.high, pre_close)
+        b = If(close > pre_close, e, f)
+        self.a = If(close == pre_close, 0, close - b)
+
+    def next(self):
+        """Calculate NewDiff factor for the current bar.
+
+        Sums adjusted price differences over the period.
+        """
+        if len(self.a) >= self.p.period:
+            self.lines.factor[0] = math.fsum(self.a.get(size=self.p.period))
+        else:
+            self.lines.factor[0] = np.nan

backtrader/indicators/obv.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python
+"""On-Balance Volume indicator.
+
+This module provides the On-Balance Volume (OBV) cumulative volume indicator.
+OBV adds the current volume when the closing price rises, subtracts it when
+it falls, and leaves the cumulative value unchanged when the closing price is
+unchanged.
+
+Classes:
+    OnBalanceVolume: On-Balance Volume indicator (alias: OBV).
+
+Example:
+    class MyStrategy(bt.Strategy):
+        def __init__(self):
+            self.obv = bt.indicators.OBV(self.data)
+"""
+
+from . import Indicator
+
+
+class OnBalanceVolume(Indicator):
+    """Cumulative On-Balance Volume indicator.
+
+    Formula:
+      - first value = volume
+      - close > previous close: obv = previous obv + volume
+      - close < previous close: obv = previous obv - volume
+      - close == previous close: obv = previous obv
+    """
+
+    alias = ("OBV",)
+    lines = ("obv",)
+
+    def __init__(self):
+        """Initialize the indicator."""
+        super().__init__()
+
+    def nextstart(self):
+        """Seed OBV with the first available volume value."""
+        self.lines.obv[0] = self.data.volume[0]
+
+    def next(self):
+        """Update OBV for the current bar in event-driven mode."""
+        previous = self.lines.obv[-1]
+        close = self.data.close[0]
+        previous_close = self.data.close[-1]
+        volume = self.data.volume[0]
+
+        if close > previous_close:
+            self.lines.obv[0] = previous + volume
+        elif close < previous_close:
+            self.lines.obv[0] = previous - volume
+        else:
+            self.lines.obv[0] = previous
+
+    def oncestart(self, start, end):
+        """Seed OBV in batch-processing mode."""
+        dst = self.lines.obv.array
+        volume = self.data.volume.array
+
+        while len(dst) < end:
+            dst.append(float("nan"))
+
+        for i in range(start, min(end, len(volume))):
+            dst[i] = volume[i]
+
+    def once(self, start, end):
+        """Calculate OBV values in batch-processing mode."""
+        dst = self.lines.obv.array
+        close = self.data.close.array
+        volume = self.data.volume.array
+        actual_end = min(end, len(close), len(volume))
+
+        while len(dst) < end:
+            dst.append(float("nan"))
+
+        if start >= actual_end:
+            return
+
+        if start == 0:
+            dst[0] = volume[0]
+            start = 1
+
+        previous = dst[start - 1]
+        for i in range(start, actual_end):
+            if close[i] > close[i - 1]:
+                previous += volume[i]
+            elif close[i] < close[i - 1]:
+                previous -= volume[i]
+
+            dst[i] = previous
+
+
+OBV = OnBalanceVolume

backtrader/indicators/ols.py

@@ -0,0 +1,265 @@
+#!/usr/bin/env python
+"""OLS Indicator Module - Ordinary least squares regression.
+
+This module provides indicators using OLS (Ordinary Least Squares)
+regression for statistical analysis.
+
+Classes:
+    OLS_Slope_InterceptN: Calculates slope and intercept via OLS.
+    OLS_TransformationN: Calculates OLS transformed values.
+    OLS_BetaN: Calculates beta via OLS.
+    CointN: Tests for cointegration between series.
+
+Example:
+    class MyStrategy(bt.Strategy):
+        def __init__(self):
+            # Calculate OLS regression slope and intercept between two data feeds
+            self.ols = bt.indicators.OLS_Slope_InterceptN(self.data0, self.data1, period=30)
+
+            # Calculate OLS transformation (spread, zscore)
+            self.ols_trans = bt.indicators.OLS_TransformationN(self.data0, self.data1, period=30)
+
+        def next(self):
+            # Trade based on zscore of the spread
+            if self.ols_trans.zscore[0] > 2:
+                # Spread is too high - short data0, long data1
+                self.sell(data=self.data0)
+                self.buy(data=self.data1)
+            elif self.ols_trans.zscore[0] < -2:
+                # Spread is too low - long data0, short data1
+                self.buy(data=self.data0)
+                self.sell(data=self.data1)
+"""
+
+import pandas as pd
+
+from . import PeriodN
+
+# Lazy import statsmodels to avoid slow import at module load time
+# statsmodels is a heavy library that adds 20+ seconds to import time
+# It will be imported when the indicators are actually used
+
+
+def _get_statsmodels():
+    """Lazy import statsmodels.api."""
+    import statsmodels.api as sm
+
+    return sm
+
+
+def _get_coint():
+    """Lazy import statsmodels coint function."""
+    from statsmodels.tsa.stattools import coint
+
+    return coint
+
+
+__all__ = ["OLS_Slope_InterceptN", "OLS_TransformationN", "OLS_BetaN", "CointN"]
+
+
+class OLS_Slope_InterceptN(PeriodN):
+    """
+    Calculates a linear regression using ``statsmodel.OLS`` (Ordinary least
+    squares) of data1 on data0
+
+    Uses ``pandas`` and ``statsmodels``
+    """
+
+    _mindatas = 2  # ensure at least 2 data feeds are passed
+
+    packages = (
+        ("pandas", "pd"),
+        ("statsmodels.api", "sm"),
+    )
+    lines = (
+        "slope",
+        "intercept",
+    )
+    params = (("period", 10),)
+
+    def next(self):
+        """Calculate OLS slope and intercept for the current bar.
+
+        Uses statsmodels OLS to perform linear regression.
+        """
+        sm = _get_statsmodels()
+        p0 = pd.Series(self.data0.get(size=self.p.period))
+        p1 = pd.Series(self.data1.get(size=self.p.period))
+        p1 = sm.add_constant(p1)
+        intercept, slope = sm.OLS(p0, p1).fit().params
+
+        self.lines.slope[0] = slope
+        self.lines.intercept[0] = intercept
+
+
+class OLS_TransformationN(PeriodN):
+    """
+    Calculates the ``zscore`` for data0 and data1. Although it doesn't directly
+    use any external package, it relies on ``OLS_SlopeInterceptN`` which uses
+    ``pandas`` and ``statsmodels``
+    """
+
+    _mindatas = 2  # ensure at least 2 data feeds are passed
+    lines = (
+        "spread",
+        "spread_mean",
+        "spread_std",
+        "zscore",
+    )
+    params = (("period", 10),)
+
+    def __init__(self):
+        """Initialize the OLS Transformation indicator.
+
+        Creates OLS slope-intercept indicator for transformation calculations.
+        """
+        super().__init__()
+        self.slint = OLS_Slope_InterceptN(*self.datas)
+
+    def next(self):
+        """Calculate OLS transformation values for the current bar.
+
+        Computes spread, mean, std, and zscore based on OLS regression.
+        """
+        slope = self.slint.slope[0]
+        intercept = self.slint.intercept[0]
+        spread = self.data0[0] - (slope * self.data1[0] + intercept)
+        self.lines.spread[0] = spread
+
+        # Calculate spread_mean (SMA of spread)
+        period = self.p.period
+        spread_sum = spread
+        for i in range(1, period):
+            spread_sum += self.lines.spread[-i]
+        spread_mean = spread_sum / period
+        self.lines.spread_mean[0] = spread_mean
+
+        # Calculate spread_std (StdDev of spread)
+        var_sum = (spread - spread_mean) ** 2
+        for i in range(1, period):
+            var_sum += (self.lines.spread[-i] - spread_mean) ** 2
+        spread_std = (var_sum / period) ** 0.5
+        self.lines.spread_std[0] = spread_std
+
+        # Calculate zscore
+        if spread_std != 0:
+            self.lines.zscore[0] = (spread - spread_mean) / spread_std
+        else:
+            self.lines.zscore[0] = 0.0
+
+    def once(self, start, end):
+        """Calculate OLS transformation in runonce mode.
+
+        Computes spread, mean, std, and zscore values across all bars.
+        """
+
+        slope_array = self.slint.lines.slope.array
+        intercept_array = self.slint.lines.intercept.array
+        d0_array = self.data0.array
+        d1_array = self.data1.array
+        spread_array = self.lines.spread.array
+        mean_array = self.lines.spread_mean.array
+        std_array = self.lines.spread_std.array
+        zscore_array = self.lines.zscore.array
+        period = self.p.period
+
+        for arr in [spread_array, mean_array, std_array, zscore_array]:
+            while len(arr) < end:
+                arr.append(float("nan"))
+
+        # Calculate spread
+        for i in range(
+            start, min(end, len(slope_array), len(intercept_array), len(d0_array), len(d1_array))
+        ):
+            slope = slope_array[i] if i < len(slope_array) else 0.0
+            intercept = intercept_array[i] if i < len(intercept_array) else 0.0
+            d0 = d0_array[i] if i < len(d0_array) else 0.0
+            d1 = d1_array[i] if i < len(d1_array) else 0.0
+            spread_array[i] = d0 - (slope * d1 + intercept)
+
+        # Calculate spread_mean, spread_std, zscore
+        for i in range(start, min(end, len(spread_array))):
+            if i < period - 1:
+                mean_array[i] = float("nan")
+                std_array[i] = float("nan")
+                zscore_array[i] = float("nan")
+            else:
+                spread_sum = 0.0
+                for j in range(period):
+                    idx = i - j
+                    if idx >= 0 and idx < len(spread_array):
+                        spread_sum += spread_array[idx]
+                spread_mean = spread_sum / period
+                mean_array[i] = spread_mean
+
+                var_sum = 0.0
+                for j in range(period):
+                    idx = i - j
+                    if idx >= 0 and idx < len(spread_array):
+                        var_sum += (spread_array[idx] - spread_mean) ** 2
+                spread_std = (var_sum / period) ** 0.5
+                std_array[i] = spread_std
+
+                spread = spread_array[i]
+                if spread_std != 0:
+                    zscore_array[i] = (spread - spread_mean) / spread_std
+                else:
+                    zscore_array[i] = 0.0
+
+
+class OLS_BetaN(PeriodN):
+    """
+    Calculates a regression of data1 on data0 using ``pandas.ols``
+
+    Uses ``pandas``
+    """
+
+    _mindatas = 2  # ensure at least 2 data feeds are passed
+
+    packages = (("pandas", "pd"),)
+
+    lines = ("beta",)
+    params = (("period", 10),)
+
+    def next(self):
+        """Calculate beta via OLS regression for the current bar.
+
+        Uses pandas OLS to calculate regression beta.
+        """
+        y, x = (pd.Series(d.get(size=self.p.period)) for d in self.datas)
+        r_beta = pd.ols(y=y, x=x, window_type="full_sample")
+        self.lines.beta[0] = r_beta.beta["x"]
+
+
+class CointN(PeriodN):
+    """
+    Calculates the score (coint_t) and pvalue for a given ``period`` for the
+    data feeds
+
+    Uses ``pandas`` and ``statsmodels`` (for ``coint``)
+    """
+
+    _mindatas = 2  # ensure at least 2 data feeds are passed
+
+    packages = (("pandas", "pd"),)  # import pandas as pd
+    frompackages = (("statsmodels.tsa.stattools", "coint"),)  # from st... import coint
+
+    lines = (
+        "score",
+        "pvalue",
+    )
+    params = (
+        ("period", 10),
+        ("trend", "c"),  # see statsmodel.tsa.statttools
+    )
+
+    def next(self):
+        """Calculate cointegration test for the current period.
+
+        Uses statsmodels coint function to test for cointegration.
+        """
+        coint = _get_coint()
+        x, y = (pd.Series(d.get(size=self.p.period)) for d in self.datas)
+        score, pvalue, _ = coint(x, y, trend=self.p.trend)
+        self.lines.score[0] = score
+        self.lines.pvalue[0] = pvalue

backtrader/indicators/oscillator.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python
+"""Oscillator Indicator Module - Oscillating indicators.
+
+This module provides oscillator indicators that show the deviation
+of one data series from another, typically price from a moving average.
+
+Classes:
+    OscillatorMixIn: MixIn class to create oscillating indicators.
+    Oscillator: Oscillation of data around another data.
+
+Example:
+    class MyStrategy(bt.Strategy):
+        def __init__(self):
+            # Oscillate price around SMA
+            self.osc = bt.indicators.Oscillator(self.data, bt.indicators.SMA(self.data, period=20))
+
+        def next(self):
+            # When oscillator is positive, price is above SMA
+            if self.osc[0] > 0:
+                self.buy()
+            elif self.osc[0] < 0:
+                self.sell()
+"""
+
+import sys
+
+from ..utils.log_message import get_logger
+from . import Indicator, MovingAverage
+
+logger = get_logger(__name__)
+
+
+class OscillatorMixIn(Indicator):
+    """
+    MixIn class to create a subclass with another indicator. The main line of
+    that indicator will be substracted from the other base class main line
+    creating an oscillator
+
+    The usage is:
+
+      - Class XXXOscillator(XXX, OscillatorMixIn)
+
+    Formula:
+      - XXX calculates lines[0]
+      - osc = self.data - XXX.lines[0]
+    """
+
+    plotlines = {"_0": {"_name": "osc"}}
+
+    def _plotinit(self):
+        try:
+            lname = self.lines._getlinealias(0)
+            self.plotlines._0._name = lname + "_osc"
+        except AttributeError:
+            # No line alias available; keep the default plot label.
+            logger.debug("oscillator:55 ignored AttributeError")
+
+    def __init__(self):
+        """Initialize the oscillator by subtracting the base line from data."""
+        self.lines[0] = self.data - self.lines[0]
+        super().__init__()
+
+
+class Oscillator(Indicator):
+    """
+    Oscillation of given data around another data
+
+    Datas:
+      This indicator can accept one or two data for the calculation.
+
+      - If one data is provided, it must be a complex "Lines" object (indicator)
+        which also has "data".Example: A moving average
+
+        The calculated oscillation will be that of the Moving Average (in the
+        example) around the data that was used for the average calculation
+
+      - If two data are provided, the calculated oscillation will be that of the
+        second data around the first data
+
+    Formula:
+      - 1 data -> osc = data.data - data
+      - 2 datas -> osc = data0 - data1
+    """
+
+    lines = ("osc",)
+
+    # Have a default value which can be later modified if needed
+    plotlines = {"_0": {"_name": "osc"}}
+
+    def _plotinit(self):
+        try:
+            lname = self.dataosc._getlinealias(0)
+            self.plotlines._0._name = lname + "_osc"
+        except AttributeError:
+            # No line alias available; keep the default plot label.
+            logger.debug("oscillator:95 ignored AttributeError")
+
+    def __init__(self):
+        """Initialize the oscillator with data source and oscillator data.
+
+        Calculates the oscillation between two data series or between
+        a data series and its underlying data.
+        """
+        super().__init__()
+
+        if len(self.datas) > 1:
+            datasrc = self.data
+            self.dataosc = self.data1
+        else:
+            datasrc = self.data.data
+            self.dataosc = self.data
+
+        self.lines[0] = datasrc - self.dataosc
+
+
+# Automatic creation of Oscillating Lines
+
+for movav in MovingAverage._movavs[0:]:
+    _newclsdoc = """
+    Oscillation of a %s around its data
+    """
+    # Skip aliases - they will be created automatically
+    if getattr(movav, "aliased", ""):
+        continue
+
+    movname = movav.__name__
+    # Handle both tuple lines and Lines objects after refactoring
+    if hasattr(movav.lines, "_getlinealias"):
+        # It's a Lines object
+        linename = movav.lines._getlinealias(0)
+    elif isinstance(movav.lines, (tuple, list)) and movav.lines:
+        # It's a tuple/list of line names
+        linename = movav.lines[0]
+    else:
+        # Fallback to first line name or class name. The lambda is invoked
+        # immediately within this loop iteration (no late binding), so B023 is
+        # a false positive here.
+        linename = (
+            getattr(movav.lines, "_getlinealias", lambda x: movav.__name__.lower())(0)  # noqa: B023
+            if hasattr(movav.lines, "_getlinealias")
+            else movav.__name__.lower()
+        )
+
+    newclsname = movname + "Oscillator"
+
+    newaliases = [movname + "Osc"]
+    for alias in getattr(movav, "alias", []):
+        for suffix in ["Oscillator", "Osc"]:
+            newaliases.append(alias + suffix)
+
+    newclsdoc = _newclsdoc % movname
+    newclsdct = {
+        "__doc__": newclsdoc,
+        "__module__": OscillatorMixIn.__module__,
+        "_notregister": True,
+        "alias": newaliases,
+    }
+
+    newcls = type(str(newclsname), (movav, OscillatorMixIn), newclsdct)
+    module = sys.modules[OscillatorMixIn.__module__]
+    setattr(module, newclsname, newcls)