QuanTAlib/lib/volatility/bbwn/Bbwn.md

BBWN: Bollinger Band Width Normalized

Property	Value
Category	Volatility
Inputs	Source (close)
Parameters	period, multiplier (default 2.0), lookback (default 252)
Outputs	Single series (Bbwn)
Output range	\geq 0
Warmup	period + lookback bars

TL;DR

• Bollinger Band Width Normalized (BBWN) extends the standard BBW by normalizing it to a [0,1] range based on historical minimum and maximum values o...
• Parameterized by period, multiplier (default 2.0), lookback (default 252).
• Output range: \geq 0.
• Requires period + lookback bars of warmup before first valid output (IsHot = true).
• Validated against TA-Lib, Skender, and Tulip reference implementations where available.

"Normalization transforms volatility chaos into comparable signals."

Bollinger Band Width Normalized (BBWN) extends the standard BBW by normalizing it to a [0,1] range based on historical minimum and maximum values over a lookback period. This normalization enables better comparison across different timeframes, instruments, and market conditions, making it easier to identify relative volatility levels consistently.

Historical Context

While Bollinger Band Width (BBW) effectively measures volatility expansion and contraction, its absolute values can vary dramatically across different assets and timeframes. A BBW of 0.05 might be low for a volatile stock but high for a stable bond. BBWN solves this problem by creating a normalized scale.

The normalization concept comes from technical analysis standardization techniques, similar to those used in oscillators like RSI or Stochastic. By tracking the historical range of BBW values and expressing the current BBW as a position within that range, BBWN provides a consistent 0-100% scale where:

• 0% = Lowest volatility in the lookback period (maximum squeeze)
• 100% = Highest volatility in the lookback period (maximum expansion)
• 50% = Mid-range volatility when no historical range exists

Architecture & Physics

BBWN builds upon BBW calculation and adds historical normalization:

Step 1: Standard BBW Calculation

BBW_t = \frac{2k \times \sigma_t}{SMA_t}

Where:

• k: Multiplier (default 2.0)
• \sigma_t: Standard deviation at time t
• SMA_t: Simple moving average at time t

Step 2: Historical Min/Max Tracking

For a lookback period L (default 252), track:

BBW_{min} = \min(BBW_{t-L+1}, ..., BBW_t)

BBW_{max} = \max(BBW_{t-L+1}, ..., BBW_t)

Step 3: Normalization

BBWN_t = \begin{cases}
\frac{BBW_t - BBW_{min}}{BBW_{max} - BBW_{min}} & \text{if } BBW_{max} > BBW_{min} \\
0.5 & \text{otherwise}
\end{cases}

The result is clamped to [0, 1] to ensure bounds.

Implementation Features

Performance Optimizations

1. O(1) BBW Calculation: Uses running variance with sum-of-squares method
2. Circular Buffers: Both price data and BBW history use ring buffers
3. Incremental Min/Max: Recalculates min/max only when necessary
4. Resync Protection: Periodically recalculates sums to prevent drift

Data Integrity

• NaN/Infinity Handling: Invalid inputs use last valid value
• Zero Division Protection: Handles constant price sequences
• Numerical Stability: Uses epsilon checks for floating-point comparisons

Performance Profile

Operation Count (Streaming Mode)

BBWN chains BBW computation (SMA + StdDev of N bars) with min/max normalization over a lookback window — O(1) amortized.

Operation	Count	Cost (cycles)	Subtotal
Running sum_x, sum_x2 (StdDev O(1))	2	2 cy	~4 cy
sqrt(variance) for StdDev	1	14 cy	~14 cy
BBW = 2kStdDev / SMA	1	5 cy	~5 cy
RingBuffer min update (lookback)	1	4 cy	~4 cy
RingBuffer max update (lookback)	1	4 cy	~4 cy
BBWN = (BBW - min) / (max - min)	1	5 cy	~5 cy
Zero-range guard (constant series)	1	2 cy	~2 cy
NaN guard + state update	1	2 cy	~2 cy
Total	O(1)	—	~40 cy

O(1) per bar. Two chained O(1) computations: BBW (running variance) + min/max normalization (RingBuffer monotonic deque). sqrt() is the dominant latency.

Batch Mode (SIMD Analysis)

Operation	Vectorizable?	Notes
Running sum_x, sum_x2	Yes	Vector accumulation
sqrt(variance)	Yes	Vector.Sqrt() or Avx.Sqrt
BBW from StdDev/SMA	Yes	Vector divide
Min/max tracking	Partial	Sequential dependency for running extremes
Normalization division	Yes	Vector divide with zero-guard

Batch path can vectorize the BBW computation phase (4 bars per AVX2 cycle). Min/max phase is partially sequential. Overall ~2-3× batch speedup over scalar.

Usage Examples

Basic Setup

// Default: 20-period BBW, 2.0 multiplier, 252-day lookback
var bbwn = new Bbwn(20, 2.0, 252);

foreach (var price in prices)
{
    var result = bbwn.Update(new TValue(DateTime.Now, price));
    Console.WriteLine($"BBWN: {result.Value:F4}");
}

Custom Parameters

// Short-term squeeze detection: 10-period, 1.5 multiplier, 50-day lookback
var shortTermBbwn = new Bbwn(10, 1.5, 50);

// Long-term volatility: 50-period, 2.5 multiplier, 500-day lookback  
var longTermBbwn = new Bbwn(50, 2.5, 500);

Batch Processing

var source = new TSeries(times, prices);
var bbwnSeries = Bbwn.Calculate(source, period: 20, multiplier: 2.0, lookback: 252);

for (int i = 0; i < bbwnSeries.Count; i++)
{
    Console.WriteLine($"{bbwnSeries.Times[i]}: {bbwnSeries.Values[i]:F4}");
}

Trading Applications

Volatility Regime Detection

if (bbwn.Last.Value < 0.2)
{
    Console.WriteLine("Low volatility regime - potential squeeze");
}
else if (bbwn.Last.Value > 0.8) 
{
    Console.WriteLine("High volatility regime - potential reversal zone");
}

Breakout Confirmation

var previousBbwn = bbwn.Last.Value;
// ... update with new price ...
var currentBbwn = bbwn.Last.Value;

if (previousBbwn < 0.3 && currentBbwn > 0.5)
{
    Console.WriteLine("Volatility expansion - potential breakout confirmed");
}

Multi-Timeframe Analysis

var dailyBbwn = new Bbwn(20, 2.0, 252);   // Daily squeeze
var hourlyBbwn = new Bbwn(20, 2.0, 252);  // Hourly expansion

// Trade when daily is squeezed but hourly is expanding
if (dailyBbwn.Last.Value < 0.2 && hourlyBbwn.Last.Value > 0.6)
{
    Console.WriteLine("Multi-timeframe breakout setup");
}

Key Characteristics

Advantages

• Scale Independence: Normalized values work across all instruments
• Historical Context: Compares current volatility to recent history
• Consistent Signals: 0-100% scale enables consistent thresholds
• Regime Detection: Clearly identifies volatility regimes

Limitations

• Lookback Dependency: Normalization quality depends on lookback period
• Lag: Historical normalization adds slight lag to signals
• Range Bound: Extreme volatility may still be constrained to [0,1]
• Parameter Sensitivity: Multiple parameters need optimization

Parameter Guidelines

Parameter	Typical Range	Default	Purpose
Period	5-50	20	BBW calculation period
Multiplier	1.0-3.0	2.0	Band width scaling
Lookback	50-500	252	Historical normalization range

Period Selection

• Short (5-15): Sensitive to recent volatility changes
• Medium (16-30): Balanced sensitivity and stability
• Long (31-50): Smoother, longer-term volatility trends

Lookback Selection

• Short (50-100): More responsive to regime changes
• Medium (150-300): Balanced historical context
• Long (400+): Stable long-term perspective

Mathematical Properties

Range and Bounds

• Output Range: [0, 1] by design
• Convergence: Values stabilize after lookback period
• Monotonicity: Not guaranteed due to normalization updates

Statistical Properties

• Distribution: Depends on underlying price process
• Mean Reversion: Normalization creates artificial mean reversion
• Serial Correlation: Inherits from underlying BBW

Alternative Formulations

Percentile-Based Normalization

Instead of min/max, use percentiles for robustness:

BBWN_t = \frac{BBW_t - P_{10}(BBW)}{P_{90}(BBW) - P_{10}(BBW)}

Z-Score Normalization

Standardize BBW using mean and standard deviation:

BBWN_t = \frac{BBW_t - \mu_{BBW}}{\sigma_{BBW}}

Exponential Smoothing

Weight recent history more heavily:

BBWN_t = \frac{BBW_t - EMA_{min}(BBW)}{EMA_{max}(BBW) - EMA_{min}(BBW)}

Implementation Notes

Edge Cases

1. Constant Prices: When BBW is always zero, BBWN defaults to 0.5
2. Single Value: With only one BBW value, BBWN returns 0.5
3. Numerical Precision: Uses epsilon comparisons for floating-point safety

Performance Considerations

• Memory Usage: O(period + lookback) for circular buffers
• CPU Complexity: O(1) per update, O(lookback) for min/max search
• Batch Processing: Optimized vectorized calculations available

BBWN transforms absolute volatility measurements into relative, comparable signals that work consistently across different market conditions and instruments. The normalization provides context that pure BBW cannot offer, making it particularly valuable for systematic trading strategies that need consistent volatility thresholds.