# Indicators Documentation

## Understanding Indicator Types

This documentation covers three main types of indicators used in the strategy combination system:

### Signal Indicators
**Purpose**: Generate precise entry/exit signals when specific market conditions are met
- **When to use**: For identifying high-probability trade entries and exits
- **Behavior**: Generate signals infrequently, only when patterns are detected
- **Examples**: RSI Divergence, MACD Cross, Chandelier Exit
- **Lookback Period Usage**: Determines how far back to analyze for pattern recognition (e.g., divergence detection over 5-10 candles)

### Trend Indicators
**Purpose**: Identify overall market direction and momentum
- **When to use**: For confirming market direction and avoiding counter-trend trades
- **Behavior**: Provide continuous trend assessment (Long/Short/Neutral) for each candlestick
- **Examples**: EMA Trend, Stochastic RSI Trend
- **Lookback Period Usage**: Sets the timeframe for trend calculation (e.g., 20-50 periods for reliable trend signals)

### Context Indicators
**Purpose**: Provide market context to prevent trades in unfavorable conditions
- **When to use**: For risk management and avoiding trades in poor market conditions
- **Behavior**: Act as filters with veto power - can block otherwise valid signals
- **Examples**: Volatility filters, market condition assessments
- **Lookback Period Usage**: Determines volatility measurement window for context assessment

## Using Lookback Periods for Different Scenarios

### Short-term Trading (Scalping/Day Trading)
- **Signal Indicators**: Lookback 3-5 periods - quick pattern recognition
- **Trend Indicators**: Lookback 10-20 periods - responsive to recent price action
- **Context Indicators**: Lookback 10-20 periods - capture short-term volatility spikes

### Medium-term Trading (Swing Trading)
- **Signal Indicators**: Lookback 5-10 periods - balanced pattern detection
- **Trend Indicators**: Lookback 20-50 periods - reliable trend identification
- **Context Indicators**: Lookback 20-30 periods - meaningful volatility assessment

### Long-term Trading (Position Trading)
- **Signal Indicators**: Lookback 10-15 periods - comprehensive pattern analysis
- **Trend Indicators**: Lookback 50-100 periods - stable trend confirmation
- **Context Indicators**: Lookback 30-50 periods - long-term volatility context

### High Volatility Markets
- **Signal Indicators**: Shorter lookback periods - avoid noise from extreme moves
- **Trend Indicators**: Standard periods - trends still need confirmation
- **Context Indicators**: Longer lookback periods - better volatility normalization

### Low Volatility Markets
- **Signal Indicators**: Longer lookback periods - capture subtle patterns
- **Trend Indicators**: Standard periods - maintain trend sensitivity
- **Context Indicators**: Shorter lookback periods - detect volatility contraction

## Indicator Categories

- **ChandelierExitIndicatorBase** - Chandelier Exit trailing stop indicator
- **DualEmaCrossIndicatorBase** - Dual EMA crossover signals
- **EmaCrossIndicator** - Exponential Moving Average crossover signals
- **EmaCrossIndicatorBase** - Base class for EMA cross indicators
- **LaggingSTC** - Lagging Schaff Trend Cycle indicator
- **MacdCrossIndicatorBase** - MACD crossover signals
- **RsiDivergenceConfirmIndicatorBase** - RSI divergence confirmation signals
- **RsiDivergenceIndicatorBase** - RSI divergence detection signals
- **StcIndicatorBase** - Schaff Trend Cycle indicator base
- **SuperTrendCrossEma** - SuperTrend with EMA crossover signals
- **SuperTrendIndicatorBase** - SuperTrend indicator base
- **ThreeWhiteSoldiersIndicatorBase** - Three White Soldiers candlestick pattern

### Trend Indicators
Trend indicators identify the direction and strength of market trends.

- **EmaTrendIndicatorBase** - Exponential Moving Average trend detection
- **StochRsiTrendIndicatorBase** - Stochastic RSI trend indicator

### Context Indicators
Context indicators provide market context and act as filters to prevent trades in unfavorable conditions. They work with confidence levels rather than simple allow/block decisions, providing veto power in the strategy combination system.

**Confidence Levels (Veto System):**
- **High Confidence**: Ideal market conditions (e.g., low volatility) - optimal for trading
- **Medium Confidence**: Normal market conditions - standard trading environment
- **Low Confidence**: Elevated risk conditions - trade with caution or reduced position size
- **None Confidence**: Poor conditions - blocks trading entirely

**Behavior in Strategy Combinations:**
- All context indicators must meet minimum confidence thresholds for trades to proceed
- Context indicators have veto power - they can block otherwise valid signals
- Used for risk management and market condition filtering

- **StDevContext** - Standard deviation context for volatility analysis using Z-score measurements


---

## RSI Divergence

**Type:** Signal

**Category:** RSI

**Description:**
Detects RSI divergence patterns where price and RSI move in opposite directions. This powerful reversal indicator identifies when momentum disagrees with price action, often signaling potential trend changes before they become obvious to other indicators.

**Trigger a Short when**
 • Previous candle close < current candle close (price going up)
 • Current RSI < maximum RSI in lookback period (RSI making lower high)
 • Current close > maximum price in lookback period (price making higher high)
 • Bearish divergence confirmed

**Trigger a Long when**
 • Previous candle close > current candle close (price going down)
 • Current RSI > minimum RSI in lookback period (RSI making higher low)
 • Current close < minimum price in lookback period (price making lower low)
 • Bullish divergence confirmed

**Parameters**
 • Period (recommended: 14) - RSI calculation period, typically 14 periods
 • Lookback Period (recommended: 5-10) - Number of candles to analyze for divergence patterns

---

## EMA Cross

**Type:** Signal

**Category:** EMA

**Description:**
Generates precise entry/exit signals when price crosses the Exponential Moving Average line. EMA gives more weight to recent prices, making it responsive to current market conditions while filtering out noise. Crossovers indicate momentum shifts and potential trend changes.

**Trigger a Short when**
 • Previous candle close > EMA value
 • Current candle close < EMA value
 • Price crosses from above to below EMA line

**Trigger a Long when**
 • Previous candle close < EMA value
 • Current candle close > EMA value
 • Price crosses from below to above EMA line

**Parameters**
 • Period (recommended: 20–50) - Number of periods for EMA calculation. Shorter periods (20-30) are more responsive but noisier, longer periods (40-50) are smoother but slower

---

## Dual EMA Cross

**Type:** Signal

**Category:** EMA

**Description:**
Uses two Exponential Moving Averages of different speeds to generate trend-following signals. The fast EMA responds quickly to price changes while the slow EMA provides trend confirmation, creating reliable crossover signals that identify major trend shifts.

**Trigger a Short when**
 • Previous candle fast EMA > slow EMA
 • Current candle fast EMA < slow EMA
 • Fast EMA crosses from above to below slow EMA

**Trigger a Long when**
 • Previous candle fast EMA < slow EMA
 • Current candle fast EMA > slow EMA
 • Fast EMA crosses from below to above slow EMA

**Parameters**
 • Fast Period (recommended: 9–12) - Short-term EMA for quick signals, typically 9-12 periods
 • Slow Period (recommended: 21–26) - Long-term EMA for trend confirmation, typically 21-26 periods

---

## MACD Cross

**Type:** Signal

**Category:** MACD

**Description:**
Generates signals when the MACD line crosses the signal line, indicating changes in momentum. MACD (Moving Average Convergence Divergence) combines trend-following and momentum oscillators to identify when buying/selling pressure shifts, often providing early signals of trend changes.

**Trigger a Short when**
 • Previous candle MACD > signal line
 • Current candle MACD < signal line
 • MACD line crosses from above to below signal line

**Trigger a Long when**
 • Previous candle MACD < signal line
 • Current candle MACD > signal line
 • MACD line crosses from below to above signal line

**Parameters**
 • Fast Period (recommended: 12) - Fast EMA period for MACD calculation, typically 12 periods
 • Slow Period (recommended: 26) - Slow EMA period for MACD calculation, typically 26 periods
 • Signal Period (recommended: 9) - EMA smoothing period for signal line, typically 9 periods

---

## SuperTrend

**Type:** Signal

**Category:** Trend Following

**Description:**
Uses ATR-based trailing stop levels to identify trend direction and generate signals. Combines volatility measurement with trend following to create dynamic support/resistance levels that adapt to market conditions, providing clear entry/exit points with built-in risk management.

**Trigger a Short when**
 • Current candle close < SuperTrend value
 • Price is below the SuperTrend trailing stop line

**Trigger a Long when**
 • Current candle close > SuperTrend value
 • Price is above the SuperTrend trailing stop line

**Parameters**
 • Period (recommended: 10–14) - ATR calculation period for volatility measurement, typically 10-14 periods
 • Multiplier (recommended: 2.0–3.0) - ATR multiplier for stop distance, higher values create wider stops

---

## Chandelier Exit

**Type:** Signal

**Category:** Volatility

**Description:** ATR-based trailing stop that adjusts based on recent volatility, using separate calculations for long and short positions

**Trigger a Short when →**
 • Current close < previous Chandelier exit level
 • Previous close > previous Chandelier exit level
 • Current close < previous candle open price
 • Using Short Chandelier type calculation

**Trigger a Long when →**
 • Current close > previous Chandelier exit level
 • Previous close < previous Chandelier exit level
 • Current close > current candle open price
 • Using Long Chandelier type calculation

**Parameters:**
- Period (recommended: 22) - ATR calculation period for volatility measurement
- Multiplier (recommended: 3.0) - ATR multiplier for trailing stop distance

---

## STC (Schaff Trend Cycle)

**Type:** Signal

**Category:** STC

**Description:**
Advanced cycle oscillator that combines MACD with Stochastic calculations to identify trend cycles. Oscillates between 0-100 with double-smoothing to reduce noise, providing clear overbought/oversold signals that often precede major trend changes in cyclic markets.

**Trigger a Short when**
 • Previous candle STC > 75
 • Current candle STC ≤ 75
 • STC crosses from above 75 to 75 or below

**Trigger a Long when**
 • Previous candle STC < 25
 • Current candle STC ≥ 25
 • STC crosses from below 25 to 25 or above

**Parameters**
 • Cycle Period (recommended: 10) - Primary cycle length for double-smoothing, typically 10 periods
 • Fast Period (recommended: 23) - Fast EMA period for MACD calculation, typically 23 periods
 • Slow Period (recommended: 50) - Slow EMA period for MACD calculation, typically 50 periods

---

## SuperTrend Cross EMA

**Type:** Signal

**Category:** EMA

**Description:** Combines SuperTrend with EMA crossover for enhanced trend confirmation

**Trigger a Short when →** SuperTrend confirms downtrend and price below EMA

**Trigger a Long when →** SuperTrend confirms uptrend and price above EMA

**Parameters:**
- SuperTrend Period (recommended: 10-14)
- SuperTrend Multiplier (recommended: 2.0-3.0)
- EMA Period (recommended: 20-50)

---

## Three White Soldiers

**Type:** Signal

**Category:** Candlestick

**Description:** Bullish reversal pattern consisting of three consecutive white candles

**Trigger a Short when →** N/A (bullish only pattern)

**Trigger a Long when →** Three consecutive higher closes forming white candles

**Parameters:**
- Lookback Period (recommended: 3-5 candles)



---

## RSI Divergence Confirm

**Type:** Signal

**Category:** RSI

**Description:** Detects RSI divergences and confirms them with additional price action validation for higher reliability

**Divergence Detection Process:**
1. **Identifies divergence**: Same logic as RSI Divergence - detects when price and RSI move in opposite directions
2. **Initial signal**: Creates low-confidence signal (Confidence.None) when divergence is spotted
3. **Confirmation phase**: Monitors subsequent price action to validate the divergence

**Confirmation Logic:**
 • **Long confirmation**: Divergence signal is confirmed when current close price breaks above the divergence signal's open price
 • **Short confirmation**: Divergence signal is confirmed when current close price breaks below the divergence signal's open price
 • When confirmed, generates High confidence signal and expires the original low-confidence signal

**Trigger a Short when →** Bearish divergence confirmed by price breaking below signal candle's open

**Trigger a Long when →** Bullish divergence confirmed by price breaking above signal candle's open

**Parameters:**
- RSI Period (recommended: 14) - RSI calculation period for divergence detection

---

## EMA Trend

**Type:** Trend

**Category:** EMA

**Description:**
Provides continuous trend context by comparing price position relative to Exponential Moving Average. Unlike crossover signals, this indicator gives ongoing trend direction information, useful for trend filtering and position management in trending markets.

**Trigger a Short when**
 • Current candle close < EMA value
 • Price is below the EMA line (bearish trend context)

**Trigger a Long when**
 • Current candle close > EMA value
 • Price is above the EMA line (bullish trend context)

**Parameters**
 • Period (recommended: 20–50) - EMA calculation period, longer periods provide more reliable trend signals
 • Slope Threshold (recommended: 0.1–0.5%) - Minimum EMA slope change to confirm trend strength

---

## Stochastic RSI Trend

**Type:** Trend

**Category:** RSI

**Description:**
Combines RSI momentum with Stochastic overbought/oversold levels for enhanced trend analysis. Applies Stochastic oscillator to RSI values instead of price, reducing false signals while providing clear trend context based on momentum extremes.

**Trigger a Short when**
 • Current candle Stochastic RSI signal > 80
 • Indicates overbought conditions (bearish trend context)

**Trigger a Long when**
 • Current candle Stochastic RSI signal < 20
 • Indicates oversold conditions (bullish trend context)

**Parameters**
 • RSI Period (recommended: 14) - RSI calculation period, typically 14 periods
 • Stochastic Period (recommended: 14) - Lookback period for Stochastic calculation, typically 14 periods
 • Signal Period (recommended: 3) - Smoothing period for signal line, typically 3 periods
 • Smooth Period (recommended: 3) - Additional smoothing period, typically 3 periods

---

## Standard Deviation Context

**Type:** Context

**Category:** Volatility

**Description:** Provides volatility context using standard deviation and Z-score analysis to assess market conditions and trading suitability

**Trigger a Short when →** N/A (context indicator - no directional signals)

**Trigger a Long when →** N/A (context indicator - no directional signals)

**Context Confidence Levels (Veto System):**
 • **High Confidence** (|Z-score| ≤ 0.5) - Very low volatility, ideal trading conditions
 • **Medium Confidence** (|Z-score| ≤ 1.0) - Normal volatility, good trading conditions
 • **Low Confidence** (|Z-score| ≤ 1.5) - Elevated volatility, use caution
 • **None Confidence** (|Z-score| > 1.5) - High volatility, trading not recommended

**Parameters:**
- Period (recommended: 20-50) - Standard deviation calculation period for volatility measurement

---

