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

backtrader/indicators/bollinger.py

@@ -0,0 +1,223 @@
+#!/usr/bin/env python
+"""Bollinger Bands Indicator Module - Volatility bands.
+
+This module provides the Bollinger Bands indicator developed by
+John Bollinger in the 1980s for measuring market volatility.
+
+Classes:
+    BollingerBands: Bollinger Bands indicator (alias: BBands).
+    BollingerBandsPct: Bollinger Bands with %B line.
+
+Example:
+    class MyStrategy(bt.Strategy):
+        def __init__(self):
+            self.bbands = bt.indicators.BBands(self.data, period=20, devfactor=2.0)
+
+        def next(self):
+            if self.data.close[0] < self.bbands.bot[0]:
+                self.buy()
+            elif self.data.close[0] > self.bbands.top[0]:
+                self.sell()
+"""
+
+import math
+
+from . import Indicator, MovAv
+
+
+class BollingerBands(Indicator):
+    """
+    Defined by John Bollinger in the 80s. It measures volatility by defining
+    upper and lower bands at distance x standard deviations
+
+    Formula:
+      - midband = SimpleMovingAverage(close, period)
+      - topband = midband + devfactor * StandardDeviation(data, period)
+      - botband = midband - devfactor * StandardDeviation(data, period)
+
+    See:
+      - http://en.wikipedia.org/wiki/Bollinger_Bands
+    """
+
+    alias = ("BBands",)
+
+    lines = (
+        "mid",
+        "top",
+        "bot",
+    )
+    params = (
+        ("period", 20),
+        ("devfactor", 2.0),
+        ("movav", MovAv.Simple),
+    )
+
+    plotinfo = {"subplot": False}
+    plotlines = {
+        "mid": {"ls": "--"},
+        "top": {"_samecolor": True},
+        "bot": {"_samecolor": True},
+    }
+
+    def _plotlabel(self):
+        plabels = [self.p.period, self.p.devfactor]
+        plabels += [self.p.movav] * self.p.notdefault("movav")
+        return plabels
+
+    def __init__(self):
+        """Initialize the Bollinger Bands indicator.
+
+        Sets minimum period to the configured period.
+        """
+        super().__init__()
+        self.addminperiod(self.p.period)
+
+    def next(self):
+        """Calculate Bollinger Bands for the current bar.
+
+        Calculates mid (SMA), top (mid + devfactor*stddev), and
+        bot (mid - devfactor*stddev) bands.
+        """
+        period = self.p.period
+        devfactor = self.p.devfactor
+
+        # Calculate SMA (mid)
+        data_sum = 0.0
+        data_sq_sum = 0.0
+        for i in range(period):
+            val = self.data[-i]
+            data_sum += val
+            data_sq_sum += val * val
+
+        mid = data_sum / period
+
+        # Calculate StdDev
+        meansq = data_sq_sum / period
+        sqmean = mid * mid
+        diff = abs(meansq - sqmean)
+        stddev = math.sqrt(max(0, diff))
+
+        # Set lines
+        self.lines.mid[0] = mid
+        self.lines.top[0] = mid + devfactor * stddev
+        self.lines.bot[0] = mid - devfactor * stddev
+
+    def once(self, start, end):
+        """Calculate Bollinger Bands in runonce mode."""
+        darray = self.data.array
+        mid_array = self.lines.mid.array
+        top_array = self.lines.top.array
+        bot_array = self.lines.bot.array
+        period = self.p.period
+        devfactor = self.p.devfactor
+        actual_end = min(end, len(darray))
+        darray_len = len(darray)
+
+        # Ensure arrays are sized
+        for arr in [mid_array, top_array, bot_array]:
+            while len(arr) < end:
+                arr.append(float("nan"))
+
+        # PERFORMANCE: Cache constants and functions
+        nan_val = float("nan")
+        sqrt = math.sqrt
+
+        # Pre-fill warmup with NaN
+        for i in range(min(period - 1, darray_len)):
+            mid_array[i] = nan_val
+            top_array[i] = nan_val
+            bot_array[i] = nan_val
+
+        for i in range(period - 1, actual_end):
+            data_sum = 0.0
+            data_sq_sum = 0.0
+            has_nan = False
+
+            # PERFORMANCE: Simplified loop with faster NaN check
+            for j in range(period):
+                idx = i - j
+                if 0 <= idx < darray_len:
+                    val = darray[idx]
+                    # PERFORMANCE: Use val != val for NaN check (faster)
+                    if val != val:
+                        has_nan = True
+                        break
+                    data_sum += val
+                    data_sq_sum += val * val
+
+            if has_nan:
+                mid_array[i] = nan_val
+                top_array[i] = nan_val
+                bot_array[i] = nan_val
+                continue
+
+            mid = data_sum / period
+            meansq = data_sq_sum / period
+            sqmean = mid * mid
+            diff = abs(meansq - sqmean)
+            stddev = sqrt(max(0, diff))
+
+            mid_array[i] = mid
+            top_array[i] = mid + devfactor * stddev
+            bot_array[i] = mid - devfactor * stddev
+
+
+# Bollinger Bands Percentage indicator
+class BollingerBandsPct(BollingerBands):
+    """
+    Extends the Bollinger Bands with a Percentage line
+    """
+
+    lines = ("pctb",)
+    plotlines = {"pctb": {"_name": "%B"}}  # display the line as %B on chart
+
+    def __init__(self):
+        """Initialize the Bollinger Bands %B indicator.
+
+        Extends Bollinger Bands with percentage calculation.
+        """
+        super().__init__()
+
+    def next(self):
+        """Calculate %B line for the current bar.
+
+        Formula: %B = (price - bot) / (top - bot)
+        """
+        super().next()
+        top = self.lines.top[0]
+        bot = self.lines.bot[0]
+        diff = top - bot
+        if diff != 0:
+            self.lines.pctb[0] = (self.data[0] - bot) / diff
+        else:
+            self.lines.pctb[0] = 0.0
+
+    def once(self, start, end):
+        """Calculate %B line in runonce mode."""
+        super().once(start, end)
+        darray = self.data.array
+        top_array = self.lines.top.array
+        bot_array = self.lines.bot.array
+        pctb_array = self.lines.pctb.array
+
+        while len(pctb_array) < end:
+            pctb_array.append(float("nan"))
+
+        for i in range(start, min(end, len(darray), len(top_array), len(bot_array))):
+            top = top_array[i] if i < len(top_array) else 0.0
+            bot = bot_array[i] if i < len(bot_array) else 0.0
+            data_val = darray[i] if i < len(darray) else 0.0
+
+            if (
+                isinstance(top, float)
+                and math.isnan(top)
+                or isinstance(bot, float)
+                and math.isnan(bot)
+            ):
+                pctb_array[i] = float("nan")
+            else:
+                diff = top - bot
+                if diff != 0:
+                    pctb_array[i] = (data_val - bot) / diff
+                else:
+                    pctb_array[i] = 0.0

backtrader/indicators/cci.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python
+"""CCI Indicator Module - Commodity Channel Index.
+
+This module provides the CCI (Commodity Channel Index) indicator
+introduced by Donald Lambert in 1980 for identifying cyclical trends.
+
+Classes:
+    CommodityChannelIndex: CCI indicator (alias: CCI).
+
+Example:
+    class MyStrategy(bt.Strategy):
+        def __init__(self):
+            self.cci = bt.indicators.CCI(self.data, period=20)
+
+        def next(self):
+            if self.cci[0] > 100:
+                self.sell()
+            elif self.cci[0] < -100:
+                self.buy()
+"""
+
+from . import DivByZero, Indicator, MeanDev, MovAv
+
+
+class CommodityChannelIndex(Indicator):
+    """
+    Introduced by Donald Lambert in 1980 to measure variations of the
+    "typical price" (see below) from its mean to identify extremes and
+    reversals
+
+    Formula:
+      - tp = typical_price = (high + low + close) / 3
+      - tpmean = MovingAverage(tp, period)
+      - deviation = tp - tpmean
+      - meandev = MeanDeviation(tp)
+      - cci = deviation / (meandeviation * factor)
+
+    See:
+      - https://en.wikipedia.org/wiki/Commodity_channel_index
+    """
+
+    alias = ("CCI",)
+
+    lines = ("cci",)
+
+    params = (
+        ("period", 20),
+        ("factor", 0.015),
+        ("movav", MovAv.Simple),
+        ("upperband", 100.0),
+        ("lowerband", -100.0),
+    )
+
+    def _plotlabel(self):
+        plabels = [self.p.period, self.p.factor]
+        plabels += [self.p.movav] * self.p.notdefault("movav")
+        return plabels
+
+    def _plotinit(self):
+        self.plotinfo.plotyhlines = [0.0, self.p.upperband, self.p.lowerband]
+
+    def __init__(self):
+        """Initialize the CCI indicator calculation.
+
+        Calculates:
+        1. Typical price: (high + low + close) / 3
+        2. Moving average of typical price
+        3. Deviation from the mean
+        4. Mean deviation
+        5. CCI = deviation / (factor * mean deviation)
+        """
+        # CRITICAL: Use line objects to match master branch behavior
+        # tp = typical price
+        tp = (self.data.high + self.data.low + self.data.close) / 3.0
+
+        # tpmean = SMA of tp
+        tpmean = self.p.movav(tp, period=self.p.period)
+
+        # dev = tp - tpmean
+        dev = tp - tpmean
+
+        # meandev = MeanDev using tp and tpmean as two data sources
+        # This matches master branch's behavior: SMA(|tp - tpmean|) where tpmean varies
+        meandev = MeanDev(tp, tpmean, period=self.p.period)
+
+        # A zero mean deviation makes CCI mathematically undefined. Preserve that
+        # state while avoiding a division-by-zero exception, rather than treating
+        # it as the neutral (and signal-bearing) value 0.0.
+        self.lines.cci = DivByZero(dev, self.p.factor * meandev, zero=float("nan"))

backtrader/indicators/channels_ext.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python
+"""Channel and volatility-band indicators migrated from functional tests."""
+
+from . import Indicator
+from .atr import ATR
+from .basicops import Highest, Lowest
+from .ema import EMA
+
+__all__ = [
+    "ChandelierExitIndicator",
+    "DonchianChannel",
+    "DonchianChannelWarmup",
+    "DonchianChannelIndicator",
+    "KeltnerChannelIndicator",
+]
+
+
+class DonchianChannel(Indicator):
+    """Donchian channel exposing both upper/lower and dch/dcl/dcm aliases."""
+
+    lines = ("upper", "lower", "dch", "dcl", "dcm")
+    params = {"period": 20}
+
+    def __init__(self):
+        """Compute the highest/lowest/median series and bind them to the five output lines."""
+        period = max(2, int(self.p.period))
+        upper = Highest(self.data.high, period=period)
+        lower = Lowest(self.data.low, period=period)
+        mid = (upper + lower) / 2
+        self.lines.upper = upper
+        self.lines.lower = lower
+        self.lines.dch = upper
+        self.lines.dcl = lower
+        self.lines.dcm = mid
+
+
+class DonchianChannelIndicator(DonchianChannel):
+    """Compatibility alias for Donchian channel tests."""
+
+
+class DonchianChannelWarmup(DonchianChannel):
+    """Donchian channel variant preserving historical extra warm-up behavior."""
+
+    def __init__(self):
+        """Inherit the parent's lines and re-declare the minimum period explicitly."""
+        super().__init__()
+        self.addminperiod(max(2, int(self.p.period)))
+
+
+class KeltnerChannelIndicator(Indicator):
+    """Keltner Channel using EMA middle line and ATR width."""
+
+    lines = ("mid", "top", "bot")
+    params = {"period": 20, "atr_mult": 2.0, "atr_period": 14}
+
+    def __init__(self):
+        """Compute the EMA midline and the ATR-scaled top/bot envelopes."""
+        self.l.mid = EMA(self.data.close, period=self.p.period)
+        atr = ATR(self.data, period=self.p.atr_period)
+        self.l.top = self.l.mid + self.p.atr_mult * atr
+        self.l.bot = self.l.mid - self.p.atr_mult * atr
+
+
+class ChandelierExitIndicator(Indicator):
+    """Chandelier Exit volatility-based trailing stop levels."""
+
+    lines = ("long", "short")
+    params = {"period": 22, "multip": 3}
+    plotinfo = {"subplot": False}
+
+    def __init__(self):
+        """Build the long/short Chandelier Exit stop levels.
+
+        The long stop is the highest high over the configured
+        ``period`` minus ``multip * ATR`` (a long trailing stop
+        that sits below recent highs by a volatility buffer). The
+        short stop mirrors that, sitting above the recent low.
+        """
+        highest = Highest(self.data.high, period=self.p.period)
+        lowest = Lowest(self.data.low, period=self.p.period)
+        atr = self.p.multip * ATR(self.data, period=self.p.period)
+        self.lines.long = highest - atr
+        self.lines.short = lowest + atr

backtrader/indicators/contrib/__init__.py

@@ -0,0 +1,228 @@
+#!/usr/bin/env python
+"""Contributed indicators migrated from functional strategy tests.
+
+These indicators are lower-commonality or strategy-specific indicators. They are
+re-exported from ``backtrader.indicators`` so users can access them as
+``bt.indicators.Xxx``.
+"""
+
+from importlib import import_module as _import_module
+
+_MODULES = (
+    "absolutely_no_lag_lwma",
+    "absolutely_no_lag_lwma_color",
+    "accumulation_distribution_line",
+    "adx_cross_hull_style_indicator",
+    "adxdmi",
+    "ai_acceleration_deceleration_oscillator",
+    "altr_trend_signal_v22",
+    "anchored_momentum_line",
+    "any_range_cld_tail_indicator",
+    "aroon_horn_sign_indicator",
+    "aroon_oscillator_sign_alert",
+    "arrows_curves_indicator",
+    "as_ctrend_indicator",
+    "asimmetric_stoch_nr_indicator",
+    "atr_normalize_histogram",
+    "average_change_candle",
+    "bb_squeeze_indicator",
+    "bezier_st_dev_indicator",
+    "binary_wave_indicator",
+    "blau_c_momentum_indicator",
+    "blau_cmi_indicator",
+    "blau_csi",
+    "blau_ergodic",
+    "blau_t_stoch_i",
+    "blau_ts_stochastic",
+    "blau_tvi",
+    "brain_trend2_indicator",
+    "brain_trend_signal_proxy",
+    "brake_parb_indicator",
+    "breakout_bars_trend_v2",
+    "bsi_indicator",
+    "bulls_bears_eyes",
+    "bulls_power",
+    "bw_wise_man1_signal",
+    "bykov_trend_indicator",
+    "candle_stop_color",
+    "candles_x_smoothed_indicator",
+    "candlesticks_bw",
+    "caudate_x_period_candle_color",
+    "cci_histogram_indicator",
+    "cci_woodies_indicator",
+    "center_of_gravity_candle_indicator",
+    "center_of_gravity_indicator",
+    "cg_oscillator",
+    "close_line_cci",
+    "close_price_fractals",
+    "color3rd_gen_xma_indicator",
+    "color_bb_candles_indicator",
+    "color_coppock_indicator",
+    "color_hma",
+    "color_j_variation_indicator",
+    "color_metro_de_marker_indicator",
+    "color_metro_stochastic_indicator",
+    "color_metro_wpr_indicator",
+    "color_schaff_de_marker_trend_cycle",
+    "color_schaff_trend_cycle_indicator",
+    "color_step_xccx_indicator",
+    "color_x2_ma",
+    "color_x_derivative",
+    "color_zerolag_de_marker",
+    "corrected_average_indicator",
+    "darvas_boxes_system",
+    "dema_range_channel_color",
+    "derivative_indicator",
+    "digital_ft01_indicator",
+    "digital_macd",
+    "donchian_channels_system",
+    "dots_indicator",
+    "ef_distance_indicator",
+    "ema_rsi_va",
+    "envelopes_jp_alonso",
+    "f2a_ao_indicator",
+    "fatl_filter",
+    "fibo_candles_indicator",
+    "fine_tuning_ma",
+    "fisher_org_v1",
+    "fisher_org_v1_sign",
+    "force_index_ema",
+    "force_index_ema_2",
+    "forecast_oscilator",
+    "fractal_amambk",
+    "frama_series",
+    "frasm_av2_indicator",
+    "go_indicator",
+    "hlr_indicator",
+    "hma",
+    "i4_drfv2",
+    "i4_drfv3",
+    "i_anch_mom_indicator",
+    "i_de_marker_sign_indicator",
+    "i_gap_indicator",
+    "i_stoch_komposter_indicator",
+    "i_trend_indicator",
+    "iamma_indicator",
+    "indexed_moving_average",
+    "instantaneous_trend_filter_indicator",
+    "inverse_reaction_indicator",
+    "irsi_sign_indicator",
+    "iwpr_sign_indicator",
+    "j_brain_trend1_sig_indicator",
+    "j_tpo_proxy",
+    "jma_slope_indicator",
+    "kalman_filter_indicator",
+    "kalman_filter_line",
+    "kama_indicator",
+    "karacatica_indicator",
+    "kdj_indicator",
+    "kwan_ccc_indicator",
+    "kwan_nrp_indicator",
+    "kwan_rdp_indicator",
+    "laguerre_adx_indicator",
+    "laguerre_filter_indicator",
+    "laguerre_plus_di_proxy",
+    "laguerre_roc_indicator",
+    "le_man_signal_indicator",
+    "linear_reg_slope_v2_indicator",
+    "loco_indicator",
+    "lrma_indicator",
+    "lsma_angle_indicator",
+    "ma_rounding_channel_indicator",
+    "macd2_indicator",
+    "macd_candle_indicator",
+    "malr_indicator",
+    "momentum_candle_sign_indicator",
+    "moving_average_fn_indicator",
+    "mt5_stochastic_close_close",
+    "muv_nor_diff_cloud_indicator",
+    "non_lag_dot_indicator",
+    "nrtr_extr_indicator",
+    "nrtr_indicator",
+    "p_channel_system",
+    "percent_envelope",
+    "percentage_crossover_channel",
+    "pivot_zig_zag_proxy",
+    "price_channel_stop_indicator",
+    "price_extreme_channel",
+    "qqe_cloud_indicator",
+    "ravi_indicator",
+    "raw_close_close_stochastic",
+    "rd_trend_trigger_indicator",
+    "renko_level",
+    "renko_line_break",
+    "rftl_indicator",
+    "rkd_indicator",
+    "roc2_vg_indicator",
+    "rsi_histogram_indicator",
+    "rsi_slowdown",
+    "rsioma_v2",
+    "rvi_histogram_indicator",
+    "safe_adx",
+    "shared_strategy_indicators",
+    "sidus_indicator",
+    "silver_trend_indicator",
+    "sliding_range_color",
+    "slow_stoch",
+    "smoothed_adx_indicator",
+    "smoothed_rsi",
+    "spearman_rank_correlation_histogram",
+    "stalin_indicator",
+    "starter_laguerre_filter",
+    "step_manrtr_indicator",
+    "stochastic_histogram_indicator",
+    "t3_alarm_indicator",
+    "t3_average",
+    "t3_indicator",
+    "the20s_v020_signal",
+    "three_candles_indicator",
+    "three_line_break_indicator",
+    "time_line",
+    "trading_channel_index_proxy",
+    "trend_arrows_indicator",
+    "trend_continuation_indicator",
+    "trend_intensity_index_proxy",
+    "trend_manager_indicator",
+    "tri_x_candle_indicator",
+    "trigger_line",
+    "triple_ema_rate",
+    "trvi_indicator",
+    "two_pb_ideal_xosma_indicator",
+    "ultra_absolutely_no_lag_lwma_color",
+    "ultra_wpr_indicator",
+    "up_down_candle_strength",
+    "vinin_i_trend_indicator",
+    "volume_weighted_ma_indicator",
+    "volume_weighted_ma_st_dev_indicator",
+    "vwap_close_indicator",
+    "vwma_candle",
+    "vwma_digit_system",
+    "wami",
+    "wprsi_signal_indicator",
+    "x_de_marker_histogram_vol_direct_indicator",
+    "x_fisher_indicator",
+    "xcci_histogram_vol_direct_indicator",
+    "xcci_histogram_vol_indicator",
+    "xma_ichimoku",
+    "xma_ishimoku_channel_indicator",
+    "xma_ishimoku_line",
+    "xma_range_bands_indicator",
+    "xmacd_indicator",
+    "xrsi_de_marker_histogram",
+    "xrsi_histogram_vol_direct_indicator",
+    "xrsi_histogram_vol_indicator",
+    "xrvi_indicator",
+    "zero_lag_macd",
+    "zig_zag_recent_pivot_signal",
+    "zpf_indicator",
+)
+
+__all__ = []
+
+for _module_name in _MODULES:
+    _module = _import_module(f"{__name__}.{_module_name}")
+    for _name in getattr(_module, "__all__", ()):  # pragma: no branch
+        globals()[_name] = getattr(_module, _name)
+        __all__.append(_name)
+
+del _import_module, _module_name, _module, _name

backtrader/indicators/contrib/absolutely_no_lag_lwma.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python
+"""Functional-test indicators migrated to contrib.
+
+Generated from a single functional strategy module to preserve file-local
+helper functions and constants without cross-test name collisions.
+"""
+
+from .. import (
+    Indicator,
+    WeightedMovingAverage,
+)
+
+__all__ = [
+    "AbsolutelyNoLagLwma",
+]
+
+
+class AbsolutelyNoLagLwma(Indicator):
+    """Compute a low-lag LWMA proxy based on nested weighted moving averages."""
+
+    lines = ("value",)
+    params = (("length", 7),)
+
+    def __init__(self):
+        """Create line value from weighted moving average and set minimum period."""
+        period = max(2, int(self.p.length))
+        self.lines.value = WeightedMovingAverage(self.data.close, period=period)
+        self.addminperiod(period + 2)

backtrader/indicators/contrib/absolutely_no_lag_lwma_color.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python
+"""Functional-test indicators migrated to contrib.
+
+Generated from a single functional strategy module to preserve file-local
+helper functions and constants without cross-test name collisions.
+"""
+
+from .. import (
+    Indicator,
+    WeightedMovingAverage,
+)
+
+__all__ = [
+    "AbsolutelyNoLagLwmaColor",
+]
+
+
+class AbsolutelyNoLagLwmaColor(Indicator):
+    """Indicator computing WMA-of-WMA (no-lag) upper/lower channels with color breakout signal."""
+
+    lines = ("color_idx", "upper", "lower")
+    params = (("length", 7),)
+
+    def __init__(self):
+        """Initialize double-WMA smoothing for high and low inputs."""
+        self.up_lwma_1 = WeightedMovingAverage(self.data.high, period=self.p.length)
+        self.up_lwma_2 = WeightedMovingAverage(self.up_lwma_1, period=self.p.length)
+        self.dn_lwma_1 = WeightedMovingAverage(self.data.low, period=self.p.length)
+        self.dn_lwma_2 = WeightedMovingAverage(self.dn_lwma_1, period=self.p.length)
+
+    def next(self):
+        """Set the color index based on close position relative to the no-lag WMA channel."""
+        upper = float(self.up_lwma_2[0])
+        lower = float(self.dn_lwma_2[0])
+        close = float(self.data.close[0])
+        open_ = float(self.data.open[0])
+        self.lines.upper[0] = upper
+        self.lines.lower[0] = lower
+        color = 4.0
+        if close > upper:
+            color = 3.0 if close >= open_ else 2.0
+        elif close < lower:
+            color = 0.0 if close <= open_ else 1.0
+        self.lines.color_idx[0] = color