QuanTAlib/lib/channels/stbands/stbands.md

STBANDS: Super Trend Bands

Super Trend bands fuse trend direction with volatility width, flipping their bias at each breakout.

Property	Value
Category	Channel
Inputs	OHLCV bar (TBar)
Parameters	period (default DefaultPeriod), multiplier (default DefaultMultiplier)
Outputs	Multiple series (Upper, Lower, Trend, Width)
Output range	Tracks input
Warmup	period bars
PineScript	stbands.pine

• Super Trend Bands provide ATR-based dynamic support and resistance levels with asymmetric ratchet logic: the upper band only tightens downward duri...
• Similar: BBands, KC | Complementary: Volume for breakout validation | Trading note: Stoller bands use ATR multiplier instead of standard deviation.
• Validated against TA-Lib, Skender, and Tulip reference implementations where available.

Super Trend Bands provide ATR-based dynamic support and resistance levels with asymmetric ratchet logic: the upper band only tightens downward during downtrends, and the lower band only tightens upward during uptrends. This creates natural trailing stop-loss levels that respect market momentum. A trend direction signal (+1 or -1) flips when price breaches the opposite band. The ATR is computed as a simple moving average of True Range via a ring buffer with running sum, providing O(1) streaming updates.

Historical Context

The SuperTrend indicator emerged from the trading community's need for a volatility-adaptive trend-following tool. Olivier Seban popularized the concept, building on Wilder's ATR foundation to create bands that respect trend direction rather than blindly following price symmetrically.

Traditional channel indicators like Bollinger Bands expand and contract symmetrically around price. SuperTrend takes a different approach: once a band establishes a level favorable to the trend, it refuses to retreat. This asymmetric "ratchet effect" means the lower band in an uptrend can only rise (never fall), creating a progressively tighter trailing stop. The band resets only when price violates it, triggering a trend reversal.

The implementation here follows the canonical PineScript algorithm, using a simple moving average of True Range rather than Wilder's exponentially smoothed ATR. This produces slightly more responsive bands since the SMA gives equal weight to all TR values in the window, while Wilder's RMA carries heavier memory of older values.

Architecture & Physics

1. True Range

True Range captures the full extent of price movement including gaps:

TR_t = \max(H_t - L_t,\; |H_t - C_{t-1}|,\; |L_t - C_{t-1}|)

2. Average True Range (SMA of TR)

The implementation uses a simple moving average of TR via ring buffer with running sum:

ATR_t = \frac{1}{\min(t+1, n)} \sum_{i=0}^{\min(t,n-1)} TR_{t-i}

The running sum provides O(1) updates: subtract the oldest TR leaving the window, add the new TR.

3. Basic Band Calculation

Bands center on HL2 (the bar midpoint):

\text{HL2}_t = \frac{H_t + L_t}{2}

\text{BasicUpper}_t = \text{HL2}_t + k \cdot ATR_t

\text{BasicLower}_t = \text{HL2}_t - k \cdot ATR_t

where k is the multiplier (default 3.0).

4. Ratchet Logic (Final Bands)

The defining characteristic. Bands only move in the trend-favorable direction:

\text{Upper}_t = \begin{cases}
\text{BasicUpper}_t & \text{if } \text{BasicUpper}_t < \text{Upper}_{t-1} \;\text{OR}\; C_{t-1} > \text{Upper}_{t-1} \\
\text{Upper}_{t-1} & \text{otherwise}
\end{cases}

\text{Lower}_t = \begin{cases}
\text{BasicLower}_t & \text{if } \text{BasicLower}_t > \text{Lower}_{t-1} \;\text{OR}\; C_{t-1} < \text{Lower}_{t-1} \\
\text{Lower}_{t-1} & \text{otherwise}
\end{cases}

In words: the upper band adopts the new (lower) basic value only if it tightens, or if price already broke above the previous upper band (resetting it). The lower band rises only if the new basic value is higher, or if price already broke below the previous lower band.

5. Trend Determination

Trend flips when price breaches the opposite band:

\text{Trend}_t = \begin{cases}
+1 & \text{if } C_t \leq \text{Lower}_t \\
-1 & \text{if } C_t \geq \text{Upper}_t \\
\text{Trend}_{t-1} & \text{otherwise}
\end{cases}

+1 = bullish (price is above the lower band trailing stop), -1 = bearish (price is below the upper band trailing stop).

6. Complexity

Streaming: O(1) per bar. The TR running sum uses a ring buffer; the ratchet logic and trend determination are constant-time comparisons. Memory: one ring buffer of n floats plus scalar state for previous bands, trend, and close.

Mathematical Foundation

Parameters

Symbol	Name	Default	Constraint	Description
n	period	10	> 0	ATR lookback period
k	multiplier	3.0	> 0	ATR multiplier for band distance from HL2

Band State Transitions

Condition	Upper Band	Lower Band
Uptrend, price rising	Holds	Rises (tightens)
Uptrend, price breaks upper	Resets to basic	Holds
Downtrend, price falling	Drops (tightens)	Holds
Downtrend, price breaks lower	Holds	Resets to basic

Output Interpretation

Output	Interpretation
Trend = +1	Bullish; lower band acts as trailing stop
Trend = -1	Bearish; upper band acts as trailing stop
Trend flip +1 \to -1	Bearish reversal; price breached upper band
Trend flip -1 \to +1	Bullish reversal; price breached lower band
Band width contracting	ATR falling; volatility decreasing

Performance Profile

Operation Count (Streaming Mode)

STBANDS computes True Range, an SMA of TR via running sum, basic band math from HL2, ratchet logic, and trend determination:

Operation	Count	Cost (cycles)	Subtotal
SUB (H - L)	1	1	1
SUB + ABS (H - prevC, L - prevC)	2	2	4
CMP (max of 3 for TR)	2	1	2
SUB (oldest from TR sum)	1	1	1
ADD (new to TR sum)	1	1	1
DIV (TR sum / count for ATR)	1	15	15
ADD (H + L for HL2)	1	1	1
MUL (× 0.5 for HL2)	1	3	3
MUL (k × ATR)	1	3	3
ADD/SUB (HL2 ± k·ATR)	2	1	2
CMP (ratchet: upper tightens?)	2	1	2
CMP (ratchet: lower tightens?)	2	1	2
CMP (trend: close vs bands)	2	1	2
Total (hot)	19	—	~39 cycles

The ratchet logic is pure comparisons with no expensive math. The DIV for ATR is the costliest single operation.

Batch Mode (SIMD Analysis)

The ATR running sum and ratchet logic are both sequential (state-dependent). True Range and basic band computation are vectorizable:

Optimization	Benefit
True Range (3-way max)	Vectorizable with Vector.Max and Vector.Abs
HL2 + basic bands	Vectorizable in a batch pre-pass
ATR running sum	Sequential
Ratchet logic + trend	Sequential (conditional state)

Resources

• Seban, O. SuperTrend Indicator methodology.
• Wilder, J. W. (1978). New Concepts in Technical Trading Systems. Trend Research.
• TradingView. "SuperTrend." Pine Script Reference.