Component:Probability Zone

 ---
 = Component: Probability Zone Analysis =

 File: probability_zone_analysis.py

 Type: Support Component

 Lines: 947

 Branch: task/T26_probability_zone

 Code: View Source

 ----

 == Purpose ==

 Answers the question: "Where is price in the range, and what are the odds of continuation?"

 This component implements the probability zone concepts from trade_philosophy.pdf:
 # Divides price range into halves and thirds
 # Calculates continuation probability based on zone
 # Detects Three-Finger Spread (profit-taking pressure)
 # Identifies crash bars (structural breaks)
 # Filters signals based on zone probability

 ----

 == Trading Market Principle ==

 "Trade with the odds. Top third after pullback = 80% continuation. Bottom third = 15%."

 * Price in top third = high probability of new high (80%) → favor LONG
 * Price in bottom third = low probability of new high (15%) → avoid LONG
 * Three-finger spread = profit-taking imminent → avoid new positions
 * Crash bar = structural break → short the bounce
 * Sideways market = mean reversion → opposite logic applies

 ----

 == Probability Zones ==

 Divide recent swing range into zones:

      ┌───────────────────────────────────────┐ ← Swing High
      │                                       │
      │         TOP THIRD (80%)               │ ← 80% continuation probability
      │     (Above 66.7% of range)            │
      ├───────────────────────────────────────┤
      │                                       │
      │         TOP HALF (65%)                │ ← 65% continuation probability
      │     (50% - 66.7% of range)            │
      ├───────────────────────────────────────┤ ← 50% Line
      │                                       │
      │         BOTTOM HALF (35%)             │ ← 35% continuation probability
      │     (33.3% - 50% of range)            │
      ├───────────────────────────────────────┤
      │                                       │
      │         BOTTOM THIRD (15%)            │ ← Only 15% continuation (85% DOWN)
      │     (Below 33.3% of range)            │
      │                                       │
      └───────────────────────────────────────┘ ← Swing Low
  

Zone	Range Position	Continuation Prob	Trading Implication
Top Third	≥ 66.7%	80%	Strong LONG zone after pullback
Top Half	50% - 66.7%	65%	OK for LONG with confirmation
Bottom Half	33.3% - 50%	35%	Cautious LONG, watch for confirmation
Bottom Third	< 33.3%	15%	Avoid LONG (85% chance of lower)

 ----

 == Three-Finger Spread ==

 Detects large separation between Price, 21 MA, and 200 MA:

  BULLISH THREE-FINGER SPREAD:
      Price >> 21 MA >> 200 MA (large gaps)

      Interpretation:
      - Many traders with unrealized profits
      - Any red bar can trigger mass profit-taking
      - Creates fast, violent declines
      - AVOID LONGS in this condition

  BEARISH THREE-FINGER SPREAD:
      Price << 21 MA << 200 MA (large gaps)

      Interpretation:
      - Many traders with unrealized losses
      - Potential for short squeeze
      - AVOID SHORTS in this condition
  

 Detection Threshold: 2% minimum spread between each level

 ----

 == Crash Bar Detection ==

 Identifies structural breaks (crash bars):

  Crash Bar Criteria:
      1. Range ≥ 2× average range of prior 10 bars
      2. Close near extreme (within 30% of high/low)
      3. Fast, violent, elongated movement

  IF crash bar detected:
      - Block LONG signals
      - Allow SHORT signals with 1.5x strength

  Post-Crash (within 5 bars):
      - Bounce to top zone = prime SHORT entry
      - Block LONG signals
  

 ----

 == Pullback Classification ==

 Classifies pullbacks as healthy or collapse:

Type	Criteria	Trading Action
HEALTHY_PULLBACK	≤ 50% retracement, 45-degree drift	Good entry opportunity
COLLAPSE	≥ 60% retracement, vertical drop	Avoid buying the dip
BOUNCE	Between healthy and collapse	Short opportunity in downtrend
NO_PULLBACK	< 10% retracement	Price at highs, wait for pullback

 ----

 == Signal Filtering Logic ==

 === Trending Market ===

  UPTREND:
      Top Third:      LONG ✓ (80% odds), SHORT ✗
      Top Half:       LONG ✓ (65% odds), SHORT ✗
      Bottom Half:    LONG ⚠ (35% odds, reduced strength), SHORT ✗
      Bottom Third:   LONG ✗ (15% odds), SHORT ✓ (trend break signal)

  DOWNTREND:
      Bottom Third:   SHORT ✓, LONG ✗
      Top Third:      SHORT ✓ (bounce entry), LONG ✗
  

 === Sideways/Creeper Market ===

 Mean reversion logic (opposite of trending):

  SIDEWAYS:
      Top Third:      LONG needs confirmation, SHORT ✓
      Top Half:       LONG needs confirmation, SHORT ✓
      Bottom Half:    LONG needs confirmation, SHORT ✓
      Bottom Third:   LONG ✓ (85% reversal up), SHORT ✗
  

 ----

 == Configuration ==

Parameter	Value	Description
top_third_threshold	0.667	Above 66.7% = top third
bottom_third_threshold	0.333	Below 33.3% = bottom third
top_third_probability	0.80	80% continuation
bottom_third_probability	0.15	15% continuation
swing_lookback_bars	20	Bars for swing detection
three_finger_min_spread_pct	0.02	2% minimum spread
crash_bar_multiplier	2.0	Bar 2x average = crash
crash_bar_close_threshold	0.30	Close within 30% of extreme
healthy_pullback_max_depth	0.50	Max 50% for healthy
collapse_min_depth	0.60	Min 60% for collapse

 ----

 == Output ==

 ProbabilityZoneResult:

Field	Type	Description
zone	Enum	TOP_THIRD, TOP_HALF, BOTTOM_HALF, BOTTOM_THIRD
zone_position_pct	float	0-100, where in range
continuation_probability	float	0.15 - 0.80
swing_high	float	Recent swing high
swing_low	float	Recent swing low
has_three_finger_spread	bool	Large MA spread detected
ma_structure	Enum	UPTREND, DOWNTREND, SIDEWAYS, THREE_FINGER_*
pullback_type	Enum	HEALTHY, COLLAPSE, BOUNCE, NO_PULLBACK
is_crash_bar	bool	Crash bar detected
crash_bar_magnitude	float	How many times larger than average
allows_long	bool	Should LONG be allowed?
allows_short	bool	Should SHORT be allowed?
signal_strength_modifier	float	0.5 - 1.5 multiplier

 ----

 == Dependencies ==

 Used By:
 * signal_generation_trade_management.py - Gate 4: Probability Zone Filter

 Provides:
 * Zone classification for signal filtering
 * Continuation probability for strength adjustment

 ----

 == Quick Reference ==

Condition	LONG	SHORT	Reason
Top third, uptrend	✓ Strong	✗ Block	80% continuation
Bottom third, uptrend	✗ Block	✓ Allow	85% down probability
Three-finger spread (bull)	✗ Block	✓ Allow	Profit-taking imminent
Three-finger spread (bear)	✓ Allow	✗ Block	Potential reversal
Crash bar detected	✗ Block	✓ Strong	Structural break
Post-crash bounce to top	✗ Block	✓ Strong	Bounce short opportunity
Collapse detected	✗ Block	✓ Allow	Not healthy pullback
Sideways, top third	Needs confirm	✓ Allow	Mean reversion
Sideways, bottom third	✓ Strong	✗ Block	85% reversal up

 ----