Editing Component:Trend Analysis Core

= Trend Analysis Core =
== Purpose ==
'''"Is this timeframe trending or flattish[low odds of follow-through, moves are short-lived]"'''

For each timeframe, this component determines:
# '''Trend Direction''' - UP, DOWN, or SIDEWAYS
# '''MA Trending Status''' - Is 21 MA moving with conviction (45-degree) or flat?
# '''Price-MA Struggle''' - Is price stuck near MA, unable to break away?

----

== Trading Market Principle ==
  '''"Only trade when Market shows clear directional conviction."'''
  - 45-degree MA slope = healthy, tradeable trend → too steep or flattish = skip
  - MA21 slope tells us conviction → rising = bullish, declining = bearish, flat = no trade
  - Price stuck near MA = indecision → wait for clean break before entry
  - Direction needs both price position AND slope confirmation → one without the other is weak

== Three Core Algorithms ==

=== Algorithm 1: Trend Direction ===

Determines if timeframe is UP, DOWN, or SIDEWAYS.

<pre>
Input:  close, MA21, MA200, MA21_slope
Output: "up" | "down" | "sideways" | "unknown"

Logic:
  IF close > MA21 AND MA21_slope > +0.01%:
      return "up"

  ELIF close < MA21 AND MA21_slope < -0.01%:
      return "down"

  ELSE:
      // Fallback to MA stack
      IF MA21 > MA200: return "up"
      IF MA21 < MA200: return "down"
      return "sideways"
</pre>

=== Algorithm 2: MA Trending Status ===

Checks if MA21 has significant slope (45-degree angle).

<pre>
Input:  MA21 values (last 6 bars)
Output: True (trending) | False (flattish)

Formula:
  slope = (MA21_current - MA21_5_bars_ago) / MA21_5_bars_ago

  return |slope| > 0.05%
</pre>

'''Translation to trading language:'''
{| class="wikitable"
|-
! Slope !! Interpretation !! Trading Action
|-
| > +0.05% || Bullish 45-degree || Look for LONG entries
|-
| < -0.05% || Bearish 45-degree || Look for SHORT entries
|-
| -0.05% to +0.05% || Flattish/Sideways || WEAKEST Low odds of follow-through, moves are short-lived
|}

=== Algorithm 3: Price-MA Struggle ===

Detects when price is stuck near MA (indecision).

<pre>
Input:  close values, MA21 values (last 5 bars)
Output: True (struggling) | False (moving freely)

Logic:
  FOR each of last 5 bars:
      distance = |close - MA21| / MA21
      IF distance > 0.5%:
          return False  // Price broke away

  return True  // All bars within 0.5% = struggling
</pre>

'''Trading interpretation:'''
* <code>price_ma_struggle = True</code> → Price is "fighting" the MA, no clear direction
* <code>price_ma_struggle = False</code> → Price has conviction, clean trend

----

== Configuration ==

{| class="wikitable"
|-
! Parameter !! Value !! Description
|-
| <code>primary_ma_period</code> || 21 || Fast moving average (21 MA)
|-
| <code>secondary_ma_period</code> || 200 || Slow moving average (200 MA)
|-
| <code>bullish_slope_threshold</code> || 0.0001 || +0.01% = bullish direction
|-
| <code>bearish_slope_threshold</code> || -0.0001 || -0.01% = bearish direction
|-
| <code>ma_trending_min_slope</code> || 0.0005 || 0.05% = 45-degree threshold
|-
| <code>price_ma_struggle_threshold</code> || 0.005 || 0.5% = struggle zone
|-
| <code>min_bars_for_analysis</code> || 10 || Minimum bars needed
|-
| <code>min_bars_for_slope</code> || 6 || Bars for slope calculation
|}

----

== Output ==

'''TrendAnalysisResult:'''
{| class="wikitable"
|-
! Field !! Type !! Description
|-
| <code>trend_direction</code> || str || "up", "down", "sideways", "unknown"
|-
| <code>primary_ma_slope</code> || float || Actual slope value of MA21
|-
| <code>ma_trending_status</code> || bool || True = 45-degree, False = flattish
|-
| <code>price_ma_struggle</code> || bool || True = stuck near MA
|-
| <code>trend_confidence</code> || float || 0-1 confidence score
|-
| <code>trend_strength</code> || float || 0-1 strength score
|}

----

== Confidence Calculation ==

Confidence is weighted sum of three factors:

<pre>
Confidence = (slope_factor × 0.4) + (position_factor × 0.3) + (alignment_factor × 0.3)

Where:
  slope_factor    = min(|MA_slope| / 0.05%, 1.0)
  position_factor = min(|price - MA| / 0.5%, 1.0)
  alignment_factor = 1.0 if direction matches MA trending, else 0.5
</pre>

----

== How MTF Analysis Uses This ==

[[Component:Multi_Timeframe_Analysis|multi_timeframe_analysis.py]] calls this component for each timeframe:

<pre>
for timeframe in [1D, 4H, 1H, 15M, 5M]:
    result = trend_analysis_core._analyze_timeframe(data, timeframe)

    // Uses result.trend_direction for alignment check
    // Uses result.ma_trending_status for quality assessment
    // Uses result.price_ma_struggle for penalty detection
</pre>

----

== Example ==

'''Scenario:''' 5-minute bar with:
* Close = 5850
* MA21 = 5820 (30 points below close)
* MA21 5 bars ago = 5800

<pre>
Step 1: Calculate MA slope
  slope = (5820 - 5800) / 5800 = 0.00345 = 0.345%

Step 2: Determine trend direction
  close (5850) > MA21 (5820) ✓
  slope (0.345%) > bullish_threshold (0.01%) ✓
  → trend_direction = "up"

Step 3: Check MA trending
  |slope| (0.345%) > ma_trending_min (0.05%) ✓
  → ma_trending_status = True (45-degree angle)

Step 4: Check price-MA struggle
  distance = |5850 - 5820| / 5820 = 0.52%
  0.52% > 0.5% threshold
  → price_ma_struggle = False (price broke away cleanly)
</pre>

'''Result:''' Strong bullish trend with 45-degree MA, price moving with conviction.

----

== Key Methods ==

=== _analyze_timeframe() ===
Main entry point for single timeframe analysis. Calls all three algorithms.

=== _determine_trend_direction() ===
Algorithm 1: UP/DOWN/SIDEWAYS based on price vs MA21 and slope.

=== _check_ma_trending() ===
Algorithm 2: Is MA21 slope > 0.05%? (45-degree detection)

=== _check_price_ma_struggle() ===
Algorithm 3: Are all last 5 bars within 0.5% of MA21?

=== _calculate_ma_slope() ===
Helper: Calculates (MA_current - MA_5_bars_ago) / MA_5_bars_ago

----

== Dependencies ==

'''Used By:'''
* [[Component:Multi_Timeframe_Analysis|multi_timeframe_analysis.py]] - Calls this for each timeframe

'''Provides Data To:'''
* [[Component:Setup_Quality_Detection|setup_quality_detection.py]] - Uses <code>price_ma_struggle</code> for -30 penalty

----