Kerbal_Breadth

Library "kerbal_breadth"
Kerbal Indicators Shared Library - Breadth Analysis
This library provides functions for analyzing market breadth indicators including
Advance/Decline lines, Bullish Percent Index, and breadth divergence detection.

getAdvDecLine()
  Get NYSE Advance/Decline line
  Returns: NYSE A/D line value

getAdvDecRatio()
  Get NYSE Advance/Decline ratio
  Returns: NYSE Advance/Decline ratio

advDecSlope(length)
  Calculate A/D line slope (rate of change)
  Parameters:
    length (int): Period for slope calculation
  Returns: A/D line slope (positive = breadth improving, negative = deteriorating)

advDecDivergence(priceHigh, priceHighBar, lookback)
  Detect A/D line divergence with price
  Parameters:
    priceHigh (float): Recent price high
    priceHighBar (int): Bar index of price high
    lookback (int): Bars to look back for divergence
  Returns: Tuple [bearishDiv, bullishDiv] - true if divergence detected

getBullishPercentNYSE()
  Get Bullish Percent Index for NYSE
  Returns: NYSE BPI value (0-100 scale)

getBullishPercentSPX()
  Get Bullish Percent Index for S&P 500
  Returns: SPX BPI value (0-100 scale)

getBullishPercentNDX()
  Get Bullish Percent Index for Nasdaq
  Returns: NDX BPI value (0-100 scale)

bpiRegime(bpi, oversoldThresh, overboughtThresh)
  Classify BPI regime
  Parameters:
    bpi (float): BPI value (0-100)
    oversoldThresh (float): Oversold threshold (contrarian bullish)
    overboughtThresh (float): Overbought threshold (contrarian bearish)
  Returns: Regime: "OVERSOLD", "BULLISH", "NEUTRAL", "BEARISH", "OVERBOUGHT"

pctAbove200MA_SPX()
  Get percentage of S&P 500 stocks above their 200-day MA
  Returns: Percentage (0-100)

pctAbove50MA_SPX()
  Get percentage of S&P 500 stocks above their 50-day MA
  Returns: Percentage (0-100)

breadthHealth(pct200, pct50)
  Analyze breadth health based on MA participation
  Parameters:
    pct200 (float): Percentage above 200-day MA
    pct50 (float): Percentage above 50-day MA
  Returns: Health assessment: "STRONG", "HEALTHY", "WEAK", "POOR"

breadthThrust(period, threshold)
  Detect breadth thrust (rapid improvement in breadth)
  Parameters:
    period (int): Measurement period
    threshold (float): Minimum improvement threshold
  Returns: True if breadth thrust detected

breadthScore(advDecSlope, bpi, pct200)
  Calculate composite breadth score
  Parameters:
    advDecSlope (float): A/D line slope
    bpi (float): Bullish Percent Index value
    pct200 (float): Percentage above 200-day MA
  Returns: Breadth score 0-100 (higher = better breadth)

currentBreadthScore()
  Get current composite breadth with all data retrieval
  Returns: Composite breadth score 0-100

breadthBearishDivergence(priceHigh, prevPriceHigh, currentBreadth, prevBreadth)
  Detect bearish breadth divergence
  Parameters:
    priceHigh (float): Current price high
    prevPriceHigh (float): Previous price high
    currentBreadth (float): Current breadth score
    prevBreadth (float): Previous breadth score
  Returns: True if bearish divergence (price up, breadth down)

breadthBullishDivergence(priceLow, prevPriceLow, currentBreadth, prevBreadth)
  Detect bullish breadth divergence
  Parameters:
    priceLow (float): Current price low
    prevPriceLow (float): Previous price low
    currentBreadth (float): Current breadth score
    prevBreadth (float): Previous breadth score
  Returns: True if bullish divergence (price down, breadth up)

breadthConfirmsBullish(breadthScore, minScore)
  Check if breadth confirms bullish price action
  Parameters:
    breadthScore (float): Current breadth score (0-100)
    minScore (float): Minimum acceptable breadth score
  Returns: True if breadth is confirming

breadthConfirmsBearish(breadthScore, maxScore)
  Check if breadth confirms bearish price action
  Parameters:
    breadthScore (float): Current breadth score (0-100)
    maxScore (float): Maximum acceptable breadth score
  Returns: True if breadth is confirming

breadthWarning(breadthScore, priceAction)
  Detect breadth warning signals
  Parameters:
    breadthScore (float): Current breadth score
    priceAction (int): Recent price direction (1 = up, -1 = down, 0 = neutral)
  Returns: Tuple [bearishWarning, bullishWarning]

marketHealthFromBreadth(breadthScore, hasThrust, divergenceType)
  Comprehensive market health from breadth indicators
  Parameters:
    breadthScore (float): Composite breadth score
    hasThrust (bool): Whether breadth thrust detected
    divergenceType (int): Divergence type: 1 = bearish, -1 = bullish, 0 = none
  Returns: Health string: "EXCELLENT", "GOOD", "FAIR", "POOR", "WARNING"

marketHealth(sentimentScore, breadthScore)
  Combined sentiment and breadth confirmation
  Parameters:
    sentimentScore (float): Sentiment score from kerbal_sentiment library (0-100)
    breadthScore (float): Breadth score (0-100)
  Returns: Tuple [overallHealth, contrarian Signal]