Merge pull request #66 from xgboosted/feature-improve-indicator-docs

xgboosted · web-flow · commit 8c3852d997e5 · 2025-11-26T03:36:26.000+11:00
docs: Improve indicator documentation for clarity and completeness
diff --git a/pandas_ta_classic/candles/cdl_doji.py b/pandas_ta_classic/candles/cdl_doji.py
@@ -17,7 +17,7 @@ def cdl_doji(
     offset=None,
     **kwargs,
 ):
-    """Candle Type: Doji"""
+    """Indicator: Candle Type - Doji"""
     # Validate Arguments
     length = int(length) if length and length > 0 else 10
     factor = float(factor) if is_percent(factor) else 10
diff --git a/pandas_ta_classic/candles/cdl_inside.py b/pandas_ta_classic/candles/cdl_inside.py
@@ -5,7 +5,7 @@
 
 
 def cdl_inside(open_, high, low, close, asbool=False, offset=None, **kwargs):
-    """Candle Type: Inside Bar"""
+    """Indicator: Candle Type - Inside Bar"""
     # Validate arguments
     open_ = verify_series(open_)
     high = verify_series(high)
diff --git a/pandas_ta_classic/candles/cdl_pattern.py b/pandas_ta_classic/candles/cdl_pattern.py
@@ -84,7 +84,7 @@ def cdl_pattern(
     offset=None,
     **kwargs,
 ) -> DataFrame:
-    """Candle Pattern"""
+    """Indicator: Candle Pattern"""
     # Validate Arguments
     open_ = verify_series(open_)
     high = verify_series(high)
diff --git a/pandas_ta_classic/candles/cdl_z.py b/pandas_ta_classic/candles/cdl_z.py
@@ -8,7 +8,7 @@
 def cdl_z(
     open_, high, low, close, length=None, full=None, ddof=None, offset=None, **kwargs
 ):
-    """Candle Type: Z Score"""
+    """Indicator: Candle Type - Z Score"""
     # Validate Arguments
     length = int(length) if length and length > 0 else 30
     ddof = int(ddof) if ddof and ddof >= 0 and ddof < length else 1
diff --git a/pandas_ta_classic/candles/ha.py b/pandas_ta_classic/candles/ha.py
@@ -5,7 +5,7 @@
 
 
 def ha(open_, high, low, close, offset=None, **kwargs):
-    """Candle Type: Heikin Ashi"""
+    """Indicator: Candle Type - Heikin Ashi"""
     # Validate Arguments
     open_ = verify_series(open_)
     high = verify_series(high)
diff --git a/pandas_ta_classic/overlap/hl2.py b/pandas_ta_classic/overlap/hl2.py
@@ -22,3 +22,35 @@ def hl2(high, low, offset=None, **kwargs):
     hl2.category = "overlap"
 
     return hl2
+
+
+hl2.__doc__ = """HL2 (Median Price)
+
+HL2 calculates the median price, which is the average of the High and Low 
+prices for each period. This indicator is commonly used to represent the 
+mid-point of a period's price range and is often used in technical analysis 
+as a reference point for price action.
+
+Sources:
+    https://www.tradingview.com/support/solutions/43000502274-hl2/
+    https://www.investopedia.com/terms/m/median.asp
+    https://school.stockcharts.com/doku.php?id=chart_analysis:typical_price
+
+Calculation:
+    Default Inputs:
+        None (uses raw high and low prices)
+    
+    HL2 = (High + Low) / 2
+
+Args:
+    high (pd.Series): Series of 'high' prices
+    low (pd.Series): Series of 'low' prices
+    offset (int): How many periods to offset the result. Default: 0
+
+Kwargs:
+    fillna (value, optional): pd.DataFrame.fillna(value)
+    fill_method (value, optional): Type of fill method
+
+Returns:
+    pd.Series: New feature generated.
+"""
diff --git a/pandas_ta_classic/overlap/hlc3.py b/pandas_ta_classic/overlap/hlc3.py
@@ -30,3 +30,38 @@ def hlc3(high, low, close, talib=None, offset=None, **kwargs):
     hlc3.category = "overlap"
 
     return hlc3
+
+
+hlc3.__doc__ = """HLC3 (Typical Price)
+
+HLC3 calculates the typical price, which is the average of the High, Low, 
+and Close prices for each period. This indicator provides a simple measure 
+of the average price level during a period and is widely used in technical 
+analysis. It's also known as the TA-Lib TYPPRICE function.
+
+Sources:
+    https://www.tradingview.com/support/solutions/43000502273-hlc3/
+    https://school.stockcharts.com/doku.php?id=chart_analysis:typical_price
+    https://www.investopedia.com/terms/t/typicalprice.asp
+
+Calculation:
+    Default Inputs:
+        None (uses raw HLC prices)
+    
+    HLC3 = (High + Low + Close) / 3
+
+Args:
+    high (pd.Series): Series of 'high' prices
+    low (pd.Series): Series of 'low' prices
+    close (pd.Series): Series of 'close' prices
+    talib (bool): If TA Lib is installed and talib is True, Returns the TA Lib
+        version. Default: True
+    offset (int): How many periods to offset the result. Default: 0
+
+Kwargs:
+    fillna (value, optional): pd.DataFrame.fillna(value)
+    fill_method (value, optional): Type of fill method
+
+Returns:
+    pd.Series: New feature generated.
+"""
diff --git a/pandas_ta_classic/overlap/midpoint.py b/pandas_ta_classic/overlap/midpoint.py
@@ -53,3 +53,39 @@ def midpoint(close, length=None, talib=None, offset=None, **kwargs):
     midpoint.category = "overlap"
 
     return midpoint
+
+
+midpoint.__doc__ = """Midpoint Over Period (MIDPOINT)
+
+MIDPOINT calculates the midpoint between the highest and lowest values of 
+the close price over a specified period. This indicator helps identify the 
+center of the price range and can be used to detect potential support and 
+resistance levels.
+
+Sources:
+    https://www.tradingview.com/support/solutions/43000594683-midpoint/
+    https://ta-lib.org/function.html?name=MIDPOINT
+
+Calculation:
+    Default Inputs:
+        length=2
+    
+    LOWEST = MIN(close, length)
+    HIGHEST = MAX(close, length)
+    MIDPOINT = (LOWEST + HIGHEST) / 2
+
+Args:
+    close (pd.Series): Series of 'close's
+    length (int): Its period. Default: 2
+    talib (bool): If TA Lib is installed and talib is True, Returns the TA Lib
+        version. Default: True
+    offset (int): How many periods to offset the result. Default: 0
+
+Kwargs:
+    min_periods (int, optional): Minimum number of observations required. Default: length
+    fillna (value, optional): pd.DataFrame.fillna(value)
+    fill_method (value, optional): Type of fill method
+
+Returns:
+    pd.Series: New feature generated.
+"""
diff --git a/pandas_ta_classic/overlap/midprice.py b/pandas_ta_classic/overlap/midprice.py
@@ -55,3 +55,40 @@ def midprice(high, low, length=None, talib=None, offset=None, **kwargs):
     midprice.category = "overlap"
 
     return midprice
+
+
+midprice.__doc__ = """Midpoint Price Over Period (MIDPRICE)
+
+MIDPRICE calculates the midpoint between the highest high and lowest low 
+over a specified period. Similar to MIDPOINT but uses high and low prices 
+instead of close prices. This provides a measure of the center of the 
+price range and is useful for identifying equilibrium levels.
+
+Sources:
+    https://www.tradingview.com/support/solutions/43000594684-midprice/
+    https://ta-lib.org/function.html?name=MIDPRICE
+
+Calculation:
+    Default Inputs:
+        length=2
+    
+    LOWEST_LOW = MIN(low, length)
+    HIGHEST_HIGH = MAX(high, length)
+    MIDPRICE = (LOWEST_LOW + HIGHEST_HIGH) / 2
+
+Args:
+    high (pd.Series): Series of 'high's
+    low (pd.Series): Series of 'low's
+    length (int): Its period. Default: 2
+    talib (bool): If TA Lib is installed and talib is True, Returns the TA Lib
+        version. Default: True
+    offset (int): How many periods to offset the result. Default: 0
+
+Kwargs:
+    min_periods (int, optional): Minimum number of observations required. Default: length
+    fillna (value, optional): pd.DataFrame.fillna(value)
+    fill_method (value, optional): Type of fill method
+
+Returns:
+    pd.Series: New feature generated.
+"""
diff --git a/pandas_ta_classic/overlap/ohlc4.py b/pandas_ta_classic/overlap/ohlc4.py
@@ -24,3 +24,36 @@ def ohlc4(open_, high, low, close, offset=None, **kwargs):
     ohlc4.category = "overlap"
 
     return ohlc4
+
+
+ohlc4.__doc__ = """OHLC4 (Average of Open, High, Low, Close)
+
+OHLC4 calculates the average of the Open, High, Low, and Close prices for 
+each period. This simple average provides a balanced representation of price 
+action across the entire period, giving equal weight to all four OHLC values.
+It's commonly used as a smoother alternative to close prices alone.
+
+Sources:
+    https://www.tradingview.com/support/solutions/43000502001-ohlc4/
+    https://www.investopedia.com/terms/o/ohlc-chart.asp
+
+Calculation:
+    Default Inputs:
+        None (uses raw OHLC prices)
+    
+    OHLC4 = (Open + High + Low + Close) / 4
+
+Args:
+    open_ (pd.Series): Series of 'open' prices
+    high (pd.Series): Series of 'high' prices
+    low (pd.Series): Series of 'low' prices
+    close (pd.Series): Series of 'close' prices
+    offset (int): How many periods to offset the result. Default: 0
+
+Kwargs:
+    fillna (value, optional): pd.DataFrame.fillna(value)
+    fill_method (value, optional): Type of fill method
+
+Returns:
+    pd.Series: New feature generated.
+"""
diff --git a/pandas_ta_classic/trend/amat.py b/pandas_ta_classic/trend/amat.py
@@ -74,3 +74,39 @@ def amat(
     amatdf.category = "trend"
 
     return amatdf
+
+
+amat.__doc__ = """Archer Moving Averages Trends (AMAT)
+
+The Archer Moving Averages Trends indicator identifies trend direction by comparing
+fast and slow moving averages. It generates long and short run signals based on the
+relationship between the two moving averages over a lookback period.
+
+Sources:
+    https://www.tradingview.com/script/nhQe8QJ0-Archer-Moving-Averages-Trends/
+
+Calculation:
+    Default Inputs:
+        fast=8, slow=21, lookback=2, mamode="ema"
+    
+    FAST_MA = MA(close, fast, mamode)
+    SLOW_MA = MA(close, slow, mamode)
+    
+    AMAT_LR = LONG_RUN(FAST_MA, SLOW_MA, lookback)
+    AMAT_SR = SHORT_RUN(FAST_MA, SLOW_MA, lookback)
+
+Args:
+    close (pd.Series): Series of 'close's
+    fast (int): Fast MA period. Default: 8
+    slow (int): Slow MA period. Default: 21
+    lookback (int): Lookback period for trend detection. Default: 2
+    mamode (str): See ```help(ta.ma)```. Default: 'ema'
+    offset (int): How many periods to offset the result. Default: 0
+
+Kwargs:
+    fillna (value, optional): pd.DataFrame.fillna(value)
+    fill_method (value, optional): Type of fill method
+
+Returns:
+    pd.DataFrame: AMAT_LR and AMAT_SR columns.
+"""
diff --git a/pandas_ta_classic/trend/long_run.py b/pandas_ta_classic/trend/long_run.py
@@ -48,3 +48,35 @@ def long_run(fast, slow, length=None, offset=None, **kwargs):
     long_run.category = "trend"
 
     return long_run
+
+
+long_run.__doc__ = """Long Run
+
+Identifies potential long (bullish) trend conditions by detecting when the fast 
+moving average is increasing while the slow moving average is either decreasing 
+(potential bottom) or also increasing (confirmed uptrend).
+
+Sources:
+    Used in AMAT (Archer Moving Averages Trends) indicator
+
+Calculation:
+    Default Inputs:
+        length=2
+    
+    PB = INCREASING(fast, length) AND DECREASING(slow, length)  # Potential bottom
+    BI = INCREASING(fast, length) AND INCREASING(slow, length)  # Both increasing
+    LONG_RUN = PB OR BI
+
+Args:
+    fast (pd.Series): Fast moving average series
+    slow (pd.Series): Slow moving average series
+    length (int): Lookback period. Default: 2
+    offset (int): How many periods to offset the result. Default: 0
+
+Kwargs:
+    fillna (value, optional): pd.DataFrame.fillna(value)
+    fill_method (value, optional): Type of fill method
+
+Returns:
+    pd.Series: New feature generated (boolean).
+"""
diff --git a/pandas_ta_classic/trend/short_run.py b/pandas_ta_classic/trend/short_run.py
@@ -46,3 +46,35 @@ def short_run(fast, slow, length=None, offset=None, **kwargs):
     short_run.category = "trend"
 
     return short_run
+
+
+short_run.__doc__ = """Short Run
+
+Identifies potential short (bearish) trend conditions by detecting when the fast 
+moving average is decreasing while the slow moving average is either increasing 
+(potential top) or also decreasing (confirmed downtrend).
+
+Sources:
+    Used in AMAT (Archer Moving Averages Trends) indicator
+
+Calculation:
+    Default Inputs:
+        length=2
+    
+    PT = DECREASING(fast, length) AND INCREASING(slow, length)  # Potential top
+    BD = DECREASING(fast, length) AND DECREASING(slow, length)  # Both decreasing
+    SHORT_RUN = PT OR BD
+
+Args:
+    fast (pd.Series): Fast moving average series
+    slow (pd.Series): Slow moving average series
+    length (int): Lookback period. Default: 2
+    offset (int): How many periods to offset the result. Default: 0
+
+Kwargs:
+    fillna (value, optional): pd.DataFrame.fillna(value)
+    fill_method (value, optional): Type of fill method
+
+Returns:
+    pd.Series: New feature generated (boolean).
+"""
diff --git a/pandas_ta_classic/volume/aobv.py b/pandas_ta_classic/volume/aobv.py
@@ -129,3 +129,45 @@ def aobv(
     aobvdf.category = "volume"
 
     return aobvdf
+
+
+aobv.__doc__ = """Archer On Balance Volume (AOBV)
+
+Archer On Balance Volume enhances the traditional OBV indicator by applying moving
+averages and detecting long/short run trends. It provides multiple signals including
+OBV with min/max bounds, fast/slow moving averages of OBV, and trend direction signals.
+
+Sources:
+    Derived from OBV (On Balance Volume)
+    https://www.investopedia.com/terms/o/onbalancevolume.asp
+
+Calculation:
+    Default Inputs:
+        fast=4, slow=12, max_lookback=2, min_lookback=2, mamode="ema", run_length=2
+    
+    OBV = On Balance Volume(close, volume)
+    OBV_MIN = ROLLING_MIN(OBV, min_lookback)
+    OBV_MAX = ROLLING_MAX(OBV, max_lookback)
+    FAST_MA = MA(OBV, fast, mamode)
+    SLOW_MA = MA(OBV, slow, mamode)
+    AOBV_LR = LONG_RUN(FAST_MA, SLOW_MA, run_length)
+    AOBV_SR = SHORT_RUN(FAST_MA, SLOW_MA, run_length)
+
+Args:
+    close (pd.Series): Series of 'close's
+    volume (pd.Series): Series of 'volume's
+    fast (int): Fast MA period. Default: 4
+    slow (int): Slow MA period. Default: 12
+    max_lookback (int): Max lookback period. Default: 2
+    min_lookback (int): Min lookback period. Default: 2
+    mamode (str): See ```help(ta.ma)```. Default: 'ema'
+    offset (int): How many periods to offset the result. Default: 0
+
+Kwargs:
+    run_length (int, optional): Lookback for long/short run. Default: 2
+    fillna (value, optional): pd.DataFrame.fillna(value)
+    fill_method (value, optional): Type of fill method
+
+Returns:
+    pd.DataFrame: OBV, OBV_min, OBV_max, fast MA, slow MA, AOBV_LR, AOBV_SR columns.
+"""
