0
# Cycle Indicators
1

2
Hilbert Transform-based indicators for cycle analysis and trend vs cycle mode determination. These advanced indicators use mathematical transformations to identify market cycles, dominant periods, and phase relationships in price data.
3

4
## Capabilities
5

6
### Hilbert Transform - Dominant Cycle Period
7

8
Determines the dominant cycle period in the price data, helping identify the primary cyclical component.
9

10
```python { .api }
11
def HT_DCPERIOD(real):
12
    """
13
    Hilbert Transform - Dominant Cycle Period
14
    
15
    Identifies the dominant cycle period in price data using Hilbert Transform analysis.
16
    
17
    Parameters:
18
    - real: array-like, input price data (typically close prices)
19
    
20
    Returns:
21
    numpy.ndarray: Dominant cycle period values (in periods)
22
    """
23
```
24

25
### Hilbert Transform - Dominant Cycle Phase
26

27
Calculates the phase of the dominant cycle, indicating where the current price is within the cycle.
28

29
```python { .api }
30
def HT_DCPHASE(real):
31
    """
32
    Hilbert Transform - Dominant Cycle Phase
33
    
34
    Determines the phase angle of the dominant cycle (0 to 360 degrees).
35
    
36
    Parameters:
37
    - real: array-like, input price data
38
    
39
    Returns:
40
    numpy.ndarray: Dominant cycle phase values (degrees)
41
    """
42
```
43

44
### Hilbert Transform - Phasor Components
45

46
Provides the in-phase and quadrature components of the dominant cycle, representing the cycle as a rotating vector.
47

48
```python { .api }
49
def HT_PHASOR(real):
50
    """
51
    Hilbert Transform - Phasor Components
52
    
53
    Returns the in-phase and quadrature components of the dominant cycle.
54
    
55
    Parameters:
56
    - real: array-like, input price data
57
    
58
    Returns:
59
    tuple: (inphase, quadrature) - Phasor component values
60
    """
61
```
62

63
### Hilbert Transform - SineWave
64

65
Generates sine and lead sine waves based on the dominant cycle, useful for cycle timing and trend prediction.
66

67
```python { .api }
68
def HT_SINE(real):
69
    """
70
    Hilbert Transform - SineWave
71
    
72
    Generates sine and lead sine waves from the dominant cycle analysis.
73
    
74
    Parameters:
75
    - real: array-like, input price data
76
    
77
    Returns:
78
    tuple: (sine, leadsine) - Sine wave and lead sine wave values
79
    """
80
```
81

82
### Hilbert Transform - Trend vs Cycle Mode
83

84
Determines whether the market is in a trending mode or cycling mode, helping choose appropriate indicators and strategies.
85

86
```python { .api }
87
def HT_TRENDMODE(real):
88
    """
89
    Hilbert Transform - Trend vs Cycle Mode
90
    
91
    Identifies whether the market is trending or cycling.
92
    
93
    Parameters:
94
    - real: array-like, input price data
95
    
96
    Returns:
97
    tuple: (integer, trendmode) - Integer component and trend mode indicator arrays
98
    - integer: array of integer values (first component)
99
    - trendmode: array with 1 = trending, 0 = cycling (second component)
100
    """
101
```
102

103
## Usage Examples
104

105
```python
106
import talib
107
import numpy as np
108

109
# Sample price data (needs sufficient length for Hilbert Transform)
110
np.random.seed(42)
111
price_trend = np.linspace(100, 120, 100)
112
price_cycle = 5 * np.sin(np.linspace(0, 8*np.pi, 100))
113
price_data = price_trend + price_cycle + np.random.normal(0, 0.5, 100)
114

115
# Calculate Hilbert Transform indicators
116
dc_period = talib.HT_DCPERIOD(price_data)
117
dc_phase = talib.HT_DCPHASE(price_data)
118
inphase, quadrature = talib.HT_PHASOR(price_data)
119
sine, leadsine = talib.HT_SINE(price_data)
120
trendmode, _ = talib.HT_TRENDMODE(price_data)
121

122
# Analyze results
123
print(f"Dominant Cycle Period: {dc_period[-1]:.2f} periods")
124
print(f"Current Phase: {dc_phase[-1]:.1f} degrees")
125
print(f"Market Mode: {'Trending' if trendmode[-1] else 'Cycling'}")
126

127
# Trading applications:
128
# - Use sine/leadsine crossovers for cycle timing
129
# - Apply trend-following indicators when trendmode = 1
130
# - Apply oscillators when trendmode = 0
131
# - Use dominant cycle period to optimize indicator parameters
132

133
# Sine wave trading signals
134
if sine[-1] > leadsine[-1] and sine[-2] <= leadsine[-2]:
135
    print("Potential bullish cycle signal")
136
elif sine[-1] < leadsine[-1] and sine[-2] >= leadsine[-2]:
137
    print("Potential bearish cycle signal")
138
```
139

140
## Understanding Hilbert Transform Indicators
141

142
### Theory
143
The Hilbert Transform is a mathematical operation that creates a 90-degree phase shift in a signal, allowing for the analysis of instantaneous amplitude, phase, and frequency. In financial markets, this helps identify:
144

145
- **Cycle Components**: Separate trending from cyclical price movements
146
- **Phase Relationships**: Determine where price is within a cycle
147
- **Dominant Periods**: Identify the most significant cycle length
148

149
### Practical Applications
150

151
1. **Adaptive Indicators**: Use dominant cycle period to dynamically adjust indicator periods
152
2. **Market Mode Detection**: Switch between trend-following and mean-reversion strategies
153
3. **Cycle Timing**: Use phase information to time entries and exits
154
4. **Signal Filtering**: Apply different signal processing based on trend vs cycle mode
155

156
### Limitations
157

158
- Require substantial historical data (typically 50+ periods)
159
- May produce unstable results in choppy markets
160
- Best suited for markets with clear cyclical components
161
- Should be combined with other analysis methods for robust trading decisions