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

Add new moving average implementations: LTMA, MCNMA, NLMA, NMA, NYQMA, RAIN, and TRAMA

Browse Source 
- LTMA (Linear Trend Moving Average): Introduces a predictive moving average using dual cascaded EMAs for trend estimation.
- MCNMA (McNicholl EMA): Implements a zero-lag TEMA using a cascaded EMA structure for enhanced responsiveness.
- NLMA (Non-Lag Moving Average): Utilizes a damped cosine kernel to achieve reduced lag in moving averages.
- NMA (Natural Moving Average): Adapts smoothing based on volatility profiles using a square-root kernel.
- NYQMA (Nyquist Moving Average): Applies the Nyquist-Shannon theorem to prevent aliasing in cascaded moving averages.
- RAIN (Rainbow Moving Average): Combines multiple SMA layers with weighted averages for multi-scale smoothing.
- TRAMA (Trend Regularity Adaptive Moving Average): Adapts smoothing based on the frequency of new highs and lows in price data.
This commit is contained in:
Miha Kralj
2026-02-20 21:40:32 -08:00
parent cbeefc9d64
commit 90d5638008
121 changed files with 9595 additions and 6315 deletions
Download Patch File Download Diff File Expand all files Collapse all files
lib/dynamics/ichimoku/Ichimoku.md
+85 -121
View File
@@ -1,168 +1,132 @@
# ICHIMOKU: Ichimoku Kinko Hyo (One Glance Equilibrium Chart)
# ICHIMOKU: Ichimoku Kinko Hyo
> "Five lines, two clouds, one chart. Goichi Hosoda spent thirty years developing a system that tells you trend, momentum, support, and resistance simultaneously. Most traders use it for about thirty seconds before getting confused."
Ichimoku Kinko Hyo is a comprehensive trend-following system developed by Japanese journalist Goichi Hosoda (pen name Ichimoku Sanjin), published in 1969 after three decades of research. It provides five distinct components that together reveal trend direction, momentum, support/resistance levels, and potential future price zones. The "cloud" (Kumo) formed between Senkou Span A and B is particularly valued for identifying trend strength and equilibrium zones.
Ichimoku Kinko Hyo ("One Glance Equilibrium Chart") is a comprehensive trend-following system that provides five distinct components revealing trend direction, momentum, support/resistance levels, and potential future price zones simultaneously. The Tenkan-sen and Kijun-sen are midpoints of high-low ranges at different timescales (not moving averages of closes). Senkou Span A and B form the "cloud" (Kumo) — a projected equilibrium zone displaced forward in time. Chikou Span is simply the current close displaced backward. All components use sliding window min/max arithmetic, producing step-function behavior on breakouts rather than the smooth curves of EMA-based systems. The system requires OHLC bar input.
## Historical Context
Hosoda began developing Ichimoku in 1935, enlisting university students to hand-calculate the indicator across historical data long before computers made such work trivial. He published the complete system in a seven-volume series in 1969. The indicator remained largely unknown outside Japan until the 1990s, when it gained international recognition through the work of traders and analysts who translated and popularized the system.
The original parameters (9, 26, 52) were calibrated to the Japanese trading week: 9 days (1.5 weeks), 26 days (one month of 6-day trading weeks), and 52 days (two months). While modern 5-day trading weeks would suggest different values, the original parameters remain standard due to their widespread adoption and self-fulfilling nature in liquid markets.
The system is unique among technical indicators in projecting values into the future (Senkou spans displaced 26 periods forward) and into the past (Chikou span displaced 26 periods back), providing a temporal dimension that most indicators lack.
Japanese journalist Goichi Hosoda (pen name "Ichimoku Sanjin") began developing the system in 1935, enlisting university students to hand-calculate the indicator across historical data decades before computers. He published the complete system in a seven-volume series in 1969. Ichimoku remained largely unknown outside Japan until the 1990s when international traders translated and popularized it. The original parameters (9, 26, 52) were calibrated to the Japanese six-day trading week: 9 days (1.5 weeks), 26 days (one month), and 52 days (two months). While modern five-day weeks would suggest different values, the original parameters remain standard due to widespread adoption and their self-fulfilling nature in liquid markets. Some practitioners use (7, 22, 44) for cryptocurrency markets with seven-day trading weeks. The system is unique among technical indicators in projecting values into the future (Senkou spans displaced 26 periods forward) and into the past (Chikou span displaced 26 periods back), providing a temporal dimension most indicators lack.
## Architecture & Physics
### 1. Tenkan-sen (Conversion Line)
The short-term equilibrium, calculated as the midpoint of the highest high and lowest low over the Tenkan period:
Short-term equilibrium — midpoint of the highest high and lowest low over the Tenkan period:
$$
\text{Tenkan}_t = \frac{\max(H, \text{tenkanPeriod}) + \min(L, \text{tenkanPeriod})}{2}
$$
$$\text{Tenkan}_t = \frac{\max(H_{t-8:t}) + \min(L_{t-8:t})}{2}$$
This is not a moving average but a midpoint of the price range, making it responsive to breakouts rather than smooth trends.
This is a range midpoint, not a moving average. It responds to breakouts (new highs or lows entering the window) rather than gradual price changes.
### 2. Kijun-sen (Base Line)
The medium-term equilibrium, calculated identically but over a longer period:
Medium-term equilibrium — same formula over a longer period:
$$
\text{Kijun}_t = \frac{\max(H, \text{kijunPeriod}) + \min(L, \text{kijunPeriod})}{2}
$$
$$\text{Kijun}_t = \frac{\max(H_{t-25:t}) + \min(L_{t-25:t})}{2}$$
Kijun-sen serves as the primary trend reference and key support/resistance level.
Kijun-sen serves as the primary trend reference and key support/resistance level. Flat Kijun indicates a balanced market within that timeframe.
### 3. Senkou Span A (Leading Span A)
The average of Tenkan and Kijun, displaced forward:
The average of Tenkan and Kijun, displayed forward:
$$
\text{SenkouA}_t = \frac{\text{Tenkan}_t + \text{Kijun}_t}{2} \quad \text{(plotted at } t + \text{displacement)}
$$
$$\text{SenkouA}_t = \frac{\text{Tenkan}_t + \text{Kijun}_t}{2} \quad \text{(plotted at } t + \text{displacement)}$$
Forms the first boundary of the cloud. More reactive than Senkou Span B.
The more reactive cloud boundary. Changes faster due to Tenkan's shorter period.
### 4. Senkou Span B (Leading Span B)
The long-term midpoint, displaced forward:
Long-term midpoint, displayed forward:
$$
\text{SenkouB}_t = \frac{\max(H, \text{senkouBPeriod}) + \min(L, \text{senkouBPeriod})}{2} \quad \text{(plotted at } t + \text{displacement)}
$$
$$\text{SenkouB}_t = \frac{\max(H_{t-51:t}) + \min(L_{t-51:t})}{2} \quad \text{(plotted at } t + \text{displacement)}$$
Forms the second boundary of the cloud. Flatter and more stable than Span A.
The slower, flatter cloud boundary. Provides strong support/resistance levels.
### 5. Chikou Span (Lagging Span)
The current close price, displaced backward:
Current close plotted backward:
$$
\text{Chikou}_t = P_t \quad \text{(plotted at } t - \text{displacement)}
$$
$$\text{Chikou}_t = C_t \quad \text{(plotted at } t - \text{displacement)}$$
Confirms trend by comparing current price to historical context.
Confirms trend by comparing current price to the price from 26 bars ago.
### 6. State Management
### 6. Complexity
The indicator implements `ITValuePublisher` directly (not `AbstractBase`) and manages its own ring buffer arrays for high/low tracking. State rollback uses `_state` / `_p_state` with full buffer snapshots (`_highBuffer` / `_p_highBuffer`, `_lowBuffer` / `_p_lowBuffer`).
- **Time:** $O(N_{\text{senkou}})$ per bar for min/max scanning over the longest window (52)
- **Space:** $O(N_{\text{senkou}})$ — ring buffers for high and low histories
- **Warmup:** $\max(N_{\text{tenkan}}, N_{\text{kijun}}, N_{\text{senkou}}) = 52$ bars
## Mathematical Foundation
### Component Summary
### Parameters
| Component | Formula | Default Period | Displacement |
|-----------|---------|---------------|-------------|
| Tenkan-sen | $(HH_9 + LL_9) / 2$ | 9 | None |
| Kijun-sen | $(HH_{26} + LL_{26}) / 2$ | 26 | None |
| Senkou A | $(\text{Tenkan} + \text{Kijun}) / 2$ | N/A | +26 forward |
| Senkou B | $(HH_{52} + LL_{52}) / 2$ | 52 | +26 forward |
| Chikou | Close price | N/A | -26 backward |
| Symbol | Parameter | Default | Original Meaning |
|--------|-----------|---------|-----------------|
| $N_t$ | tenkanPeriod | 9 | 1.5 trading weeks |
| $N_k$ | kijunPeriod | 26 | 1 trading month |
| $N_s$ | senkouBPeriod | 52 | 2 trading months |
| $d$ | displacement | 26 | 1 trading month forward/back |
where $HH_n$ = highest high over $n$ periods, $LL_n$ = lowest low over $n$ periods.
### Pseudo-code
```
Initialize:
highBuf = RingBuffer(senkouBPeriod) // covers all windows
lowBuf = RingBuffer(senkouBPeriod)
bar_count = 0
On each bar (high, low, close, isNew):
if !isNew: restore previous state (including buffer snapshots)
highBuf.Add(high)
lowBuf.Add(low)
bar_count++
// Tenkan-sen (shortest window)
tenkan = (Max(highBuf, tenkanPeriod) + Min(lowBuf, tenkanPeriod)) / 2
// Kijun-sen (medium window)
kijun = (Max(highBuf, kijunPeriod) + Min(lowBuf, kijunPeriod)) / 2
// Senkou Span A (computed now, plotted displacement bars forward)
senkouA = (tenkan + kijun) / 2
// Senkou Span B (longest window, plotted displacement bars forward)
senkouB = (Max(highBuf, senkouBPeriod) + Min(lowBuf, senkouBPeriod)) / 2
// Chikou Span (current close, plotted displacement bars backward)
chikou = close
output:
Tenkan = tenkan // plot at current bar
Kijun = kijun // plot at current bar
SenkouA = senkouA // plot at bar + displacement
SenkouB = senkouB // plot at bar + displacement
Chikou = chikou // plot at bar - displacement
```
### Cloud (Kumo) Interpretation
$$
\text{Cloud}_{bullish} \iff \text{SenkouA} > \text{SenkouB}
$$
| Condition | Meaning |
|-----------|---------|
| SenkouA > SenkouB | Bullish cloud (green) — uptrend structure |
| SenkouA < SenkouB | Bearish cloud (red) — downtrend structure |
| Cloud twist (A crosses B) | Potential trend reversal (leading signal) |
| Thick cloud | Strong support/resistance zone |
| Thin cloud | Weak equilibrium — vulnerable to breakout |
| Price above cloud | Bullish bias |
| Price below cloud | Bearish bias |
| Price inside cloud | Indeterminate — consolidation |
$$
\text{Cloud}_{bearish} \iff \text{SenkouA} < \text{SenkouB}
$$
### Displacement Note
$$
\text{Cloud thickness} = |\text{SenkouA} - \text{SenkouB}|
$$
Senkou Span A and B are computed at the current bar but displayed shifted forward by `displacement` bars on charts. Chikou Span is the current close displayed shifted backward. The implementation computes current-bar values only — the charting layer handles the visual displacement.
### Default Parameters
### Multi-Output Structure
| Parameter | Default | Original Meaning |
|-----------|---------|-----------------|
| tenkanPeriod | 9 | 1.5 trading weeks (6-day week) |
| kijunPeriod | 26 | 1 trading month |
| senkouBPeriod | 52 | 2 trading months |
| displacement | 26 | 1 trading month forward/back |
The indicator produces five simultaneous values per bar. The primary output (`Last`) returns Kijun-sen as the default reference line.
### Warmup
## Resources
$$
\text{WarmupPeriod} = \max(\text{tenkanPeriod}, \text{kijunPeriod}, \text{senkouBPeriod})
$$
## Performance Profile
### Operation Count (Streaming Mode)
| Operation | Count | Notes |
| :--- | :---: | :--- |
| Min/Max scan | 3 | Tenkan, Kijun, SenkouB windows |
| ADD | 3 | Midpoint calculations |
| DIV | 3 | Midpoint /2 |
| Buffer update | 2 | High + low ring buffers |
| State copy | 2 | Buffer snapshots for rollback |
| **Total** | **~11 ops** | Plus O(n) for min/max scans |
### Quality Metrics
| Metric | Score | Notes |
| :--- | :---: | :--- |
| **Accuracy** | 10/10 | Exact min/max arithmetic |
| **Timeliness** | 6/10 | Midpoint-based, moderate lag |
| **Smoothness** | 5/10 | Step-like behavior on breakouts |
| **Complexity** | 4/10 | Five components, displacement logic |
## Validation
| Library | Status | Notes |
| :--- | :---: | :--- |
| **Skender** | ✅ | All 5 components match |
| **TA-Lib** | N/A | No Ichimoku function |
| **Tulip** | N/A | No Ichimoku function |
| **Ooples** | ✅ | Matches within tolerance |
| **TradingView** | ✅ | Matches PineScript reference |
## Common Pitfalls
1. **Displacement is charting-only**: The implementation computes current values for Senkou A/B. The forward displacement (plotting these values 26 bars ahead) is the responsibility of the charting layer, not the indicator.
2. **TBar input required**: Ichimoku operates on OHLC bars, not single values. It implements `ITValuePublisher` directly and accepts `TBar` input, not `TValue`.
3. **Multiple outputs**: The indicator exposes five separate properties (Tenkan, Kijun, SenkouA, SenkouB, Chikou). The `Last` property returns Kijun-sen as the primary reference.
4. **Not a moving average**: Tenkan and Kijun are midpoints of high-low ranges, not averages of closing prices. They respond to range breakouts, not gradual price changes.
5. **Cloud twist**: When Senkou A crosses Senkou B, the cloud color changes. This is a leading signal because the spans are displaced forward.
6. **Chikou confirmation**: Chikou Span is simply the current close plotted 26 bars back. When Chikou is above the price from 26 bars ago, the trend is confirmed bullish.
7. **Parameter sensitivity**: Changing from the standard (9, 26, 52) parameters alters the equilibrium model. Some practitioners use (7, 22, 44) for crypto markets with 7-day trading weeks.
## References
- Hosoda, G. (1969). "Ichimoku Kinko Hyo." Tokyo, Japan.
- Patel, M. (2010). "Trading with Ichimoku Clouds." Wiley.
- Elliott, N. (2007). "Ichimoku Charts: An Introduction to Ichimoku Kinko Clouds." Harriman House.
- StockCharts.com: "Ichimoku Cloud" Technical Analysis documentation.
- Investopedia: "Ichimoku Cloud Definition and Uses."
- Hosoda, G. — *Ichimoku Kinko Hyo* (7-volume series, Tokyo, 1969)
- Patel, M. — *Trading with Ichimoku Clouds* (John Wiley & Sons, 2010)
- Elliott, N. — *Ichimoku Charts: An Introduction* (Harriman House, 2007)
- PineScript reference: `ichimoku.pine` in indicator directory