QuanTAlib/lib/channels/atrbands/atrbands.md

# ATRBANDS: ATR Bands

## Overview and Purpose

ATR Bands (Average True Range Bands) are a volatility-based indicator that creates an adaptive price envelope using the Average True
Range (ATR) to determine the band width. Unlike fixed percentage bands, ATR Bands dynamically adjust to changing market conditions,
expanding during volatile periods and contracting during calmer markets. This approach provides traders with support and resistance
levels that reflect the security's actual volatility rather than arbitrary fixed percentages, offering more relevant trading signals
across different market environments.

The implementation provided uses an efficient circular buffer approach for SMA and ATR calculations, ensuring optimal performance while
properly handling data gaps. By deriving band width directly from the ATR—a proven measure of market volatility—these bands
automatically expand when volatility increases and contract when markets calm, creating a volatility-normalized trading channel that
adapts to each security's specific characteristics.

## Core Concepts

* **Volatility-adaptive envelope:** Bands automatically widen during volatile periods and narrow during calm markets, providing dynamic
support/resistance levels
* **Centered structure:** Uses a simple moving average (SMA) of the price as the middle line, providing a reference point for mean
reversion
* **ATR-based width:** Calculates band width using ATR multiplied by a configurable factor, making the bands proportional to actual
market volatility
* **Customizable sensitivity:** Adjustable multiplier allows traders to fine-tune the bands to different trading styles, timeframes,
and market conditions

ATR Bands improve upon traditional percentage-based bands by incorporating the ATR, which measures volatility based on a security's
true range (accounting for gaps). This approach ensures that the bands expand precisely when they should—during periods of high
volatility—creating a more responsive and market-adaptive trading framework.

## Common Settings and Parameters

| Parameter | Default | Function | When to Adjust |
| --------- | ------- | -------- | -------------- |
| Period | 20 | Lookback period for both SMA and ATR calculations | Shorter (10-15) for more responsiveness to recent volatility; longer (30-50) for more stable bands and filtered signals |
| ATR Multiplier | 2.0 | Determines band width as a multiple of ATR | Higher (2.5-3.0) for wider bands and fewer signals; lower (1.0-1.5) for tighter bands and more frequent signals |
| Source | Close | Price data for the center line calculation | Can be modified to use typical price (hlc3) for a more balanced view of price action |

**Pro Tip:** For a comprehensive trading framework, try using multiple ATR Band settings simultaneously. A narrower band (1.0-1.5× ATR)
can help identify minor retracements and short-term entry points, while a wider band (2.5-3.0× ATR) can be used for major
support/resistance zones and stop placement.

## Calculation and Mathematical Foundation

**Simplified explanation:**
ATR Bands first calculate a middle band using a simple moving average of the source price. They then create upper and lower bands by
adding or subtracting the ATR (multiplied by a factor) from this middle line.

**Technical formula:**

Middle Band = SMA(Source, Period)
Upper Band = Middle Band + ATR(Period) × Multiplier
Lower Band = Middle Band - ATR(Period) × Multiplier

Where:
* SMA = Simple Moving Average
* ATR = Average True Range calculated using Wilder's smoothing
* Period = Lookback period for calculations
* Multiplier = Factor for band width

> 🔍 **Technical Note:** The implementation uses optimized circular buffers to maintain rolling sums for SMA calculations and Wilder's
smoothing method for ATR, ensuring O(1) computational complexity regardless of the lookback period. The ATR calculation includes proper
initialization handling for early bars, with bias correction that prevents the common "warm-up effect" seen in many ATR
implementations.

## Performance Profile

### Operation Count (Streaming Mode, Scalar)

Per-bar cost for SMA + ATR computation:

| Operation | Count | Cost (cycles) | Subtotal |
| :--- | :---: | :---: | :---: |
| ADD/SUB | 6 | 1 | 6 |
| MUL | 4 | 3 | 12 |
| DIV | 1 | 15 | 15 |
| CMP/MAX | 2 | 1 | 2 |
| FMA | 1 | 4 | 4 |
| **Total** | **14** | — | **~39 cycles** |

**Complexity**: O(1) per bar — SMA uses running sum, ATR uses Wilder's IIR smoothing.

### Batch Mode (SIMD/FMA Analysis)

ATR has IIR dependency; SMA running sum also has sequential dependency:

| Operation | Scalar Ops | SIMD Benefit | Notes |
| :--- | :---: | :---: | :--- |
| SMA update | 3 | 1× | Running sum dependency |
| ATR update | 5 | 1× | Wilder smoothing (IIR) |
| Band computation | 4 | 2× | Upper/lower parallel |

**Batch efficiency (512 bars):**

| Mode | Cycles/bar | Total (512 bars) | Improvement |
| :--- | :---: | :---: | :---: |
| Scalar streaming | 39 | 19,968 | — |
| Partial SIMD | ~35 | ~17,920 | **~10%** |

SIMD benefit is limited due to IIR dependencies in both components.

### Quality Metrics

| Metric | Score | Notes |
| :--- | :---: | :--- |
| **Accuracy** | 10/10 | Exact SMA and ATR calculation |
| **Timeliness** | 7/10 | SMA introduces (period-1)/2 lag |
| **Overshoot** | 8/10 | ATR adapts smoothly to volatility changes |
| **Smoothness** | 8/10 | Wilder smoothing provides stable envelope |

## Interpretation Details

ATR Bands provide several analytical frameworks for trading decisions:

* **Mean reversion opportunities:** Price touching or briefly exceeding a band often suggests a potential reversal toward the middle
band, especially in range-bound markets
* **Trend strength assessment:** In strong trends, price will regularly touch or slightly exceed the band in the trend direction while
respecting the opposite band
* **Breakout confirmation:** Sustained price movement beyond a band after a period of contraction often signals a genuine breakout
rather than a false move
* **Volatility shifts:** Sudden expansion of band width indicates increasing volatility that may precede significant price moves
* **Support and resistance framework:** The middle band often acts as the first support/resistance level, while the outer bands
represent more significant levels
* **Stop placement guide:** The bands provide logical stop-loss placement points based on a security's actual volatility
* **Timeframe alignment:** Comparing ATR Bands across multiple timeframes can identify high-probability setups where support/resistance
aligns

## Limitations and Considerations

* **Lagging nature:** As a moving average-based indicator incorporating ATR, the bands react to volatility changes with some delay
* **Parameter sensitivity:** Performance varies significantly based on period and multiplier settings, requiring optimization for
specific securities
* **False signals in trending markets:** Band touches may not indicate reversals during strong trends, potentially leading to premature
position exits
* **Complementary tool requirement:** Most effective when combined with trend identification and momentum indicators
* **Volatility regime changes:** During sudden extreme volatility spikes, bands may widen with a delay, potentially after the optimal
entry/exit point
* **Lookback period trade-offs:** Shorter periods increase responsiveness but also noise; longer periods provide stability but increase
lag
* **Mean reversion assumption:** Implicitly assumes prices will revert to the mean (middle band), which doesn't always hold in strongly
trending markets

## References

* Wilder, J. W. (1978). New Concepts in Technical Trading Systems. Trend Research.
* Kaufman, P. J. (2013). Trading Systems and Methods (5th ed.). John Wiley & Sons.
* Murphy, J. J. (1999). Technical Analysis of the Financial Markets. New York Institute of Finance.
* Brooks, A. (2006). Reading Price Charts Bar by Bar. John Wiley & Sons.
* Elder, A. (2014). The New Trading for a Living. John Wiley & Sons.