add boillinger bands and fib retracements

Author: MDUYN

pyindicators/__init__.py

@@ -1,12 +1,17 @@
-from .indicators import sma, rsi, ema, wilders_rsi, adx, roc, cci, \
-    crossover, is_crossover, wma, macd, willr, is_crossunder, crossunder, \
-    is_lower_low_detected, is_divergence, bollinger_width, \
-    is_below, is_above, get_slope, has_any_higher_then_threshold, \
-    has_slope_above_threshold, has_any_lower_then_threshold, \
-    has_values_above_threshold, has_values_below_threshold, is_down_trend, \
-    is_up_trend, up_and_downtrends, detect_peaks, atr, bollinger_bands, \
-    bearish_divergence, bullish_divergence, stochastic_oscillator, \
-    bearish_divergence_multi_dataframe, bullish_divergence_multi_dataframe
+from .indicators import (
+    sma, rsi, ema, wilders_rsi, adx, roc, cci,
+    crossover, is_crossover, wma, macd, willr, is_crossunder, crossunder,
+    is_lower_low_detected, is_divergence, bollinger_width,
+    bollinger_overshoot, is_below, is_above, get_slope,
+    has_any_higher_then_threshold, has_slope_above_threshold,
+    has_any_lower_then_threshold, has_values_above_threshold,
+    has_values_below_threshold, is_down_trend,
+    is_up_trend, up_and_downtrends, detect_peaks, atr, bollinger_bands,
+    bearish_divergence, bullish_divergence, stochastic_oscillator,
+    bearish_divergence_multi_dataframe, bullish_divergence_multi_dataframe,
+    fibonacci_retracement, fibonacci_retracement_levels, fibonacci_extension,
+    moving_average_envelope, sma_envelope, ema_envelope
+)
 from .exceptions import PyIndicatorException
 from .date_range import DateRange
 
@@ -60,7 +65,14 @@ def get_version():
     'bullish_divergence_multi_dataframe',
     'bollinger_bands',
     'bollinger_width',
+    'bollinger_overshoot',
     'atr',
     'cci',
-    'roc'
+    'roc',
+    'fibonacci_retracement',
+    'fibonacci_retracement_levels',
+    'fibonacci_extension',
+    'moving_average_envelope',
+    'sma_envelope',
+    'ema_envelope'
 ]

pyindicators/indicators/__init__.py

@@ -20,9 +20,14 @@
     bullish_divergence_multi_dataframe
 from .stochastic_oscillator import stochastic_oscillator
 from .average_true_range import atr
-from .bollinger_bands import bollinger_bands, bollinger_width
+from .bollinger_bands import bollinger_bands, bollinger_width, \
+    bollinger_overshoot
 from .commodity_channel_index import cci
 from .rate_of_change import roc
+from .fibonacci_retracement import fibonacci_retracement, \
+    fibonacci_retracement_levels, fibonacci_extension
+from .moving_average_envelope import moving_average_envelope, \
+    sma_envelope, ema_envelope
 
 __all__ = [
     'sma',
@@ -60,6 +65,13 @@
     'atr',
     'bollinger_bands',
     'bollinger_width',
+    'bollinger_overshoot',
     'cci',
-    'roc'
+    'roc',
+    'fibonacci_retracement',
+    'fibonacci_retracement_levels',
+    'fibonacci_extension',
+    'moving_average_envelope',
+    'sma_envelope',
+    'ema_envelope'
 ]

pyindicators/indicators/bollinger_bands.py

@@ -46,6 +46,111 @@ def bollinger_bands(
         )
 
 
+def bollinger_overshoot(
+    data: Union[PdDataFrame, PlDataFrame],
+    source_column='Close',
+    period=20,
+    std_dev=2,
+    result_column='bollinger_overshoot'
+) -> Union[PdDataFrame, PlDataFrame]:
+    """
+    Calculate Bollinger Band overshoot percentage for a price series.
+
+    Measures how far the price has exceeded the upper or lower band,
+    expressed as a percentage of the half-band width (distance from
+    middle to upper/lower band).
+
+    Calculation:
+    - When price > upper band (bullish overshoot):
+        Overshoot % = ((Price - Upper Band) / (Upper Band - Middle Band)) × 100
+    - When price < lower band (bearish overshoot):
+        Overshoot % = ((Price - Lower Band) / (Middle Band - Lower Band)) × 100
+    - When price is within bands: 0%
+
+    Example interpretation:
+    - A 40% overshoot means the price is 40% of the band width beyond the band
+    - Positive values indicate overbought conditions (above upper band)
+    - Negative values indicate oversold conditions (below lower band)
+    - High overshoots (e.g., 40% for silver) indicate risk of mean reversion
+
+    Args:
+        data: pandas or polars DataFrame with price data
+        source_column: Column name containing the price data (default: 'Close')
+        period: Rolling window period for calculation (default: 20)
+        std_dev: Number of standard deviations for bands (default: 2)
+        result_column: Name for the result column
+            (default: 'bollinger_overshoot')
+
+    Returns:
+        DataFrame with added overshoot percentage column
+    """
+    # First calculate the bands
+    data = bollinger_bands(
+        data,
+        source_column=source_column,
+        period=period,
+        std_dev=std_dev,
+        middle_band_column_result_column='BB_middle_temp',
+        upper_band_column_result_column='BB_upper_temp',
+        lower_band_column_result_column='BB_lower_temp'
+    )
+
+    if isinstance(data, PdDataFrame):
+        import numpy as np
+
+        price = data[source_column]
+        upper = data['BB_upper_temp']
+        middle = data['BB_middle_temp']
+        lower = data['BB_lower_temp']
+
+        # Calculate half-band width (same for upper and
+        # lower with symmetric bands)
+        half_band_width = upper - middle
+
+        # Calculate overshoot
+        # Above upper band: positive overshoot
+        # Below lower band: negative overshoot
+        # Within bands: 0
+        overshoot = np.where(
+            price > upper,
+            ((price - upper) / half_band_width) * 100,
+            np.where(
+                price < lower,
+                ((price - lower) / half_band_width) * 100,
+                0.0
+            )
+        )
+
+        data[result_column] = overshoot
+
+        # Drop temporary columns
+        data = data.drop(
+            columns=['BB_middle_temp', 'BB_upper_temp', 'BB_lower_temp']
+        )
+        return data
+
+    elif isinstance(data, PlDataFrame):
+        half_band_width = pl.col('BB_upper_temp') - pl.col('BB_middle_temp')
+
+        overshoot = pl.when(pl.col(source_column) >
+                            pl.col('BB_upper_temp')).then(
+            ((pl.col(source_column) -
+              pl.col('BB_upper_temp')) / half_band_width) * 100
+        ).when(pl.col(source_column) < pl.col('BB_lower_temp')).then(
+            ((pl.col(source_column) -
+              pl.col('BB_lower_temp')) / half_band_width) * 100
+        ).otherwise(0.0)
+
+        return data.with_columns(
+            overshoot.alias(result_column)
+        ).drop(['BB_middle_temp', 'BB_upper_temp', 'BB_lower_temp'])
+
+    else:
+        raise PyIndicatorException(
+            "Input data must be a pandas or polars DataFrame."
+        )
+
+
 def bollinger_width(
     data: Union[PdDataFrame, PlDataFrame],
     source_column='Close',