Editing Component:Multi Timeframe Analysis

= Component: Multi-Timeframe Analysis =

'''File:''' <code>multi_timeframe_analysis.py</code><br/>
'''Layer:''' 1 (Foundation)<br/>
'''Lines:''' 708<br/>

----

== Purpose ==

Answers the question: '''"Are all timeframes pointing the same direction?"'''

Before entering a trade, we need confirmation that 1D, 4H, 1H, 15M, and 5M timeframes agree on direction. This component calculates a weighted alignment score and determines if we have sufficient confluence to trade.

----

== How It Works ==

=== Step 1: Analyze Each Timeframe ===

For each timeframe [1D, 4H, 1H, 15M, 5M]:
* Uses [[Component:Trend_Analysis_Core|TrendAnalysisCore]] to determine direction (up/down/sideways)
* Checks if price is above or below MA21
* Detects if MA is trending or flat

=== Step 2: Determine Expected Direction ===

The '''primary timeframe''' (default: 4H) sets the expected direction:
* 4H trending UP → expected direction = "up"
* 4H trending DOWN → expected direction = "down"

=== Step 3: Check Alignment ===

Each timeframe is marked as "aligned" if its direction matches the expected direction:
<pre>
aligned = (timeframe_direction == expected_direction)
</pre>

=== Step 4: Calculate Weighted Score ===

Higher timeframes get more weight (they're more reliable):

<pre>
Alignment_Score = Σ(Weight_i × Aligned_i) / Σ(Weight_i)

Where:
  Weight_i = hierarchical weight for timeframe i
  Aligned_i = 1 if aligned, 0 if not
</pre>

=== Step 5: 15-Minute Confirmation (Optional) ===

If enabled, checks that 70% of recent 15M bars confirm the direction:
<pre>
For LONG:  bullish_bars >= min_bars × 0.70
For SHORT: bearish_bars >= min_bars × 0.70
</pre>

=== Step 6: Final Decision ===

<pre>
is_aligned = (alignment_score >= min_alignment_score) AND (15m_confirmed)
</pre>

----

== Weight Formula ==

Default hierarchical weights using institutional formula:

<pre>
weight(i) = 1.0 - (i / N) × 0.7

Where:
  i = timeframe index (0-based)
  N = total timeframes (5)
  0.7 = scaling factor
</pre>

'''Calculated Weights:'''
{| class="wikitable"
|-
! Timeframe !! Index !! Calculation !! Weight
|-
| 1D || 0 || 1.0 - (0/5 × 0.7) || '''1.000'''
|-
| 4H || 1 || 1.0 - (1/5 × 0.7) || '''0.860'''
|-
| 1H || 2 || 1.0 - (2/5 × 0.7) || '''0.720'''
|-
| 15M || 3 || 1.0 - (3/5 × 0.7) || '''0.580'''
|-
| 5M || 4 || 1.0 - (4/5 × 0.7) || '''0.440'''
|}

----

== Example Calculation ==

'''Scenario:''' 1D, 4H, 1H aligned UP. 15M and 5M are DOWN.

<pre>
Expected direction: UP (from 4H)

Timeframe   Direction   Aligned   Weight   Contribution
─────────────────────────────────────────────────────────
1D          up          ✓         1.000    1.000
4H          up          ✓         0.860    0.860
1H          up          ✓         0.720    0.720
15M         down        ✗         0.580    0.000
5M          down        ✗         0.440    0.000
─────────────────────────────────────────────────────────
                        Total:    3.600    2.580

Alignment Score = 2.580 / 3.600 = 0.717 (71.7%)
</pre>

With min_alignment_score = 0.70, this PASSES (71.7% >= 70%).

----

== Configuration ==

{| class="wikitable"
|-
! Parameter !! Default !! Description
|-
| <code>min_alignment_score</code> || 0.70 || Minimum weighted score required (0-1)
|-
| <code>require_all_timeframes_aligned</code> || False || If True, ALL timeframes must align
|-
| <code>wait_for_15min_alignment</code> || True || Enable 15-minute confirmation
|-
| <code>min_15min_confirmation_bars</code> || 2 || Bars to check for 15M confirmation
|-
| <code>primary_ma_period</code> || 21 || Primary moving average period
|-
| <code>secondary_ma_period</code> || 200 || Secondary moving average period
|}

----

== Input ==

Dictionary of market data by timeframe:
<pre>
{
  TimeframeValue.DAILY: {
    "close": pd.Series,
    "open": pd.Series,
    "high": pd.Series,
    "low": pd.Series,
    "volume": pd.Series,
    "ma21": pd.Series,
    "ma200": pd.Series
  },
  TimeframeValue.FOUR_HOUR: { ... },
  TimeframeValue.ONE_HOUR: { ... },
  TimeframeValue.FIFTEEN_MIN: { ... },
  TimeframeValue.FIVE_MIN: { ... }
}
</pre>

----

== Output ==

'''TimeframeAnalysisResult:'''
{| class="wikitable"
|-
! Field !! Type !! Description
|-
| <code>aligned</code> || bool || Final alignment decision
|-
| <code>alignment_score</code> || float || Weighted score (0-1)
|-
| <code>primary_direction</code> || Direction || LONG or SHORT
|-
| <code>sufficient_alignment</code> || bool || Score >= threshold
|-
| <code>fifteen_min_aligned</code> || bool || 15M confirmation result
|-
| <code>timeframe_results</code> || Dict || Per-timeframe analysis details
|}

----

== Key Methods ==

=== process() ===
Main entry point. Called for each 5-minute bar.

=== _generate_default_weights() ===
Creates hierarchical weights using formula: <code>1.0 - (i/N × 0.7)</code>

=== _calculate_weighted_alignment() ===
Calculates: <code>Σ(Weight × Aligned) / Σ(Weight)</code>

=== _check_15min_alignment() ===
Checks if 70% of recent 15M bars confirm direction.

----

== Dependencies ==

'''Upstream:'''
* [[Component:Data_Manager|data_manager.py]] - Provides OHLC data per timeframe

'''Internal:'''
* [[Component:Trend_Analysis_Core|trend_analysis_core.py]] - Per-timeframe trend direction analysis

'''Downstream:'''
* [[Component:Market_State_Analysis|market_state_analysis.py]] - Receives alignment result
* [[Component:Setup_Quality_Detection|setup_quality_detection.py]] - Uses alignment score (30% weight)

----

== Trading Philosophy ==

This component implements the core principle: '''"Trade with the trend across multiple timeframes."'''

* Higher timeframes are more reliable → they get higher weights
* We need agreement, not perfection → 70% alignment is sufficient
* 15-minute confirmation prevents premature entries

----

[[Category:Components]]
[[Category:Layer 1]]