Component: Multi-Timeframe Analysis

File: multi_timeframe_analysis.py
Layer: 1 (Foundation)
Lines: 708

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 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:

aligned = (timeframe_direction == expected_direction)

Step 4: Calculate Weighted Score

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

Alignment_Score = Σ(Weight_i × Aligned_i) / Σ(Weight_i)

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

Step 5: 15-Minute Confirmation (Optional)

If enabled, checks that 70% of recent 15M bars confirm the direction:

For LONG:  bullish_bars >= min_bars × 0.70
For SHORT: bearish_bars >= min_bars × 0.70

Step 6: Final Decision

is_aligned = (alignment_score >= min_alignment_score) AND (15m_confirmed)

Weight Formula

Default hierarchical weights using institutional formula:

weight(i) = 1.0 - (i / N) × 0.7

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

Calculated Weights:

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.

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%)

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

Configuration

Parameter	Default	Description
`min_alignment_score`	0.70	Minimum weighted score required (0-1)
`require_all_timeframes_aligned`	False	If True, ALL timeframes must align
`wait_for_15min_alignment`	True	Enable 15-minute confirmation
`min_15min_confirmation_bars`	2	Bars to check for 15M confirmation
`primary_ma_period`	21	Primary moving average period
`secondary_ma_period`	200	Secondary moving average period

Input

Dictionary of market data by timeframe:

{
  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: { ... }
}

Output

TimeframeAnalysisResult:

Field	Type	Description
`aligned`	bool	Final alignment decision
`alignment_score`	float	Weighted score (0-1)
`primary_direction`	Direction	LONG or SHORT
`sufficient_alignment`	bool	Score >= threshold
`fifteen_min_aligned`	bool	15M confirmation result
`timeframe_results`	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: 1.0 - (i/N × 0.7)

_calculate_weighted_alignment()

Calculates: Σ(Weight × Aligned) / Σ(Weight)

_check_15min_alignment()

Checks if 70% of recent 15M bars confirm direction.

Dependencies

Upstream:

data_manager.py - Provides OHLC data per timeframe

Internal:

trend_analysis_core.py - Per-timeframe trend direction analysis

Downstream:

market_state_analysis.py - Receives alignment result
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