Editing Component:Market State Analysis

= Component: Market State Analysis =

'''File:''' <code>market_state_analysis.py</code><br/>
'''Layer:''' 2<br/>
'''Lines:''' 941<br/>
'''Code:''' [https://github.com/stoic97/plus_ev_code_base/blob/rikk_mtf_backtest001/services/backtest/src/components/market_state_analysis.py View Source]

----

== Purpose ==

Answers the question: '''"What kind of market are we in right now?"'''

This component classifies the current market regime using 7 detection algorithms:
* Is this a '''railroad''' (strong one-sided move) or a '''creeper''' (grinding sideways)?
* Are we in the '''early''', '''middle''', or '''late''' phase of the trend?
* Is there '''institutional activity''' (accumulation, fighting, breakouts)?

----

== Trading Market Principle ==

'''"Trade the market that exists, not the one you wish existed."'''

* Railroad = strong conviction, ride the wave → aggressive entries allowed
* Creeper = grinding, no conviction → skip or reduce size
* Two-day trend confirms direction → same direction both days = high probability
* Institutional fight = big players battling → stay out until resolution
* MIDDLE phase is optimal → EARLY too risky, LATE trend exhausted

----

== Seven Detection Algorithms ==

=== Algorithm 1: Railroad Trend ===

Detects strong one-sided moves where market moves like a train on tracks.

<pre>
Input:  Last 5 bars (open, close)
Output: is_railroad (bool), consistency (float)

Logic:
  1. Count bullish bars (close > open)
  2. Count bearish bars (close < open)
  3. Count strong bars (body > 0.3% of price)

  consistency = max(bullish, bearish) / 5
  is_railroad = (consistency > 80%) AND (strong_bars >= 3)
</pre>

'''Example:''' 5 bars: [+1.2%, +0.8%, +0.5%, +0.9%, +0.6%] → 100% bullish, 4 strong bars → Railroad

=== Algorithm 2: Creeper Move ===

Detects slow grinding price action with no clear direction.

<pre>
Input:  Last 7 bars (high, low)
Output: is_creeper (bool), avg_range (float)

Logic:
  FOR each of last 7 bars:
      range = (high - low) / high

  avg_range = average of all ranges
  is_creeper = (avg_range < 0.5%)
</pre>

'''Note:''' Uses 1-HOUR data (not 5-minute) to avoid false positives.

=== Algorithm 3: Volatility ===

Calculates market volatility from price changes.

<pre>
Input:  Close values
Output: volatility (float)

Logic:
  changes = [|close[i] - close[i-1]| / close[i-1] for each bar]
  volatility = average(changes)

Classification:
  HIGH    = volatility > 1.0%
  NORMAL  = 0.3% to 1.0%
  LOW     = volatility < 0.3%
</pre>

=== Algorithm 4: Market State Classification ===

Combines signals into overall market state.

<pre>
Input:  is_railroad, is_creeper, trend_direction, volatility
Output: MarketState enum

Logic:
  IF railroad AND direction="up"    → TRENDING_UP
  IF railroad AND direction="down"  → TRENDING_DOWN
  IF creeper                        → CREEPER_MOVE
  IF volatility > 1%                → MOMENTUM_MOVE
  IF volatility < 0.3%              → NARROW_LOW_VOLUME
  ELSE                              → RANGE_BOUND
</pre>

=== Algorithm 5: Two-Day Trend ===

Checks if last 2 daily bars agree on direction.

<pre>
Input:  Daily OHLC (last 2 bars)
Output: has_two_day_trend (bool), direction (str)

Logic:
  day1_bullish = close[-2] > open[-2]  // Yesterday
  day2_bullish = close[-1] > open[-1]  // Today

  IF both bullish  → True, "up"
  IF both bearish  → True, "down"
  ELSE             → False, "mixed"
</pre>

=== Algorithm 6: Trend Phase ===

Determines if trend is EARLY, MIDDLE, or LATE.

<pre>
Input:  Close, MA21 (50+ bars history)
Output: TrendPhase enum

Logic:
  1. Find where price crossed MA21 (trend start)
  2. Count bars since crossover = trend_length

  IF trend_length < 10   → EARLY (trend just started, risky)
  IF trend_length > 40   → LATE (trend exhausted)
  ELSE                   → MIDDLE (optimal zone)
</pre>

=== Algorithm 7: Institutional Behavior ===

Detects signs of big player activity.

'''7a. Institutional Fight:'''
<pre>
High volume (>150% average) + Narrow range (<0.5%) = Fight in progress
</pre>

'''7b. Accumulation:'''
<pre>
High volume bars (2+) + Price stable (<0.2% movement) = Accumulation
</pre>

'''7c. Break of Structure (BOS):'''
<pre>
Close breaks above swing high (bullish BOS)
Close breaks below swing low (bearish BOS)
Requires confirmation bars to avoid fakeouts
</pre>

----

== Configuration ==

{| class="wikitable"
|-
! Parameter !! Value !! Algorithm !! Description
|-
| <code>railroad_threshold</code> || 0.80 || #1 || 80% bars same direction
|-
| <code>railroad_analysis_bars</code> || 5 || #1 || Bars to analyze
|-
| <code>strong_bar_threshold</code> || 0.003 || #1 || 0.3% = strong bar
|-
| <code>min_strong_bars_required</code> || 3 || #1 || Need 3+ strong bars
|-
| <code>creeper_range_threshold</code> || 0.005 || #2 || <0.5% avg range = creeper
|-
| <code>creeper_analysis_bars</code> || 7 || #2 || Bars to analyze
|-
| <code>high_volatility_threshold</code> || 0.010 || #3 || >1% = high volatility
|-
| <code>low_volatility_threshold</code> || 0.003 || #3 || <0.3% = low volatility
|-
| <code>early_phase_max_length</code> || 10 || #6 || <10 bars = EARLY
|-
| <code>late_phase_min_length</code> || 40 || #6 || >40 bars = LATE
|-
| <code>volume_fight_multiplier</code> || 1.50 || #7 || 150% avg = high volume
|-
| <code>bos_confirmation_bars</code> || 1 || #7c || Bars to confirm BOS
|}

----

== Output ==

'''MarketStateResult:'''
{| class="wikitable"
|-
! Field !! Type !! Description
|-
| <code>market_state</code> || Enum || TRENDING_UP, TRENDING_DOWN, CREEPER_MOVE, MOMENTUM_MOVE, NARROW_LOW_VOLUME, RANGE_BOUND
|-
| <code>trend_phase</code> || Enum || EARLY, MIDDLE, LATE, UNDETERMINED
|-
| <code>trend_direction</code> || str || "up", "down", "sideways"
|-
| <code>is_railroad_trend</code> || bool || Strong one-sided move detected
|-
| <code>is_creeper_move</code> || bool || Grinding sideways detected
|-
| <code>has_two_day_trend</code> || bool || Both days same direction
|-
| <code>volatility</code> || float || Calculated volatility
|-
| <code>institutional_fight_in_progress</code> || bool || Big players fighting
|-
| <code>accumulation_detected</code> || bool || Accumulation pattern
|-
| <code>bos_detected</code> || bool || Break of structure
|}

----

== How Setup Quality Uses This ==

[[Component:Setup_Quality_Detection|setup_quality_detection.py]] applies penalties based on market state:

{| class="wikitable"
|-
! Detection !! Impact
|-
| <code>is_creeper_move = True</code> || -50 penalty (major)
|-
| <code>has_two_day_trend = False</code> || -30 penalty
|-
| <code>trend_phase != MIDDLE</code> || -25 penalty
|-
| <code>is_railroad_trend = True</code> || +15 bonus
|-
| <code>institutional_fight = True</code> || 0.7x multiplier (30% reduction)
|}

----

== Dependencies ==

'''Input Data:'''
* 1-HOUR data for creeper/railroad detection
* DAILY data for two-day trend analysis
* 5-MIN data as fallback

'''Upstream:'''
* [[Component:Multi_Timeframe_Analysis|multi_timeframe_analysis.py]] - Provides MTF context

'''Downstream:'''
* [[Component:Setup_Quality_Detection|setup_quality_detection.py]] - Uses for scoring penalties/bonuses

----

== Quick Reference ==

{| class="wikitable"
|-
! Market State !! Trading Action
|-
| TRENDING_UP + Railroad || Aggressive LONG entries
|-
| TRENDING_DOWN + Railroad || Aggressive SHORT entries
|-
| CREEPER_MOVE || Skip or reduce size significantly
|-
| MOMENTUM_MOVE || Trade with caution, wide stops
|-
| NARROW_LOW_VOLUME || Skip, wait for breakout
|-
| RANGE_BOUND || Mean reversion strategies only
|-
| Institutional Fight || Stay out until resolution
|-
| EARLY phase || Risky, wait for confirmation
|-
| MIDDLE phase || Optimal entry zone
|-
| LATE phase || Trend exhausted, be cautious
|}