Kerbal_Sentiment

Library "kerbal_sentiment"
Kerbal Indicators Shared Library - Sentiment Analysis
This library provides functions for accessing and analyzing market sentiment indicators
including VIX and Put/Call ratios for contrarian signal generation.

getVIX()
  Get VIX (CBOE Volatility Index) close value
  Returns: VIX close price

vixPercentile(length)
  Calculate VIX percentile rank over lookback period
  Parameters:
    length (int): Lookback period for percentile calculation
  Returns: VIX percentile (0-100)

vixRegime(vix, lowThresh, highThresh, extremeThresh)
  Classify VIX regime based on thresholds
  Parameters:
    vix (float): VIX value to classify (use na for current)
    lowThresh (float): Low VIX threshold (complacent market)
    highThresh (float): High VIX threshold (fearful market)
    extremeThresh (float): Extreme fear threshold
  Returns: Regime: "COMPLACENT", "NORMAL", "FEARFUL", or "EXTREME_FEAR"

vixZScore(length)
  Calculate VIX z-score for relative positioning
  Parameters:
    length (int): Lookback period for mean and standard deviation
  Returns: VIX z-score

getPutCallRatio()
  Get equity put/call ratio
  Returns: Put/Call ratio (typically from CBOE data feed)

putCallSmoothed(length)
  Get smoothed put/call ratio using SMA
  Parameters:
    length (int): Smoothing period
  Returns: Smoothed put/call ratio

putCallZScore(length)
  Calculate put/call z-score for extremes detection
  Parameters:
    length (int): Lookback period for mean and standard deviation
  Returns: Put/Call z-score (positive = elevated put buying)

putCallRegime(pc, lowThresh, highThresh)
  Classify put/call ratio regime
  Parameters:
    pc (float): Put/call ratio (use na for current)
    lowThresh (float): Low P/C threshold (complacent/bullish)
    highThresh (float): High P/C threshold (fearful/bearish sentiment)
  Returns: Regime: "COMPLACENT", "NORMAL", "DEFENSIVE", "FEARFUL"

sentimentScore(vixPercentile, putCallZScore)
  Calculate composite sentiment score
  Parameters:
    vixPercentile (float): VIX percentile rank (0-100)
    putCallZScore (float): Put/Call ratio z-score
  Returns: Sentiment score 0-100 (0 = extreme fear/bullish contrarian, 100 = extreme complacency/bearish contrarian)

contrarianSignal(sentimentScore, bullishThreshold, bearishThreshold)
  Check if sentiment is at contrarian extreme
  Parameters:
    sentimentScore (float): Composite sentiment score (0-100)
    bullishThreshold (float): Threshold for contrarian bullish signal (extreme fear)
    bearishThreshold (float): Threshold for contrarian bearish signal (extreme complacency)
  Returns: Tuple [isContrarianBullish, isContrarianBearish]

sentimentTrend(sentimentScore, prevSentimentScore, threshold)
  Get sentiment direction and strength
  Parameters:
    sentimentScore (float): Current sentiment score
    prevSentimentScore (float): Previous sentiment score
    threshold (float)
  Returns: Tuple [direction, strength] where direction is "INCREASING_FEAR", "DECREASING_FEAR", "STABLE"

vixSpike(spikeThreshold)
  Detect VIX spike (sudden fear increase)
  Parameters:
    spikeThreshold (float): Z-score threshold for spike detection
  Returns: True if VIX is spiking

putCallSpike(spikeThreshold)
  Detect put/call spike (sudden defensive positioning)
  Parameters:
    spikeThreshold (float): Z-score threshold for spike detection
  Returns: True if P/C ratio is spiking

marketStress()
  Composite market stress indicator
  Returns: Stress level 0-100 (higher = more stress)

contrarianBuyOpportunity(minStress)
  Identify contrarian buy opportunity
  Parameters:
    minStress (float): Minimum stress level required
  Returns: True if contrarian buy opportunity detected

contrarianSellOpportunity(maxStress)
  Identify contrarian sell opportunity
  Parameters:
    maxStress (float): Maximum stress level (complacency)
  Returns: True if contrarian sell opportunity detected