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

Add Savitzky-Golay Moving Average (SGMA) Indicator Implementation

Browse Source 
- Implemented SgmaIndicator class in C# with properties for Period, Degree, and Source.
- Added unit tests for SgmaIndicator covering constructor defaults, initialization, and various update scenarios.
- Created a new Quantower adapter for the SGMA indicator, including input parameters and line series setup.
- Removed legacy SGMA implementation and tests to streamline the codebase.
- Updated project files to include new indicator and tests in the build process.
- Generated a missing indicators report and outlined a plan for oscillator documentation rewrite.
This commit is contained in:
Miha Kralj
2026-02-13 21:44:45 -08:00
parent 951842acca
commit dfeb23bf3d
81 changed files with 13629 additions and 2041 deletions
Download Patch File Download Diff File Expand all files Collapse all files
lib/oscillators/stochrsi/Stochrsi.md
+157 -172
View File
@@ -2,228 +2,213 @@
> "RSI tells you whether momentum is overbought. Stochastic RSI tells you whether RSI itself is overbought. It's turtles all the way down." -- Anonymous quant
## Overview
| Property | Value |
|----------|-------|
| **Category** | Oscillator |
| **Inputs** | Single series (close) |
| **Parameters** | `rsiLength` (default 14), `stochLength` (default 14), `kSmooth` (default 3), `dSmooth` (default 3) |
| **Outputs** | Dual series (%K line, %D signal line) |
| **Output range** | $0$ to $100$ |
| **Warmup** | `rsiWarmup + stochLength - 1 + kSmooth - 1 + dSmooth - 1` bars |
The **Stochastic RSI (StochRSI)** applies the Stochastic Oscillator formula to RSI values instead of raw price. The result is a bounded oscillator (0-100) that is more sensitive to short-term overbought/oversold conditions than RSI alone. Where RSI might linger in the 40-60 range during consolidation, StochRSI pushes to extremes more frequently, giving traders earlier (though noisier) reversal signals.
### Key takeaways
The indicator produces two lines:
- **%K**: SMA-smoothed stochastic of RSI values
- **%D**: SMA of %K (signal line)
- Applies the Stochastic formula to RSI values instead of price, measuring RSI's position within its own recent range.
- More sensitive than RSI alone: a modest RSI move from 45 to 55 can produce a StochRSI swing from 0 to 100.
- Four parameters create a large configuration space. The defaults (14, 14, 3, 3) match TradingView convention.
- Uses `MonotonicDeque` for O(1) amortized RSI min/max tracking plus circular-buffer SMA for %K and %D smoothing.
- Recursive RSI dependency makes SIMD vectorization impractical; batch mode uses streaming replay.
## Historical Context
Tushar Chande and Stanley Kroll introduced the Stochastic RSI in their 1994 book *The New Technical Trader*. Their motivation was straightforward: RSI often spends long periods in non-extreme territory during strong trends, making it difficult to identify shorter-term turning points. By applying the Stochastic normalization to RSI, they created an indicator that oscillates across its full 0-100 range regardless of the underlying trend strength.
Tushar Chande and Stanley Kroll introduced the Stochastic RSI in *The New Technical Trader* (1994). Their motivation was practical: RSI frequently lingers in the 40-60 range during strong trends, making it difficult to identify shorter-term turning points. By applying Stochastic normalization to RSI, they created an indicator that oscillates across its full $[0, 100]$ range regardless of the underlying trend strength.
The key insight is that StochRSI measures RSI's position within its own recent range, not price's position within its range. This double transformation amplifies sensitivity at the cost of increased noise, a tradeoff that suits short-term mean-reversion strategies but can mislead trend followers.
The key insight is that StochRSI measures RSI's position within its own recent range, not price's position within its range. This double transformation amplifies sensitivity at the cost of increased noise. A tradeoff that suits short-term mean-reversion strategies but misleads trend followers who mistake every extreme reading for a reversal.
Most implementations follow the TradingView convention of smoothing both %K and %D with SMA, producing what is effectively a "Slow StochRSI." The unsmoothed variant (kSmooth=1) gives the raw stochastic of RSI.
Most implementations follow the TradingView convention of smoothing both %K and %D with SMA, producing what is effectively a "Slow StochRSI." Setting `kSmooth=1` gives the raw stochastic of RSI, matching TA-Lib's `STOCHRSI` function.
## Architecture
## What It Measures and Why It Matters
```
Source ──→ RSI(rsiLength) ──→ Stochastic(stochLength) ──→ SMA(kSmooth) ──→ %K
│
SMA(dSmooth) ──→ %D
```
StochRSI measures where the current RSI value sits within the highest and lowest RSI values over the past `stochLength` bars, normalized to $[0, 100]$. A reading of $100$ means RSI is at its highest point in the lookback window. A reading of $0$ means RSI is at its lowest.
### Streaming (O(1) amortized per bar)
The double transformation (price to RSI, then RSI to Stochastic) makes StochRSI react faster to momentum changes than either indicator alone. Where RSI might take several bars to move from neutral to overbought, StochRSI can snap to $100$ the moment RSI reaches a new local high within its window.
The streaming path chains three computation stages, each maintaining O(1) state:
| Component | Data Structure | Role |
|-----------|---------------|------|
| RSI | Internal `Rsi` instance | Computes RSI values from source prices |
| Min/Max tracking | `MonotonicDeque` pair | O(1) amortized sliding min/max of RSI over `stochLength` |
| %K smoothing | Circular buffer + running sum | O(1) SMA of raw stochastic values |
| %D smoothing | Circular buffer + running sum | O(1) SMA of %K values |
### State Management
```
State record struct:
Count -- bar counter for warmup tracking
KSum / KHead -- running sum and circular buffer head for %K SMA
DSum / DHead -- running sum and circular buffer head for %D SMA
LastValidValue -- NaN/Infinity protection (last valid source price)
K / D -- current %K and %D output values
PrevRsiBufVal -- saved RSI buffer slot for bar correction rollback
PrevKBufVal -- saved %K buffer slot for bar correction rollback
PrevDBufVal -- saved %D buffer slot for bar correction rollback
```
The standard `_s` / `_ps` state snapshot pair enables bar correction:
- `isNew=true`: `_ps = _s`, save buffer slot values before overwrite, advance counters
- `isNew=false`: `_s = _ps`, restore buffer slot values, recompute from previous state
The RSI instance also supports bar correction through its own `isNew` parameter.
### Warmup
$$
\text{WarmupPeriod} = \text{RSI warmup} + \text{stochLength} - 1 + \text{kSmooth} - 1 + \text{dSmooth} - 1
$$
With default parameters (14, 14, 3, 3): RSI warmup = 15, total = 15 + 13 + 2 + 2 = 32 bars.
`IsHot` fires when `Count >= WarmupPeriod`.
### Batch Path
`Update(TSeries)` uses streaming replay, not a separate span-based batch path. This ensures exact consistency between streaming and batch modes at the cost of batch throughput. The recursive RSI dependency makes SIMD vectorization impractical for the full pipeline.
This amplified sensitivity is useful for short-term mean-reversion setups in range-bound markets. In trending markets, StochRSI stays pinned at extremes for extended periods, which confirms trend strength but generates false reversal signals. Understanding the market regime determines whether StochRSI's sensitivity is a feature or a liability.
## Mathematical Foundation
### RSI Stage
### Core Formula
**Step 1: RSI**
$$
\text{RSI}[n] = 100 - \frac{100}{1 + \frac{\text{AvgGain}[n]}{\text{AvgLoss}[n]}}
\text{RSI}_t = 100 - \frac{100}{1 + \frac{\text{AvgGain}_t}{\text{AvgLoss}_t}}
$$
Where AvgGain and AvgLoss use Wilder's exponential smoothing with period `rsiLength`.
where AvgGain and AvgLoss use Wilder's exponential smoothing with period `rsiLength`.
### Stochastic Normalization
**Step 2: Stochastic normalization**
$$
\text{rawStoch}[n] = 100 \times \frac{\text{RSI}[n] - \min(\text{RSI}, \text{stochLength})}{\max(\text{RSI}, \text{stochLength}) - \min(\text{RSI}, \text{stochLength})}
\text{rawStoch}_t = 100 \times \frac{\text{RSI}_t - \min(\text{RSI}, n_s)}{\max(\text{RSI}, n_s) - \min(\text{RSI}, n_s)}
$$
When $\max = \min$ (RSI flat over the window), rawStoch = 0.
where $n_s$ is `stochLength`. When $\max = \min$, rawStoch $= 50$.
### %K Smoothing
**Step 3: %K smoothing**
$$
\%K[n] = \text{SMA}(\text{rawStoch}, \text{kSmooth})
\%K_t = \text{SMA}(\text{rawStoch}, k)
$$
### %D Signal Line
where $k$ is `kSmooth`.
**Step 4: %D signal line**
$$
\%D[n] = \text{SMA}(\%K, \text{dSmooth})
\%D_t = \text{SMA}(\%K, d)
$$
### Warmup Seeding
where $d$ is `dSmooth`.
Following the PineScript convention, SMA buffers are pre-filled with the first computed value rather than NaN. This produces usable output from bar 1 of each SMA stage, matching TradingView behavior.
### Parameter Mapping
## Performance Profile
| Parameter | Code | Default | Constraints |
|-----------|------|---------|-------------|
| RSI Length | `rsiLength` | 14 | `> 0` |
| Stoch Length | `stochLength` | 14 | `> 0` |
| K Smoothing | `kSmooth` | 3 | `> 0` |
| D Smoothing | `dSmooth` | 3 | `> 0` |
| Metric | Value |
|--------|-------|
| Time complexity | O(1) amortized per bar (streaming) |
| Space complexity | O(stochLength + kSmooth + dSmooth) |
| Allocations | Zero per update |
| NaN handling | Last valid value substitution |
| SIMD | Not applicable (recursive RSI dependency) |
| FMA | Not used (SMA arithmetic too simple to benefit) |
### Warmup Period
| Quality Metric | Score (1-10) |
|----------------|-------------|
| Sensitivity | 9 |
| Smoothness | 5 (with kSmooth=3, dSmooth=3) |
| Noise rejection | 4 |
| Overbought/Oversold detection | 9 |
| Trend following | 3 |
$$
W = W_{\text{RSI}} + (n_s - 1) + (k - 1) + (d - 1)
$$
With defaults: $W_{\text{RSI}} = 15$, total $= 15 + 13 + 2 + 2 = 32$ bars.
## Architecture & Physics
### 1. Three-Stage Pipeline
```text
Source -> RSI(rsiLength) -> Stochastic(stochLength) -> SMA(kSmooth) -> %K
|
SMA(dSmooth) -> %D
```
Each stage maintains O(1) streaming state independently.
### 2. RSI Subsystem
An internal `Rsi` instance handles the first transformation. RSI manages its own bar correction via the `isNew` parameter, keeping state synchronized with the outer indicator.
### 3. MonotonicDeque Min/Max
A `MonotonicDeque` pair tracks the sliding min/max of RSI values over `stochLength` bars. Circular buffer (`_rsiBuf`) stores raw RSI values for deque rebuild on bar correction.
### 4. Dual SMA Smoothing
Two circular buffers (`_kBuf`, `_dBuf`) with running sums compute the %K and %D SMAs in O(1). Progressive fill: the SMA denominator ramps up from 1 to the full period as bars accumulate.
### 5. Edge Cases
| Condition | Behavior |
|-----------|----------|
| Any parameter `<= 0` | `ArgumentException` with `nameof()` |
| `NaN` / `Infinity` input | Substitutes last valid value |
| Flat RSI ($\max = \min$) | rawStoch returns $50$ |
| `kSmooth = 1` | No %K smoothing (matches TA-Lib convention) |
| `isNew = false` | Restores `_ps` + saved buffer slots; RSI handles its own rollback |
## Interpretation and Signals
### Signal Zones
| Zone | Condition | Interpretation |
|------|-----------|----------------|
| Overbought | `%K > 80` | RSI near top of its recent range |
| Neutral | `20 ≤ %K ≤ 80` | Normal RSI fluctuation |
| Oversold | `%K < 20` | RSI near bottom of its recent range |
### Signal Patterns
- **%K/%D crossover in extremes**: Bullish when %K crosses above %D below 20 (oversold reversal). Bearish when %K crosses below %D above 80. Mid-range crossovers are less reliable.
- **Divergence**: Price makes lower lows while StochRSI makes higher lows (bullish) or price makes higher highs while StochRSI makes lower highs (bearish). More frequent than RSI divergences due to amplified sensitivity.
- **Extended extremes**: StochRSI pinned at 0 or 100 indicates strong directional momentum, not an imminent reversal.
### Practical Notes
- StochRSI is best suited for mean-reversion strategies in ranging markets. In trending markets, it generates persistent false reversal signals.
- The four-parameter configuration space is large. Start with the TradingView defaults (14, 14, 3, 3) and adjust only with evidence.
- Use `kSmooth=1` to match TA-Lib's `STOCHRSI` output. Use `kSmooth=3` to match TradingView/Skender.
## Related Indicators
- [**Stoch**](../stoch/Stoch.md): Applies the stochastic formula to price instead of RSI.
- [**Stochf**](../stochf/Stochf.md): Fast Stochastic on price with shorter default lookback.
- [**RSI**](../../momentum/rsi/Rsi.md): The underlying momentum oscillator that StochRSI normalizes.
- [**SMI**](../smi/Smi.md): Measures distance from range midpoint instead of boundary; less sensitive but smoother.
## Validation
Cross-validated against independent implementations:
| Library | Status | Notes |
|---------|--------|-------|
| Skender | ✅ | `GetStochRsi(rsiLen, stochLen, dSmooth, kSmooth)` matches within `1e-6` |
| TA-Lib | ✅ | `StochRsi(close, rsiLen, stochLen, dSmooth)` with `kSmooth=1` matches within `1e-6` |
| Ooples | ⚠️ | Smoke test only. Fundamentally different algorithm (EMA-based); not directly comparable |
| Library | Mode | Tolerance | Status | Notes |
|---------|------|-----------|--------|-------|
| Skender | Batch | 1e-9 | Pass | Exact match after warmup |
| Skender | Streaming | 1e-9 | Pass | Bar-by-bar verification |
| Skender | Span | 1e-9 | Pass | Span API consistency |
| TA-Lib | Batch | 1e-9 | Pass | Lookback-aligned comparison |
| Ooples | Smoke | N/A | Smoke | Fundamentally different implementation (incompatible) |
## Performance Profile
Self-consistency validated across streaming, batch, span, and eventing API modes with exact match verification.
### Key Optimizations
### Ooples Incompatibility
- **O(1) amortized streaming**: MonotonicDeque for RSI min/max; circular buffers for both SMA stages.
- **Zero allocation**: `Update` uses pre-allocated buffers and `record struct State`.
- **Bar correction**: Saved buffer slot values (`PrevRsiBufVal`, `PrevKBufVal`, `PrevDBufVal`) enable rollback without buffer cloning.
- **Streaming replay batch**: Batch mode replays streaming to guarantee exact consistency; no separate SIMD path.
OoplesFinance uses a structurally different StochRSI calculation that produces values on a different scale and with different smoothing. This is not a bug in either implementation; the two libraries interpret "Stochastic RSI" differently. The Ooples test runs as a smoke test (verifies no crashes) without value comparison.
### Operation Count (Streaming Mode)
| Operation | Count per bar |
|-----------|---------------|
| RSI computation | ~6 ops (see RSI profile) |
| Deque push (amortized) | 2-3 comparisons |
| %K SMA update | 3 (sub + add + div) |
| %D SMA update | 3 (sub + add + div) |
| NaN check | 1 |
| **Total** | **~15 ops** |
### SIMD Analysis (Batch Mode)
| Property | Value |
|----------|-------|
| Vectorizable | No |
| Reason | Recursive RSI dependency prevents parallelization |
| Fallback | Streaming replay for batch consistency |
## Common Pitfalls
1. **Double sensitivity trap.** StochRSI amplifies RSI's movements. A modest RSI move from 45 to 55 can produce a StochRSI swing from 0 to 100 if that range spans the recent RSI min/max. Do not treat every 0 or 100 reading as a strong signal.
1. **Double sensitivity trap**: StochRSI amplifies RSI's movements. A modest RSI move from 45 to 55 can produce a StochRSI swing from 0 to 100. Not every extreme reading is a strong signal.
2. **Warmup underestimation**: With defaults (14, 14, 3, 3), StochRSI needs 32 bars, not 14. Trading on early output produces unreliable signals.
3. **Flat RSI = midpoint**: When RSI is constant over the stochastic window, max equals min and the formula returns 50. Some implementations return 0 or NaN.
4. **Parameter interaction complexity**: Four parameters create a large configuration space. Shorter `rsiLength` increases noise; longer `stochLength` increases lag; larger smoothing periods reduce signal frequency.
5. **Cross-library comparison hazards**: TA-Lib uses `kSmooth=1` (no %K smoothing). Skender/TradingView use `kSmooth=3`. Always match smoothing parameters before comparing outputs.
6. **Overbought persistence**: In strong trends, StochRSI stays above 80 for extended periods. Counter-trend trades based solely on StochRSI readings produce drawdowns.
2. **Flat RSI = zero division.** When RSI is constant over the stochastic window (common during low-volatility consolidation), max = min and the stochastic formula produces 0. Some implementations return 50 or NaN here; QuanTAlib returns 0, matching TradingView.
## FAQ
3. **Warmup period underestimation.** StochRSI needs RSI to stabilize first, then the stochastic window to fill, then both SMA smoothers to fill. With defaults (14,14,3,3), that is 32 bars, not 14.
**Q: Why does StochRSI not match between TA-Lib and TradingView?**
A: TA-Lib's `STOCHRSI` does not smooth %K (equivalent to `kSmooth=1`). TradingView applies `kSmooth=3` by default. Set `kSmooth=1` in QuanTAlib to match TA-Lib; use `kSmooth=3` to match TradingView.
4. **Confusing %K and %D roles.** In standard Stochastic, %K is the fast line. In StochRSI with kSmooth > 1, %K is already smoothed. The "fast" vs "slow" distinction from regular Stochastic does not directly apply.
**Q: When should I use StochRSI instead of RSI?**
A: When you need faster signals and can tolerate more noise. StochRSI is better for short-term mean-reversion in ranging markets. RSI is better for trend-following and longer-term momentum analysis.
5. **Overbought does not mean sell.** In strong uptrends, StochRSI can stay above 80 for extended periods. Use StochRSI for mean-reversion strategies in ranging markets, not as a counter-trend tool in trending markets.
6. **Parameter interaction complexity.** Four parameters (rsiLength, stochLength, kSmooth, dSmooth) create a large configuration space. The defaults (14,14,3,3) are the TradingView standard. Shorter rsiLength increases noise; longer stochLength increases lag; larger smoothing periods reduce signal frequency.
7. **Cross-library comparison hazards.** Different libraries handle warmup, SMA seeding, and edge cases differently. Always align warmup periods before comparing output arrays.
## Usage
```csharp
// Streaming (returns K line)
var stochrsi = new Stochrsi(rsiLength: 14, stochLength: 14, kSmooth: 3, dSmooth: 3);
TValue result = stochrsi.Update(new TValue(time, price));
// Access K and D values
double k = stochrsi.K;
double d = stochrsi.D;
// Event-based chaining
var source = new TSeries();
var stochrsi = new Stochrsi(source, rsiLength: 14, stochLength: 14);
// Batch (TSeries) - returns K line
TSeries kResults = Stochrsi.Batch(source);
// Batch with K and D lines
var indicator = new Stochrsi();
var (kSeries, dSeries) = indicator.UpdateKD(source);
// Calculate (returns indicator for state inspection)
var (results, ind) = Stochrsi.Calculate(source);
```
## Interpretation
- **Overbought / Oversold:**
| Zone | Level | Interpretation |
|------|-------|----------------|
| Overbought | > 80 | RSI is near the top of its recent range |
| Neutral | 20-80 | Normal RSI fluctuation |
| Oversold | < 20 | RSI is near the bottom of its recent range |
- **%K/%D Crossovers:**
- Bullish: %K crosses above %D below 20 (oversold reversal)
- Bearish: %K crosses below %D above 80 (overbought reversal)
- Mid-range crossovers are less reliable
- **Divergence:**
- Bullish: Price makes lower lows while StochRSI makes higher lows
- Bearish: Price makes higher highs while StochRSI makes lower highs
- More frequent than RSI divergences due to amplified sensitivity
- **Zero and 100 extremes:**
- StochRSI = 0: RSI is at the lowest point in its stochastic window
- StochRSI = 100: RSI is at the highest point in its stochastic window
- Extended stays at 0 or 100 indicate strong directional momentum
## Parameters
| Parameter | Type | Default | Range | Description |
|-----------|------|---------|-------|-------------|
| `rsiLength` | int | 14 | > 0 | RSI calculation period |
| `stochLength` | int | 14 | > 0 | Stochastic lookback period for RSI min/max |
| `kSmooth` | int | 3 | > 0 | SMA smoothing period for %K |
| `dSmooth` | int | 3 | > 0 | SMA smoothing period for %D signal line |
**Q: Why is the batch path slower than other indicators?**
A: The recursive RSI dependency prevents SIMD vectorization. Batch mode replays streaming updates to guarantee exact consistency between API modes. The trade-off is correctness over throughput.
## References
- Chande, Tushar S. and Kroll, Stanley. *The New Technical Trader*. John Wiley & Sons, 1994
- Wilder, J. Welles. *New Concepts in Technical Trading Systems*. Trend Research, 1978
- Murphy, John J. *Technical Analysis of the Financial Markets*. New York Institute of Finance, 1999
- [TradingView Stochastic RSI](https://www.tradingview.com/support/solutions/43000502333/)
- [Investopedia Stochastic RSI](https://www.investopedia.com/terms/s/stochrsi.asp)
- Chande, T. S.; Kroll, S. *The New Technical Trader*. Wiley, 1994.
- Wilder, J. W. *New Concepts in Technical Trading Systems*. Trend Research, 1978.
- Murphy, J. J. *Technical Analysis of the Financial Markets*. New York Institute of Finance, 1999.