QuanTAlib/lib/trends/htit/Htit.md

HTIT: Hilbert Transform Instantaneous Trend

"John Ehlers brought rocket science to trading. Literally. HTIT uses signal processing to find the trend by removing the cycle. It's not smoothing; it's extraction."

HTIT (Hilbert Transform Instantaneous Trend) is a trend-following indicator that doesn't rely on simple averaging. Instead, it uses the Hilbert Transform to measure the dominant cycle period of the market and then computes a trendline that filters out that specific cycle. It adapts to the market's rhythm rather than imposing a fixed period.

Historical Context

John Ehlers, a pioneer in applying DSP to trading, introduced this in his book Rocket Science for Traders. He recognized that markets have cyclic components (noise) and trend components. By identifying the cycle, you can mathematically subtract it to reveal the pure trend.

Most trend indicators (SMA, EMA) are low-pass filters: they let low frequencies (trend) pass and block high frequencies (noise). The problem is that "noise" in markets isn't random white noise; it's often cyclic. A fixed-period SMA might filter out a 10-day cycle perfectly but amplify a 20-day cycle. HTIT solves this by measuring the cycle first, then tuning the filter to kill exactly that frequency.

Architecture & Physics

This is a complex, multi-stage signal processing pipeline. It's not just a formula; it's a machine.

1. Smooth: 4-bar WMA to remove high-frequency noise (Nyquist limit).
2. Detrend: High-pass filter to remove the DC component (trend) temporarily to isolate the cycle.
3. Hilbert Transform: Compute In-Phase (I) and Quadrature (Q) components.
4. Period Measurement: Use the phase rate of change (Homodyne Discriminator) to measure the dominant cycle period.
5. Trend Extraction: Average the price over the measured dominant cycle period to cancel out the cycle.
6. Post-Smoothing: 4-bar WMA on the extracted trend for final polish.

The "physics" here is cancellation. If you average a sine wave over exactly one period, the result is zero. If you average Price (Trend + Cycle) over exactly one cycle period, the Cycle cancels out, leaving only the Trend.

Mathematical Foundation

1. Pre-Smoothing

A 4-tap FIR filter removes high-frequency noise to prevent aliasing before the Hilbert Transform.

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

2. Hilbert Transform & Detrending

The signal is detrended and split into In-Phase (I) and Quadrature (Q) components using a 7-tap Hilbert Transform. The coefficients are optimized for market cycles (10-40 bars).

\text{Adj} = 0.075 \cdot \text{Period}_{t-1} + 0.54 \text{Detrender}_t = \left( \frac{5}{52} S_t + \frac{15}{26} S_{t-2} - \frac{15}{26} S_{t-4} - \frac{5}{52} S_{t-6} \right) \cdot \text{Adj} Q_t = \left( \frac{5}{52} D_t + \frac{15}{26} D_{t-2} - \frac{15}{26} D_{t-4} - \frac{5}{52} D_{t-6} \right) \cdot \text{Adj} I_t = D_{t-3}

3. Homodyne Discriminator

The phase rate of change is calculated using the complex conjugate product of the current and previous phasors. This is the "Homodyne Discriminator" - a fancy radio term for "measuring frequency by comparing a signal to a delayed version of itself."

\text{Re}_t = (I2_t \cdot I2_{t-1}) + (Q2_t \cdot Q2_{t-1}) \text{Im}_t = (I2_t \cdot Q2_{t-1}) - (Q2_t \cdot I2_{t-1})

The period is derived from the phase angle of this complex product:

\text{Period}_t = \frac{2\pi}{\arctan\left(\frac{\text{Im}_t}{\text{Re}_t}\right)}

The period is constrained to [6, 50] bars and smoothed.

4. Instantaneous Trend

The trend is extracted by averaging the price over the measured dominant cycle period. This is the magic step.

\text{IT}_t = \frac{1}{\text{DC}} \sum_{i=0}^{\text{DC}-1} P_{t-i}

Where \text{DC} is the integer part of the smoothed dominant cycle period.

5. Final Output

The Instantaneous Trend is smoothed again using the same 4-bar WMA to remove any residual stepping artifacts from the integer period changes.

\text{HTIT}_t = \frac{4 \text{IT}_t + 3 \text{IT}_{t-1} + 2 \text{IT}_{t-2} + \text{IT}_{t-3}}{10}

Mathematical Precision & Implementation Philosophy

Like our MAMA implementation, QuanTAlib's HTIT prioritizes mathematical correctness over blind porting.

Aspect	Other Libraries	QuanTAlib	Rationale
Hilbert Coefficients	0.0962, 0.5769	5.0/52.0, 15.0/26.0	Exact fractions avoid rounding accumulation
Adjustment Slope	0.075	3.0/40.0	Preserves rational arithmetic precision
Adjustment Intercept	0.54	27.0/50.0	Ditto
Arctangent Function	atan(y/x)	atan2(y, x)	Proper quadrant handling, no division by zero
Period Calculation	360/atan(...)	2π/atan2(...)	Mathematically correct radians

We use atan2 for robust phase calculation and maintain full double precision throughout the pipeline.

Performance Profile

HTIT is computationally heavier than a simple MA but lighter than MAMA. The main cost is the loop for the Instantaneous Trend calculation, which sums up to 50 past prices.

Metric	Score	Notes
Throughput	~120 ns/bar	Variable cost due to dynamic loop length
Allocations	0	Stack-based circular buffers
Complexity	O(N)	Depends on cycle period (max 50 iterations)
Accuracy	9/10	Extracts trend by removing cycle
Timeliness	7/10	Adapts, but has inherent lag from the cycle period averaging
Overshoot	8/10	Generally good, stable trendline
Smoothness	9/10	Very smooth trendline due to double WMA

Validation

Validated against TA-Lib, Skender, and Ooples.

Library	Status	Notes
QuanTAlib	✅ Reference	Mathematically correct implementation.
TA-Lib	✅	Matches HtTrendline exactly (1e-9 precision).
Skender	⚠️	Matches GetHtTrendline (~0.32% diff).
Ooples	⚠️	Matches CalculateEhlersInstantaneousTrendlineV1 (~0.25% diff).

The differences with Skender and Ooples arise from:

1. Initialization: How the first few bars are handled.
2. Precision: Hardcoded decimals vs exact fractions.
3. Period Constraints: How strictly the [6, 50] bounds are enforced during intermediate steps.

Common Pitfalls

1. Warmup: This indicator needs significant warmup (at least 12 bars, ideally 50+) for the feedback loops (period smoothing) to stabilize. Don't trust the first 50 bars.
2. Lag: While it adapts, the trendline still lags because it's essentially a dynamic SMA. The advantage is that the period is optimal for the current market condition, not that it has zero lag.
3. Complexity: Debugging this is a nightmare. Trust the math.
4. Ranging Markets: In a pure range, the "trend" should be flat. HTIT handles this well because the cycle cancellation works best when the cycle is clear.