mirror of
https://github.com/mihakralj/QuanTAlib.git
synced 2026-08-19 02:58:05 +00:00
113 lines
5.6 KiB
Markdown
113 lines
5.6 KiB
Markdown
# HT_DCPERIOD: Ehlers Hilbert Transform Dominant Cycle Period
|
||
|
||
> *The Hilbert Transform extracts the dominant cycle period by converting price into an analytic signal and measuring its phase rate.*
|
||
|
||
| Property | Value |
|
||
| ---------------- | -------------------------------- |
|
||
| **Category** | Cycle |
|
||
| **Inputs** | Source (close) |
|
||
| **Parameters** | None |
|
||
| **Outputs** | Single series (HT_DCPERIOD) |
|
||
| **Output range** | Varies (see docs) |
|
||
| **Warmup** | `LOOKBACK` bars |
|
||
| **PineScript** | [ht_dcperiod.pine](ht_dcperiod.pine) |
|
||
|
||
- HT_DCPERIOD estimates the period of the dominant market cycle using Ehlers' Hilbert Transform cascade.
|
||
- No configurable parameters; computation is stateless per bar.
|
||
- Validated against TA-Lib, Skender, and Tulip reference implementations where available.
|
||
|
||
HT_DCPERIOD estimates the period of the dominant market cycle using Ehlers' Hilbert Transform cascade. The algorithm extracts In-Phase and Quadrature components from price, computes instantaneous phase via homodyne discrimination, and derives the period from the phase rate of change. Output is a continuously varying period (typically 6-50 bars) compatible with TA-Lib's `HT_DCPERIOD` function. The indicator enables dynamic tuning of other indicators to the market's actual rhythm rather than fixed-parameter assumptions.
|
||
|
||
## Historical Context
|
||
|
||
John Ehlers introduced the Hilbert Transform Dominant Cycle Period in *Rocket Science for Traders* (2001) to overcome the fundamental limitation of fixed-period technical indicators. Markets cycle at variable rates, yet traditional indicators like RSI-14 or SMA-20 assume constant periodicity. HT_DCPERIOD measures the actual cycle length present in price data, enabling adaptive parameter selection. The TA-Lib implementation codified specific Hilbert Transform coefficients ($A = 0.0962$, $B = 0.5769$) and smoothing algorithms that became the de facto standard. QuanTAlib matches the TA-Lib implementation within floating-point tolerance, including the 32-bar lookback convention.
|
||
|
||
## Architecture & Physics
|
||
|
||
### 1. WMA Price Smoothing
|
||
|
||
A 4-bar weighted moving average removes Nyquist-frequency noise:
|
||
|
||
$$SmoothPrice_t = \frac{4P_t + 3P_{t-1} + 2P_{t-2} + P_{t-3}}{10}$$
|
||
|
||
### 2. Hilbert Transform FIR
|
||
|
||
The discrete Hilbert approximation generates the detrender and quadrature components using coefficients $A = 0.0962$ and $B = 0.5769$. The detrender, $Q_1$, and Hilbert transforms of $I_1$ and $Q_1$ ($jI$, $jQ$) are all computed with the same 4-tap FIR structure.
|
||
|
||
### 3. Phasor Components
|
||
|
||
$$I_{2,t} = I_{1,t} - jQ_t, \qquad Q_{2,t} = Q_{1,t} + jI_t$$
|
||
|
||
Both smoothed with EMA ($\alpha = 0.2$).
|
||
|
||
### 4. Homodyne Period Extraction
|
||
|
||
$$Re_t = 0.2(I_{2,t} \cdot I_{2,t-1} + Q_{2,t} \cdot Q_{2,t-1}) + 0.8 \cdot Re_{t-1}$$
|
||
|
||
$$Im_t = 0.2(I_{2,t} \cdot Q_{2,t-1} - Q_{2,t} \cdot I_{2,t-1}) + 0.8 \cdot Im_{t-1}$$
|
||
|
||
$$Period_{raw} = \frac{2\pi}{\arctan(Im_t / Re_t)}$$
|
||
|
||
### 5. Period Smoothing
|
||
|
||
Clamped to $[6, 50]$ bars, then smoothed:
|
||
|
||
$$Period_t = 0.33 \cdot Period_{raw} + 0.67 \cdot Period_{t-1}$$
|
||
|
||
### 6. Complexity
|
||
|
||
$O(1)$ per bar. Fixed Hilbert cascade with circular buffers totaling approximately 1.2 KB per instance. Warmup: 32 bars (TA-Lib lookback).
|
||
|
||
## Mathematical Foundation
|
||
|
||
### Parameters
|
||
|
||
| Parameter | Description | Default | Constraint |
|
||
|-----------|-------------|---------|------------|
|
||
| (none) | No user-configurable parameters | | |
|
||
|
||
The period range [6, 50] and all smoothing constants are fixed by the TA-Lib specification.
|
||
|
||
### Output Interpretation
|
||
|
||
| Output | Meaning |
|
||
|--------|---------|
|
||
| `period` $\approx 6$-$15$ | Short-cycle market; fast oscillator settings appropriate |
|
||
| `period` $\approx 15$-$30$ | Medium-cycle; standard indicator periods work |
|
||
| `period` $\approx 30$-$50$ | Long-cycle or trending; period drifting toward upper bound suggests trend |
|
||
| Stable value | Regular cyclical market, ideal for oscillator-based strategies |
|
||
|
||
## Performance Profile
|
||
|
||
### Operation Count (Streaming Mode)
|
||
|
||
| Operation | Count per bar | Notes |
|
||
|-----------|--------------|-------|
|
||
| 4-bar WMA | ~5 | 3 MUL + 1 ADD + 1 MUL(×0.1) |
|
||
| Hilbert FIR (detrender) | ~7 | 4-tap FIR with period-adaptive coefficients |
|
||
| Hilbert FIR (Q1) | ~7 | Same structure applied to detrender buffer |
|
||
| Hilbert FIR (jI) | ~7 | Applied to I1 history buffer |
|
||
| Hilbert FIR (jQ) | ~7 | Applied to Q1 history buffer |
|
||
| Phasor EMA (I2, Q2) | ~8 | 2 SUB/ADD + 4 FMA |
|
||
| Homodyne mixing + EMA | ~12 | 4 MUL + 2 ADD/SUB + 2 FMA |
|
||
| ATAN | ~15 | `Math.Atan` transcendental |
|
||
| Period division (2π/θ) | ~2 | 1 DIV |
|
||
| Clamp + EMA smoothing | ~4 | 2 comparisons + 1 FMA |
|
||
| Buffer management | ~10 | 4 circular buffer writes + index arithmetic |
|
||
| **Total** | **~84** | **O(1) fixed; identical pipeline to HOMOD** |
|
||
|
||
### Batch Mode (SIMD Analysis)
|
||
|
||
| Aspect | Assessment |
|
||
|--------|------------|
|
||
| SIMD vectorizable | No: full Hilbert cascade is sequentially dependent IIR chain |
|
||
| Bottleneck | `Math.Atan` transcendental + 4 Hilbert FIR passes per bar |
|
||
| Parallelism | None: each bar's phasor depends on previous bar's EMA state |
|
||
| Memory | O(1): 4 circular buffers (7 elements each) + 6 scalar EMA states (~280 bytes) |
|
||
| Throughput | Moderate; ~3× slower than simple EMA; matches HOMOD performance |
|
||
|
||
## Resources
|
||
|
||
- **Ehlers, J.F.** *Rocket Science for Traders*. Wiley, 2001.
|
||
- **TA-Lib** `TA_HT_DCPERIOD()` reference implementation.
|
||
- **Ehlers, J.F.** *Cybernetic Analysis for Stocks and Futures*. Wiley, 2004. |