mirror of
https://github.com/mihakralj/QuanTAlib.git
synced 2026-08-06 04:57:44 +00:00
Miha Kralj
153 lines
7.3 KiB
Markdown
153 lines
7.3 KiB
Markdown
# 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](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 |