Editing Component:Probability Zone

= Probability Zone Analysis =
== Purpose ==

'''"Where is price in the range & what are the odds of continuation?"'''

# 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%) → favor SHORT
* Three-finger spread = profit-taking imminent → avoid new positions
* Crash bar = structural break → short the bounce
* Sideways market = mean reversion → opposite logic applies

----

=== The Asymmetric Probability Edge ===

When odds are low on one outcome, '''the opposite side usually carries high odds''':
* If new high probability drops to 15%, then '''85% odds favor reversal'''
* We position ourselves on the high-probability side

== Probability Zones ==

Divide recent swing range into zones:

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

{| class="wikitable"
|-
! Zone !! Range Position !! Continuation Prob !! Trading Implication
|-
| Top Third || ≥ 66% || 80% || Strong LONG zone after pullback
|-
| Top Half || 50% - 66% || 65% || OK for LONG with confirmation
|-
| Bottom Half || 33% - 50% || 35% || Cautious LONG, watch for confirmation
|-
| Bottom Third || < 33% || 15% || Avoid LONG (85% chance of lower)
|}

----

== Three-Finger Spread ==

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

<pre>
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
</pre>

'''Detection Threshold:''' 2% minimum spread between each level

----

== Crash Bar Detection ==

Identifies structural breaks (crash bars):

<pre>
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
</pre>

----

== Pullback Classification ==

Classifies pullbacks as healthy or collapse:

{| class="wikitable"
|-
! 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 ===

<pre>
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 ✗
</pre>

=== Sideways/Creeper Market ===

Mean reversion logic (opposite of trending):

<pre>
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 ✗
</pre>

----

== Configuration ==

{| class="wikitable"
|-
! Parameter !! Value !! Description
|-
| <code>top_third_threshold</code> || 0.66 || Above 66% = top third
|-
| <code>bottom_third_threshold</code> || 0.33 || Below 33% = bottom third
|-
| <code>top_third_probability</code> || 0.80 || 80% continuation
|-
| <code>bottom_third_probability</code> || 0.15 || 15% continuation
|-
| <code>swing_lookback_bars</code> || 20 || Bars for swing detection
|-
| <code>three_finger_min_spread_pct</code> || 0.02 || 2% minimum spread
|-
| <code>crash_bar_multiplier</code> || 2.0 || Bar 2x average = crash
|-
| <code>crash_bar_close_threshold</code> || 0.30 || Close within 30% of extreme
|-
| <code>healthy_pullback_max_depth</code> || 0.50 || Max 50% for healthy
|-
| <code>collapse_min_depth</code> || 0.60 || Min 60% for collapse
|}

----

== Output ==

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

----

== Dependencies ==

'''Used By:'''
* [[Component:Signal_Generation|signal_generation_trade_management.py]] - Gate 4: Probability Zone Filter

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

----

== Quick Reference ==

{| class="wikitable"
|-
! 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
|}