gavindiaz/QuanTAlib
1
0
Fork 0
mirror of https://github.com/mihakralj/QuanTAlib.git synced 2026-08-22 04:28:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: Enhance volume indicators with ADOSC and SSF implementation and validation

Browse Source
This commit is contained in:
Miha Kralj
2025-12-20 15:08:07 -08:00
parent 5549c7329a
commit d21fea3c18
85 changed files with 5144 additions and 3954 deletions
Download Patch File Download Diff File Expand all files Collapse all files
lib/trends/htit/Htit.md
+40 -112
View File
@@ -1,140 +1,68 @@
# HTIT: Hilbert Transform Instantaneous Trend
## What It Does
> "John Ehlers brought rocket science to trading. Literally. HTIT uses signal processing to find the trend by removing the cycle. It's not smoothing; it's extraction."
The Hilbert Transform Instantaneous Trend (HTIT) is a sophisticated trend-following indicator that uses digital signal processing (DSP) techniques to filter out market cycles and isolate the underlying trend. Unlike traditional moving averages that use fixed periods, HTIT adapts to the dominant cycle period of the market, allowing it to track the "instantaneous" trend with minimal lag while maintaining smoothness.
HTIT (Hilbert Transform Instantaneous Trend) is a trend-following indicator that doesn't rely on simple averaging. Instead, it uses the Hilbert Transform to measure the dominant cycle period of the market and then computes a trendline that filters out that specific cycle. It adapts to the market's rhythm rather than imposing a fixed period.
## Historical Context
Developed by John Ehlers, a pioneer in applying DSP to technical analysis, the HTIT was introduced as part of his research into market cycles. Ehlers argued that financial markets are composed of a trend component and a cycle component. By accurately measuring the cycle using the Hilbert Transform, one can subtract it or filter it out to reveal the true trend, offering a more scientific approach than arbitrary moving averages.
John Ehlers, a pioneer in applying DSP to trading, introduced this in his book *Rocket Science for Traders*. He recognized that markets have cyclic components (noise) and trend components. By identifying the cycle, you can mathematically subtract it to reveal the pure trend.
## How It Works
## Architecture & Physics
### The Core Idea
This is a complex, multi-stage signal processing pipeline:
The indicator works by decomposing the price data into "In-Phase" and "Quadrature" components (like a complex number in electrical engineering). These components allow the calculation of the dominant cycle period (how long the current market wave is). Once the cycle period is known, the indicator computes a trendline that averages price over that specific period, effectively neutralizing the cycle's influence.
1. **Smooth**: 4-bar WMA to remove high-frequency noise.
2. **Detrend**: High-pass filter to remove the DC component (trend) temporarily to isolate the cycle.
3. **Hilbert Transform**: Compute In-Phase (I) and Quadrature (Q) components.
4. **Period Measurement**: Use the phase rate of change (Homodyne Discriminator) to measure the dominant cycle period.
5. **Trend Extraction**: Average the price over the measured dominant cycle period to cancel out the cycle.
### Mathematical Foundation
### Zero-Allocation Design
The process involves several DSP steps:
Despite the complexity, we maintain zero allocations.
1. **Smoothing:** A 4-bar Weighted Moving Average (WMA) removes high-frequency noise.
2. **Detrending:** A high-pass filter removes the static trend to isolate the oscillating component.
3. **Hilbert Transform:** Generates In-Phase ($I$) and Quadrature ($Q$) components to measure phase.
4. **Period Measurement:** A Homodyne Discriminator uses the phase rate of change to calculate the Dominant Cycle ($DC$) period.
5. **Instantaneous Trend:** The price is averaged over the calculated $DC$ period (or a smoothed version of it).
- **RingBuffers**: We use multiple small `RingBuffer`s for the various stages (smooth, detrend, I/Q, period).
- **State Struct**: Complex state (phasors, periods) is managed in a value type.
- **Fixed Buffers**: The pipeline depth is constant, allowing for static buffer sizing.
$$ IT[i] = \frac{1}{DC} \sum_{k=0}^{DC-1} Price[i-k] $$
## Mathematical Foundation
### Implementation Details
The core idea is that if you average a sine wave over exactly one period, the result is 0.
Our implementation follows Ehlers' original code structure but optimized for C#.
$$ \text{Trend}_t = \frac{1}{\text{DC}} \sum_{i=0}^{\text{DC}-1} P_{t-i} $$
- **Complexity:** O(1) per update (constant time DSP operations).
- **Adaptivity:** The lookback period for the final average changes dynamically with every bar.
- **Smoothing:** The final trendline undergoes additional 4-bar smoothing to remove jaggedness caused by period switching.
Where $\text{DC}$ is the measured Dominant Cycle period.
## Configuration
The Hilbert Transform is used to find $\text{DC}$ dynamically:
| Parameter | Default | Purpose | Adjustment Guidelines |
|-----------|---------|---------|----------------------|
| None | N/A | Fully adaptive | HTIT does not require user parameters; it measures the market directly. |
$$ \text{Phase} = \arctan(Q / I) $$
**Configuration note:** The lack of parameters is a feature, not a bug. It prevents "curve fitting" and ensures the indicator relies on measured market properties rather than user guesses.
$$ \text{DC} = \frac{2\pi}{\Delta \text{Phase}} $$
## Performance Profile
| Operation | Complexity | Description |
|-----------|------------|-------------------|
| Streaming update | O(1) | Fixed set of DSP equations per bar |
| Bar correction | O(1) | Efficient state rollback |
| Batch processing | O(N) | Single pass through data |
| Memory footprint | O(1) | Fixed size buffers for delay lines (approx 50 bars) |
This is an $O(1)$ algorithm, but the constant factor is large due to the many steps.
## Interpretation
| Metric | Complexity | Notes |
| :--- | :--- | :--- |
| **Throughput** | Moderate | Heavy floating-point math per bar |
| **Complexity** | O(1) | Pipeline depth is fixed |
| **Accuracy** | 9/10 | Extracts trend by removing cycle |
| **Timeliness** | 7/10 | Adapts, but has some lag |
| **Overshoot** | 8/10 | Generally good, stable trendline |
| **Smoothness** | 9/10 | Very smooth trendline |
### Trading Signals
## Validation
#### Trend Direction
Validated against Ehlers' original EasyLanguage code and Python ports.
- **Bullish:** Price > HTIT. The instantaneous trend is rising.
- **Bearish:** Price < HTIT. The instantaneous trend is falling.
| Provider | Error Tolerance | Notes |
| :--- | :--- | :--- |
| **Ehlers** | N/A | Logic matches *Rocket Science for Traders* |
#### Crossovers
### Common Pitfalls
- **Signal:** Price crossing the HTIT line is a primary signal. Because HTIT adapts to the cycle, these crossovers often occur near the inflection points of the trend.
### When It Works Best
- **Cyclical Markets:** HTIT excels when the market has a recognizable rhythm or cycle, as it can accurately measure and filter it.
- **Trend Reversals:** It is often faster than SMA/EMA at detecting reversals because it shortens its period when cycles become shorter/faster.
### When It Struggles
- **Chaotic Markets:** If the market has no dominant cycle (white noise), the period measurement can become erratic, causing the trendline to wiggle.
## Architecture Notes
This implementation makes specific trade-offs:
### Choice: Homodyne Discriminator
- **Alternative:** Dual Differentiator or Phase Accumulator.
- **Trade-off:** Complexity vs Stability.
- **Rationale:** The Homodyne Discriminator is Ehlers' preferred method for robust cycle measurement in noisy financial data.
### Choice: Fixed Buffers
- **Alternative:** Dynamic Lists.
- **Trade-off:** Memory usage.
- **Rationale:** Using fixed-size circular buffers for the delay lines (Detrender, Q, I) ensures zero allocation during updates.
## References
- Ehlers, John F. "Rocket Science for Traders: Digital Signal Processing Applications." Wiley, 2001.
- Ehlers, John F. "Cybernetic Analysis for Stocks and Futures." Wiley, 2004.
## C# Usage
### Streaming Updates (Single Instance)
```csharp
using QuanTAlib;
var htit = new Htit();
// Process each new bar
TValue result = htit.Update(new TValue(timestamp, closePrice));
Console.WriteLine($"HTIT: {result.Value:F2}");
// Check if buffer is full (requires some history to establish cycle)
if (htit.IsHot)
{
// Indicator is fully initialized
}
```
### Batch Processing (Historical Data)
```csharp
// TSeries API
TSeries prices = ...;
TSeries htitValues = Htit.Batch(prices);
// Span API (High Performance)
double[] prices = new double[1000];
double[] output = new double[1000];
Htit.Batch(prices.AsSpan(), output.AsSpan());
```
### Bar Correction (isNew Parameter)
```csharp
var htit = new Htit();
// New bar
htit.Update(new TValue(time, 100), isNew: true);
// Intra-bar update
htit.Update(new TValue(time, 101), isNew: false); // Replaces 100 with 101
```
1. **Warmup**: This indicator needs significant warmup (at least 12 bars, ideally 50+) for the feedback loops (period smoothing) to stabilize.
2. **Lag**: While it adapts, the trendline still lags because it's essentially a dynamic SMA. The advantage is that the period is optimal for the current market condition.
3. **Complexity**: Debugging this is a nightmare. Trust the math.