QuanTAlib/lib/dynamics/ht_trendmode/HtTrendmode.md

HT_TRENDMODE: Hilbert Transform Trend vs Cycle Mode

Hilbert trend mode classifies the market as trending or cycling — a binary answer from the analytic signal's behavior.

Property	Value
Category	Dynamic
Inputs	Source (close)
Parameters	None
Outputs	Single series (HT_TRENDMODE)
Output range	0 to 1
Warmup	LOOKBACK bars
PineScript	ht_trendmode.pine

• The Hilbert Transform Trend Mode indicator is a binary regime classifier that determines whether price action is dominated by trending behavior (ou...
• No configurable parameters; computation is stateless per bar.
• Validated against TA-Lib, Skender, and Tulip reference implementations where available.

The Hilbert Transform Trend Mode indicator is a binary regime classifier that determines whether price action is dominated by trending behavior (output = 1) or cyclical/mean-reverting behavior (output = 0). It uses the full Ehlers Hilbert Transform pipeline — 4-bar WMA smoothing, Hilbert FIR filters, homodyne discriminator for period estimation, DC phase extraction, and SineWave indicators — then applies four decision criteria to classify the current regime. The implementation follows TA-Lib's Ehlers-faithful algorithm from the February 2002 publication. Output is discrete {0, 1}, making it a direct strategy selector: deploy trend-following logic when mode = 1, and mean-reversion logic when mode = 0.

Historical Context

John Ehlers developed the Trend Mode indicator as part of his cycle analysis toolkit, published in "The Instantaneous Trendline" (February 2002) and expanded in MESA and Trading Market Cycles (2002). Ehlers recognized that traders face two fundamentally different market regimes requiring opposite strategies. Applying a trend-following system to a cycling market produces losses, and applying a mean-reversion system to a trending market produces losses. The Hilbert Transform provides the mathematical machinery to distinguish these states by analyzing the phase behavior of the dominant cycle. When phase advances at a regular rate (consistent with a sinusoidal cycle), the market is in cycle mode. When phase rate becomes irregular or price deviates significantly from its trendline, the market is trending. The four-criteria decision logic prevents rapid mode flipping during transitional periods by requiring sustained evidence before declaring a regime change.

Architecture & Physics

1. Hilbert Transform Core

The same pipeline as HT_DCPERIOD and HT_SINE:

\text{smooth} = \frac{4P_t + 3P_{t-1} + 2P_{t-2} + P_{t-3}}{10}

Hilbert FIR filters extract InPhase and Quadrature components, which feed the homodyne discriminator for period estimation:

Re = 0.2(I_2 \cdot I_{2,t-1} + Q_2 \cdot Q_{2,t-1}) + 0.8 \cdot Re_{t-1} Im = 0.2(I_2 \cdot Q_{2,t-1} - Q_2 \cdot I_{2,t-1}) + 0.8 \cdot Im_{t-1} \text{period} = \frac{360}{\arctan(Im/Re) \times \frac{180}{\pi}} \text{smoothPeriod} = 0.33 \times \text{period} + 0.67 \times \text{smoothPeriod}_{t-1}

2. DC Phase and SineWave

DFT accumulation over the dominant cycle period extracts the DC phase:

\text{dcPhase} = \arctan\!\left(\frac{\sum \sin(\omega i) \cdot \text{smooth}_i}{\sum \cos(\omega i) \cdot \text{smooth}_i}\right) + 90° + \text{lagComp} \text{sine} = \sin(\text{dcPhase}), \quad \text{leadSine} = \sin(\text{dcPhase} + 45°)

3. Trendline

An SMA over the dominant cycle period, further smoothed with a 4-bar WMA:

\text{sma} = \text{Average}(\text{price}, \lfloor\text{dcPeriod}\rfloor) \text{trendline} = \frac{4 \cdot \text{sma}_0 + 3 \cdot \text{sma}_1 + 2 \cdot \text{sma}_2 + \text{sma}_3}{10}

4. Four-Criteria Decision Logic

trend = 1  (assume trend by default)

Criterion 1: SineWave crossing resets counter
  if sine crosses leadSine → daysInTrend = 0, trend = 0

Criterion 2: Duration threshold
  daysInTrend++
  if daysInTrend < 0.5 × smoothPeriod → trend = 0

Criterion 3: Phase rate check
  phaseChange = dcPhase - prevDcPhase
  expected = 360 / smoothPeriod
  if 0.67 × expected < phaseChange < 1.5 × expected → trend = 0

Criterion 4: Price deviation override
  if |smoothPrice - trendline| / trendline ≥ 0.015 → trend = 1

5. Complexity

• Time: O(P) per bar for the SMA over dominant cycle period; Hilbert pipeline is O(1)
• Space: O(P_{\max}) — circular buffers for price history and Hilbert state (P_{\max} = 50)
• Warmup: 63 bars (TA-Lib compatible)

Mathematical Foundation

Parameters

No user-configurable parameters. The algorithm self-tunes based on the detected dominant cycle period (clamped to 6-50 bars).

Decision Criteria Summary

Criterion	Purpose
SineWave crossing	Resets trend counter — new cycle detected
Duration threshold	Requires sustained trending before declaration
Phase rate check	Normal phase advance indicates cycle mode
Price deviation	Large deviation from trendline forces trend mode

Mode Transition Patterns

Pattern	Interpretation
0→1 after breakout	Trend confirmed; deploy momentum strategy
1→0 at extremes	Cycle started; switch to mean-reversion
Long run of 1s	Strong, sustained trend
Rapid 0/1 flipping	Transitional/choppy — reduce exposure

Performance Profile

Operation Count (Streaming Mode)

HtTrendmode uses the Hilbert Transform DC Period estimation and compares it against a threshold to output binary trend/cycle mode.

Post-warmup steady state (per bar):

Operation	Count	Cost (cycles)	Subtotal
Hilbert FIR coefficients × 4 (InPhase, Quad)	8	3	24
Phase accumulator update (ATAN2 equivalent)	1	20	20
Period smoothing (EMA on period estimate)	2	4	8
Trend period threshold comparison	1	1	1
History buffer shifts × 4	4	1	4
Total	16	—	~57 cycles

The ATAN2-equivalent phase computation is the dominant cost. For default parameters: ~57 cycles per bar.

Batch Mode (SIMD Analysis)

Operation	Vectorizable?	Notes
Hilbert FIR (windowed taps)	Partial	Each tap independent; cross-bar state dependency limits
Period EMA smoothing	No	Recursive IIR — sequential
Threshold comparison	Yes	VCMPPD

The recursive EMA smoothing of the period estimate blocks full vectorization.

Quality Metrics

Metric	Score	Notes
Accuracy	7/10	Phase estimation inherent noise; binary output loses detail
Timeliness	6/10	Hilbert requires ~32 bar warmup for phase stabilization
Smoothness	10/10	Binary 0/1 output — maximally smooth
Noise Rejection	7/10	EMA-smoothed period estimate reduces mode-flip chatter

Resources

• Ehlers, J.F. — "The Instantaneous Trendline" (February 2002)
• Ehlers, J.F. — MESA and Trading Market Cycles (John Wiley & Sons, 2002)
• Ehlers, J.F. — Rocket Science for Traders (John Wiley & Sons, 2001)
• PineScript reference: ht_trendmode.pine in indicator directory