Skip to content

Cycle Indicators

Cycle indicators use the Hilbert Transform for advanced market cycle analysis. These indicators help identify dominant market cycles and their phases.

HT_DCPERIOD - Dominant Cycle Period

HT_DCPERIOD 

HT_DCPERIOD(close: Union[ndarray, list]) -> np.ndarray

Hilbert Transform - Dominant Cycle Period

This function uses the Hilbert Transform to identify the dominant cycle period in a price series. It analyzes market cycles and returns the period length of the dominant cycle.

Parameters

close : array-like Close prices array

Returns

np.ndarray Array of dominant cycle period values

Notes

  • Compatible with TA-Lib HT_DCPERIOD signature
  • Uses Numba JIT compilation for performance
  • The first 32 values will be NaN (unstable period)
  • Period values typically range from 6 to 50
  • Based on John Ehlers' work on MESA (Maximum Entropy Spectrum Analysis)

Interpretation: - Values represent the length in bars of the dominant cycle - Lower values indicate shorter, faster cycles - Higher values indicate longer, slower cycles - Use to adapt other indicators to current market conditions - Helps identify cycle changes and market regime shifts

Common Uses: - Adaptive indicator periods - Cycle-based trading systems - Market regime identification - Optimizing moving average periods

Examples

import numpy as np from numta import HT_DCPERIOD close = np.random.randn(100) + 100 period = HT_DCPERIOD(close) print(period)

See Also

HT_DCPHASE : Hilbert Transform - Dominant Cycle Phase HT_PHASOR : Hilbert Transform - Phasor Components HT_TRENDMODE : Hilbert Transform - Trend vs Cycle Mode

Source code in src/numta/api/cycle_indicators.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
def HT_DCPERIOD(close: Union[np.ndarray, list]) -> np.ndarray:
    """
    Hilbert Transform - Dominant Cycle Period

    This function uses the Hilbert Transform to identify the dominant cycle
    period in a price series. It analyzes market cycles and returns the
    period length of the dominant cycle.

    Parameters
    ----------
    close : array-like
        Close prices array

    Returns
    -------
    np.ndarray
        Array of dominant cycle period values

    Notes
    -----
    - Compatible with TA-Lib HT_DCPERIOD signature
    - Uses Numba JIT compilation for performance
    - The first 32 values will be NaN (unstable period)
    - Period values typically range from 6 to 50
    - Based on John Ehlers' work on MESA (Maximum Entropy Spectrum Analysis)

    Interpretation:
    - Values represent the length in bars of the dominant cycle
    - Lower values indicate shorter, faster cycles
    - Higher values indicate longer, slower cycles
    - Use to adapt other indicators to current market conditions
    - Helps identify cycle changes and market regime shifts

    Common Uses:
    - Adaptive indicator periods
    - Cycle-based trading systems
    - Market regime identification
    - Optimizing moving average periods

    Examples
    --------
    >>> import numpy as np
    >>> from numta import HT_DCPERIOD
    >>> close = np.random.randn(100) + 100
    >>> period = HT_DCPERIOD(close)
    >>> print(period)

    See Also
    --------
    HT_DCPHASE : Hilbert Transform - Dominant Cycle Phase
    HT_PHASOR : Hilbert Transform - Phasor Components
    HT_TRENDMODE : Hilbert Transform - Trend vs Cycle Mode
    """
    # Convert to numpy array if needed
    close = np.asarray(close, dtype=np.float64)

    n = len(close)
    if n == 0:
        return np.array([], dtype=np.float64)

    # Pre-allocate output array
    output = np.empty(n, dtype=np.float64)
    _ht_dcperiod_numba(close, output)

    return output

HT_DCPHASE - Dominant Cycle Phase

HT_DCPHASE 

HT_DCPHASE(close: Union[ndarray, list]) -> np.ndarray

Hilbert Transform - Dominant Cycle Phase

This function calculates the phase of the dominant cycle using the Hilbert Transform. The phase represents where in the cycle the market currently is, measured in degrees (0-360).

Parameters

close : array-like Close prices array

Returns

np.ndarray Array of dominant cycle phase values (in degrees)

Notes

  • Compatible with TA-Lib HT_DCPHASE signature
  • Uses Numba JIT compilation for performance
  • The first 32 values will be NaN (unstable period)
  • Phase values range from 0 to 360 degrees
  • Based on John Ehlers' MESA techniques

Interpretation: - 0-90 degrees: Early cycle, potential accumulation - 90-180 degrees: Mid cycle, trending phase - 180-270 degrees: Late cycle, potential distribution - 270-360 degrees: Cycle completion, reversal zone - Phase crossing 0/360: Cycle restart signal

Common Uses: - Cycle position identification - Timing entry/exit points - Predicting cycle turns - Confirming trend changes

Examples

import numpy as np from numta import HT_DCPHASE close = np.random.randn(100) + 100 phase = HT_DCPHASE(close) print(phase)

See Also

HT_DCPERIOD : Hilbert Transform - Dominant Cycle Period HT_PHASOR : Hilbert Transform - Phasor Components HT_SINE : Hilbert Transform - SineWave

Source code in src/numta/api/cycle_indicators.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
def HT_DCPHASE(close: Union[np.ndarray, list]) -> np.ndarray:
    """
    Hilbert Transform - Dominant Cycle Phase

    This function calculates the phase of the dominant cycle using the
    Hilbert Transform. The phase represents where in the cycle the market
    currently is, measured in degrees (0-360).

    Parameters
    ----------
    close : array-like
        Close prices array

    Returns
    -------
    np.ndarray
        Array of dominant cycle phase values (in degrees)

    Notes
    -----
    - Compatible with TA-Lib HT_DCPHASE signature
    - Uses Numba JIT compilation for performance
    - The first 32 values will be NaN (unstable period)
    - Phase values range from 0 to 360 degrees
    - Based on John Ehlers' MESA techniques

    Interpretation:
    - 0-90 degrees: Early cycle, potential accumulation
    - 90-180 degrees: Mid cycle, trending phase
    - 180-270 degrees: Late cycle, potential distribution
    - 270-360 degrees: Cycle completion, reversal zone
    - Phase crossing 0/360: Cycle restart signal

    Common Uses:
    - Cycle position identification
    - Timing entry/exit points
    - Predicting cycle turns
    - Confirming trend changes

    Examples
    --------
    >>> import numpy as np
    >>> from numta import HT_DCPHASE
    >>> close = np.random.randn(100) + 100
    >>> phase = HT_DCPHASE(close)
    >>> print(phase)

    See Also
    --------
    HT_DCPERIOD : Hilbert Transform - Dominant Cycle Period
    HT_PHASOR : Hilbert Transform - Phasor Components
    HT_SINE : Hilbert Transform - SineWave
    """
    # Convert to numpy array
    close = np.asarray(close, dtype=np.float64)

    n = len(close)
    if n == 0:
        return np.array([], dtype=np.float64)

    # Pre-allocate output
    output = np.empty(n, dtype=np.float64)
    _ht_dcphase_numba(close, output)

    return output

HT_PHASOR - Phasor Components

HT_PHASOR 

HT_PHASOR(close: Union[ndarray, list]) -> Tuple[np.ndarray, np.ndarray]

Hilbert Transform - Phasor Components

This function returns the InPhase and Quadrature components of the Hilbert Transform. These components form a phasor representation of the market cycle.

Parameters

close : array-like Close prices array

Returns

tuple of np.ndarray (inphase, quadrature) - Two arrays with the phasor components

Notes

  • Compatible with TA-Lib HT_PHASOR signature
  • Uses Numba JIT compilation for performance
  • The first 32 values will be NaN (unstable period)
  • Returns two arrays: InPhase and Quadrature
  • Based on John Ehlers' MESA analysis

Components: - InPhase: Real component of the phasor - Quadrature: Imaginary component of the phasor (90° phase shift) - Together they define the cycle's position and amplitude

Interpretation: - Magnitude = sqrt(InPhase² + Quadrature²) - Phase Angle = arctan(Quadrature / InPhase) - InPhase > 0, Quadrature > 0: First quadrant (0-90°) - InPhase < 0, Quadrature > 0: Second quadrant (90-180°) - InPhase < 0, Quadrature < 0: Third quadrant (180-270°) - InPhase > 0, Quadrature < 0: Fourth quadrant (270-360°)

Common Uses: - Advanced cycle analysis - Building custom cycle indicators - Phase and amplitude extraction - Cycle prediction algorithms - Component for other Hilbert Transform indicators

Examples

import numpy as np from numta import HT_PHASOR close = np.random.randn(100) + 100 inphase, quadrature = HT_PHASOR(close) magnitude = np.sqrt(inphase2 + quadrature2) phase = np.arctan2(quadrature, inphase) * 180 / np.pi

See Also

HT_DCPERIOD : Hilbert Transform - Dominant Cycle Period HT_DCPHASE : Hilbert Transform - Dominant Cycle Phase HT_SINE : Hilbert Transform - SineWave

Source code in src/numta/api/cycle_indicators.py 
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
def HT_PHASOR(close: Union[np.ndarray, list]) -> Tuple[np.ndarray, np.ndarray]:
    """
    Hilbert Transform - Phasor Components

    This function returns the InPhase and Quadrature components of the
    Hilbert Transform. These components form a phasor representation of
    the market cycle.

    Parameters
    ----------
    close : array-like
        Close prices array

    Returns
    -------
    tuple of np.ndarray
        (inphase, quadrature) - Two arrays with the phasor components

    Notes
    -----
    - Compatible with TA-Lib HT_PHASOR signature
    - Uses Numba JIT compilation for performance
    - The first 32 values will be NaN (unstable period)
    - Returns two arrays: InPhase and Quadrature
    - Based on John Ehlers' MESA analysis

    Components:
    - InPhase: Real component of the phasor
    - Quadrature: Imaginary component of the phasor (90° phase shift)
    - Together they define the cycle's position and amplitude

    Interpretation:
    - Magnitude = sqrt(InPhase² + Quadrature²)
    - Phase Angle = arctan(Quadrature / InPhase)
    - InPhase > 0, Quadrature > 0: First quadrant (0-90°)
    - InPhase < 0, Quadrature > 0: Second quadrant (90-180°)
    - InPhase < 0, Quadrature < 0: Third quadrant (180-270°)
    - InPhase > 0, Quadrature < 0: Fourth quadrant (270-360°)

    Common Uses:
    - Advanced cycle analysis
    - Building custom cycle indicators
    - Phase and amplitude extraction
    - Cycle prediction algorithms
    - Component for other Hilbert Transform indicators

    Examples
    --------
    >>> import numpy as np
    >>> from numta import HT_PHASOR
    >>> close = np.random.randn(100) + 100
    >>> inphase, quadrature = HT_PHASOR(close)
    >>> magnitude = np.sqrt(inphase**2 + quadrature**2)
    >>> phase = np.arctan2(quadrature, inphase) * 180 / np.pi

    See Also
    --------
    HT_DCPERIOD : Hilbert Transform - Dominant Cycle Period
    HT_DCPHASE : Hilbert Transform - Dominant Cycle Phase
    HT_SINE : Hilbert Transform - SineWave
    """
    # Convert to numpy array
    close = np.asarray(close, dtype=np.float64)

    n = len(close)
    if n == 0:
        empty = np.array([], dtype=np.float64)
        return empty, empty

    # Pre-allocate outputs
    inphase = np.empty(n, dtype=np.float64)
    quadrature = np.empty(n, dtype=np.float64)
    _ht_phasor_numba(close, inphase, quadrature)

    return inphase, quadrature

HT_SINE - SineWave

HT_SINE 

HT_SINE(close: Union[ndarray, list]) -> Tuple[np.ndarray, np.ndarray]

Hilbert Transform - SineWave

Source code in src/numta/api/cycle_indicators.py 
234
235
236
237
238
239
240
241
242
243
244
245
def HT_SINE(close: Union[np.ndarray, list]) -> Tuple[np.ndarray, np.ndarray]:
    """Hilbert Transform - SineWave"""
    close = np.asarray(close, dtype=np.float64)
    n = len(close)
    if n == 0:
        empty = np.array([], dtype=np.float64)
        return empty, empty

    sine = np.empty(n, dtype=np.float64)
    leadsine = np.empty(n, dtype=np.float64)
    _ht_sine_numba(close, sine, leadsine)
    return sine, leadsine

HT_TRENDLINE - Instantaneous Trendline

HT_TRENDLINE 

HT_TRENDLINE(close: Union[ndarray, list]) -> np.ndarray

Hilbert Transform - Instantaneous Trendline

Source code in src/numta/api/cycle_indicators.py 
248
249
250
251
252
253
254
255
256
257
def HT_TRENDLINE(close: Union[np.ndarray, list]) -> np.ndarray:
    """Hilbert Transform - Instantaneous Trendline"""
    close = np.asarray(close, dtype=np.float64)
    n = len(close)
    if n == 0:
        return np.array([], dtype=np.float64)

    output = np.empty(n, dtype=np.float64)
    _ht_trendline_numba(close, output)
    return output

HT_TRENDMODE - Trend vs Cycle Mode

HT_TRENDMODE 

HT_TRENDMODE(close: Union[ndarray, list]) -> np.ndarray

Hilbert Transform - Trend vs Cycle Mode

Source code in src/numta/api/cycle_indicators.py 
260
261
262
263
264
265
266
267
268
269
def HT_TRENDMODE(close: Union[np.ndarray, list]) -> np.ndarray:
    """Hilbert Transform - Trend vs Cycle Mode"""
    close = np.asarray(close, dtype=np.float64)
    n = len(close)
    if n == 0:
        return np.array([], dtype=np.float64)

    output = np.empty(n, dtype=np.float64)
    _ht_trendmode_numba(close, output)
    return output