QuanTAlib/lib/cycles/ht_dcphase/HtDcphase.md

HT_DCPHASE: Ehlers Hilbert Transform Dominant Cycle Phase

"The phase advances through a full 360-degree cycle as the dominant cycle completes; rapid phase changes indicate turning points."

HT_DCPHASE measures the instantaneous phase angle of the dominant market cycle using Ehlers' Hilbert Transform cascade. The output ranges from -45° to 315°, with phase discontinuities marking cycle completions. This indicator times entries/exits based on cycle position.

Historical Context

John Ehlers developed the Hilbert Transform cycle indicators in Rocket Science for Traders (2001). TA-Lib implements HT_DCPHASE directly from Ehlers' coefficients (A = 0.0962, B = 0.5769) with a 4-bar WMA prefilter and DC phase extraction from smoothed price history.

QuanTAlib matches TA-Lib HT_DCPHASE output within floating-point tolerance.

Architecture & Physics

The algorithm extracts phase from the complex analytic signal.

1. WMA Price Smoothing

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

2. Hilbert Transform Cascade

• Detrender (D): Removes DC component
• Quadrature (Q1): 90° phase-shifted version of D
• In-Phase (I1): D delayed by 3 bars
• jI, jQ: Hilbert transforms of I1, Q1

3. Phasor Components

I2_t = I1_t - jQ_t

Q2_t = Q1_t + jI_t

Smoothed with EMA (α = 0.2).

4. DC Phase Calculation

Via DFT-like accumulation over smoothed period:

DCPhase = \arctan\left(\frac{RealPart}{ImagPart}\right) \cdot \frac{180°}{\pi}

Wrapped to range [-45°, 315°].

Performance Profile

Operation Count (Streaming Mode, per Bar)

Operation	Count	Cost (cycles)	Subtotal
MUL (Hilbert + DFT)	45	3	135
SIN/COS (DFT loop)	100	15	1500
ADD/SUB	60	1	60
ATAN2	2	25	50
Total	~207	—	~1745 cycles

Complexity Analysis

• Streaming: O(P) per bar where P is smoothed period (~6-50)
• Memory: ~1.2 KB per instance
• Warmup: 63 bars (TA-Lib lookback)

Validation

Library	Status	Notes
TA-Lib	✅	Matches TALib.Functions.HtDcPhase()
Skender	N/A	Not implemented
PineScript	✅	Matches ht_dcphase.pine

Usage & Pitfalls

• Phase range is -45° to 315°—discontinuity at wrap is expected
• 63-bar warmup required—ignore early values
• Phase interpretation:
  • -45° to 45°: Bottom / Start of uptrend
  • 45° to 135°: Rising / Mid-uptrend
  • 135° to 225°: Top / Start of downtrend
  • 225° to 315°: Falling / Mid-downtrend
• Do not smooth across discontinuity—315° to -45° jump is cycle completion
• Strong trends cause phase to advance slowly or get stuck
• Rapid phase change often precedes price reversals

API

classDiagram
    class HtDcphase {
        +double Value
        +bool IsHot
        +HtDcphase()
        +HtDcphase(ITValuePublisher source)
        +TValue Update(TValue input, bool isNew)
        +void Reset()
    }

Class: HtDcphase

Parameter	Type	Default	Range	Description
(none)	—	—	—	No constructor parameters

Properties

• Value (double): DC phase in degrees (-45° to 315°)
• IsHot (bool): Returns true when warmup (63 bars) is complete

Methods

• Update(TValue input, bool isNew): Updates the indicator with a new data point

C# Example

using QuanTAlib;

// Create HT_DCPHASE
var htPhase = new HtDcphase();

// Update with streaming data
foreach (var bar in quotes)
{
    var result = htPhase.Update(new TValue(bar.Date, bar.Close));
    
    if (htPhase.IsHot)
    {
        double phase = result.Value;
        Console.WriteLine($"{bar.Date}: Phase = {phase:F1}°");
        
        // Cycle position detection
        if (phase >= -45 && phase < 45)
            Console.WriteLine("  → Cycle bottom zone");
        else if (phase >= 45 && phase < 135)
            Console.WriteLine("  → Rising phase");
        else if (phase >= 135 && phase < 225)
            Console.WriteLine("  → Cycle top zone");
        else
            Console.WriteLine("  → Falling phase");
    }
}

// Batch calculation
var output = HtDcphase.Calculate(sourceSeries);