QuanTAlib/lib/channels/atrbands/atrbands.md

ATRBANDS: Average True Range Bands

Property	Value
Category	Channel
Inputs	OHLCV bar (TBar)
Parameters	period, multiplier (default 2.0)
Outputs	Multiple series (Upper, Lower)
Output range	Tracks input
Warmup	period bars

TL;DR

• ATR Bands create a volatility-adaptive envelope by projecting Wilder's Average True Range above and below a central Simple Moving Average.
• Parameterized by period, multiplier (default 2.0).
• Output range: Tracks input.
• Requires period bars of warmup before first valid output (IsHot = true).
• Validated against TA-Lib, Skender, and Tulip reference implementations where available.

ATR Bands create a volatility-adaptive envelope by projecting Wilder's Average True Range above and below a central Simple Moving Average. Unlike fixed-percentage envelopes or standard-deviation bands, ATR Bands use True Range to measure volatility, making them robust for assets with gaps, pre-market moves, and 24/7 trading where the "hidden" volatility between bars is significant. The True Range captures the maximum of intra-bar range, gap-up distance, and gap-down distance, ensuring that overnight gaps contribute fully to band width even when the current bar's open-to-close range is narrow.

Historical Context

J. Welles Wilder introduced Average True Range in New Concepts in Technical Trading Systems (1978), primarily as a trailing stop mechanism (the "Volatility Stop") and as a component of the Average Directional Index (ADX). Wilder used his own smoothing method, now known as RMA or Wilder's Smoothing, which is equivalent to an EMA with \alpha = 1/n. Futures traders in the 1980s quickly realized that projecting ATR above and below a trend-following moving average created a practical channel answering the question: "How far can price move from the average before it is statistically abnormal?"

ATR Bands differ from Keltner Channels only in the center line: ATR Bands use SMA, Keltner uses EMA. Some implementations use SMA-based ATR averaging instead of Wilder's smoothing. The QuanTAlib implementation uses Wilder's smoothing (RMA) for ATR with a warmup compensator for accurate early values, and SMA for the center line.

Architecture & Physics

1. True Range

True Range captures the maximum 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 (Wilder's Smoothing / RMA)

ATR_t = \frac{ATR_{t-1} \times (n - 1) + TR_t}{n}

This is equivalent to EMA with \alpha = 1/n. The warmup compensator corrects for initialization bias:

e_t = (1 - \alpha) \cdot e_{t-1}, \quad ATR_t^* = \frac{ATR_t}{1 - e_t} \text{ while } e > \epsilon

3. Center Line (SMA)

\text{Middle}_t = \frac{1}{n} \sum_{i=0}^{n-1} x_{t-i}

4. Band Construction

\text{Upper}_t = \text{Middle}_t + k \cdot ATR_t \text{Lower}_t = \text{Middle}_t - k \cdot ATR_t

5. Complexity

The SMA uses a circular buffer for O(1) running sums. The ATR uses recursive IIR smoothing, also O(1). True Range computation requires retaining the previous close. Total: O(1) per bar with one buffer of size n for the SMA.

Mathematical Foundation

Parameters

Parameter	Description	Default	Constraint
period	Lookback for SMA and ATR smoothing (n)	20	> 0
multiplier	Band width scale factor (k)	2.0	> 0
source	Input series for center line	close

True Range Components

Component	Formula	Captures
Intra-bar	H_t - L_t	Current bar's range
Gap-up	\|H_t - C_{t-1}\|	Upward gap distance
Gap-down	\|L_t - C_{t-1}\|	Downward gap distance

Pseudo-code

function ATRBANDS(source, high, low, close, period, multiplier):
    validate: period > 0, multiplier > 0

    // True Range
    tr = max(high - low, |high - prev_close|, |low - prev_close|)
    prev_close = close

    // ATR via Wilder's smoothing (RMA)
    alpha = 1 / period
    raw_rma = (raw_rma * (period - 1) + tr) / period
    e *= (1 - alpha)
    atr = e > ε ? raw_rma / (1 - e) : raw_rma

    // Center line (SMA via circular buffer)
    middle = SMA(source, period)

    // Bands
    width = atr * multiplier
    upper = middle + width
    lower = middle - width

    return [middle, upper, lower]

Output Interpretation

Output	Description
middle	SMA of source (center line)
upper	Middle + scaled ATR (volatility-adjusted resistance)
lower	Middle - scaled ATR (volatility-adjusted support)

Performance Profile

Operation Count (Streaming Mode)

ATRBANDS combines an SMA running sum (center line), True Range computation, and Wilder's RMA with warmup compensation:

Operation	Count	Cost (cycles)	Subtotal
SUB (oldest from SMA sum)	1	1	1
ADD (new to SMA sum)	1	1	1
DIV (SMA = sum / count)	1	15	15
SUB (H - L)	1	1	1
SUB + ABS (H - prevC, L - prevC)	2	2	4
CMP (max of 3 for TR)	2	1	2
FMA (RMA: prev×(n-1)/n + TR/n)	1	4	4
MUL (multiplier × ATR)	1	3	3
ADD/SUB (middle ± width)	2	1	2
Total (hot)	12	—	~33 cycles

During warmup (compensator active):

Operation	Count	Cost (cycles)	Subtotal
MUL (e × (1 - α))	1	3	3
SUB (1 - e)	1	1	1
DIV (raw_rma / (1 - e))	1	15	15
CMP (e > ε)	1	1	1
Warmup overhead	4	—	~20 cycles

Total during warmup: ~53 cycles/bar; Post-warmup: ~33 cycles/bar.

Batch Mode (SIMD Analysis)

The SMA running sum and RMA recursion are both sequential. True Range computation is independent per bar and vectorizable:

Optimization	Benefit
True Range (3-way max)	Vectorizable with Vector.Max and Vector.Abs
RMA recursion	Sequential (IIR dependency)
SMA running sum	Sequential
Band arithmetic	Vectorizable in a post-pass

Resources

• Wilder, J.W. New Concepts in Technical Trading Systems. Trend Research, 1978. (Original ATR and Wilder's Smoothing)
• Keltner, C. "How to Use the 10-Day Moving Average Rule." Commodities, 1960. (EMA-centered ATR channel variant)
• Bollinger, J. Bollinger on Bollinger Bands. McGraw-Hill, 2001. (Standard deviation band alternative for comparison)