Adaptive Volatility Matrix [JOAT]Adaptive Volatility Matrix
Introduction
The Adaptive Volatility Matrix (AVM) is an advanced open-source volatility regime classification indicator that combines Bollinger Band Width Percentile (BBWP), ATR percentile analysis, regime transition prediction, volatility clustering detection, and historical regime statistics to classify market conditions into distinct volatility regimes. This indicator helps traders adapt their strategies to current market conditions by systematically identifying when volatility is expanding, contracting, or transitioning between regimes.
Unlike basic volatility indicators that simply plot ATR or Bollinger Bands, AVM employs a sophisticated dual-metric system that combines BBWP (measuring price range compression/expansion) with ATR percentile (measuring absolute volatility) to create a combined volatility score (0-100%). The indicator then classifies this score into five distinct regimes and predicts regime transitions through momentum analysis.
Why This Indicator Exists
This indicator addresses the challenge of adapting trading strategies to volatility conditions. Different market regimes require different approaches - mean reversion works in low volatility, breakout strategies work in expansion, and risk management becomes critical in extreme volatility. AVM systematically reveals:
BBWP Analysis: Measures Bollinger Band width percentile to identify compression/expansion cycles
ATR Percentile: Tracks normalized ATR percentile to measure absolute volatility levels
Combined Volatility Score: Weighted average (60% BBWP, 40% ATR) for robust regime classification
Regime Classification: Five distinct regimes (Extreme Expansion, Expansion, Normal, Contraction, Extreme Contraction)
Transition Prediction: Momentum-based forecasting of next regime with probability
Volatility Clustering: Detects sustained high/low volatility periods
Historical Statistics: Tracks regime duration and frequency for context
Each component provides unique intelligence. BBWP shows compression cycles, ATR shows absolute volatility, combined score provides robust classification, regime system categorizes conditions, transition prediction anticipates changes, clustering detects persistence, and statistics provide historical context.
Core Components Explained
1. BBWP (Bollinger Band Width Percentile) Calculation
BBWP measures where current Bollinger Band width ranks relative to historical width:
f_calculate_bbwp(int length, int lookback) =>
float basis = ta.sma(close, length)
float dev = ta.stdev(close, length)
float bb_width = (dev * 2) / basis * 100
// Calculate percentile rank
int count = 0
for i = 1 to lookback
if bb_width > nz(bb_width )
count += 1
float bbwp = (count / lookback) * 100
BBWP ranges from 0-100%:
- 0-20%: Extreme compression (volatility squeeze)
- 20-40%: Contraction (below average volatility)
- 40-60%: Normal (average volatility)
- 60-80%: Expansion (above average volatility)
- 80-100%: Extreme expansion (volatility breakout)
2. ATR Percentile Analysis
ATR percentile measures where current normalized ATR ranks historically:
f_atr_percentile(int period, int lookback) =>
float atr_val = ta.atr(period)
float natr = close > 0 ? (atr_val / close) * 100 : 0.0
float percentile = ta.percentrank(natr, lookback)
Normalized ATR (NATR) accounts for price level differences, making volatility comparable across different price ranges. Percentile ranking shows where current volatility sits in historical distribution.
3. Combined Volatility Score & Regime Classification
The combined score weights BBWP more heavily than ATR percentile:
float combined_score = (bbwp_value * 0.6) + (atr_percentile * 0.4)
f_classify_regime(float bbwp_val, float atr_perc, float exp_th, float con_th, float ext_th) =>
string regime = "Normal"
int regime_code = 0
if bbwp_val >= ext_th or atr_perc >= ext_th
regime := "Extreme Expansion"
regime_code := 4
else if bbwp_val >= exp_th or atr_perc >= exp_th
regime := "Expansion"
regime_code := 3
// Additional classifications...
Five regime classifications:
1. Extreme Contraction (code 1): Both metrics <30%, volatility squeeze
2. Contraction (code 2): One metric <40%, below average volatility
3. Normal (code 0): Both metrics 40-60%, average conditions
4. Expansion (code 3): One metric >70%, above average volatility
5. Extreme Expansion (code 4): Both metrics >85%, volatility breakout
4. Regime Transition Prediction
AVM predicts next regime through momentum analysis:
float regime_momentum = combined_score - combined_score
string momentum_direction = regime_momentum > 2 ? "Accelerating" :
regime_momentum < -2 ? "Decelerating" : "Stable"
string predicted_regime = regime_code == 4 and regime_momentum < -5 ? "→ Expansion" :
regime_code == 3 and regime_momentum < -3 ? "→ Normal" :
// Additional predictions...
"Stable"
float transition_prob = math.min(math.abs(regime_momentum) * 10, 100)
Transition probability (0-100%) based on momentum magnitude. >50% probability triggers warning.
5. Volatility Clustering Detection
Clustering identifies sustained high/low volatility periods:
int cluster_lookback = 20
float cluster_threshold = 70.0
int high_vol_count = 0
for i = 0 to cluster_lookback - 1
if combined_score >= cluster_threshold
high_vol_count += 1
float cluster_ratio = high_vol_count / cluster_lookback * 100
bool in_vol_cluster = cluster_ratio >= 60 // 60% of bars are high vol
string cluster_strength = cluster_ratio >= 80 ? "Strong" :
cluster_ratio >= 60 ? "Moderate" :
cluster_ratio >= 40 ? "Weak" : "None"
Clusters indicate persistent volatility conditions that tend to continue.
6. Historical Regime Statistics
AVM tracks regime history for context:
var array regime_history = array.new_int(0)
var array regime_durations = array.new_int(0)
if regime_changed
array.push(regime_history, regime_code)
array.push(regime_durations, bars_in_regime)
// Calculate statistics
float avg_expansion_duration = exp_sum / exp_cnt
float avg_contraction_duration = con_sum / con_cnt
float duration_ratio = bars_in_regime / avg_expansion_duration
bool regime_extended = duration_ratio > 1.5
Statistics show if current regime is extended (>1.5x average duration), suggesting potential transition.
Visual Elements
Combined Score Line: Main plot (0-100%) with regime-based coloring
ATR Percentile Overlay: Circles showing ATR percentile for comparison
Histogram: Gradient-colored bars showing volatility score with regime colors
Reference Lines: 70% (expansion), 50% (neutral), 30% (contraction), 85% (extreme)
Background Zones: Regime-colored backgrounds (purple for expansion, yellow for contraction)
Transition Warnings: ⚠ symbols when transition probability >50%
BBWP Percentile Bands: 20th, 50th, 80th percentile circles for context
Dashboard: Real-time metrics including regime, score, BBWP, ATR%, trend, duration, momentum, transition prediction, cluster status, duration ratio, historical stats
Input Parameters
BBWP Parameters:
BBWP Length: Bollinger Band period (default: 13)
BBWP Lookback: Historical comparison period (default: 252)
ATR Analysis:
ATR Period: ATR calculation period (default: 14)
ATR Percentile Lookback: Historical ranking period (default: 100)
Regime Classification:
Expansion Threshold: Score for expansion regime (default: 70%)
Contraction Threshold: Score for contraction regime (default: 30%)
Extreme Threshold: Score for extreme regimes (default: 85%)
Visualization:
Show Regime Zones: Toggle background coloring
Show Histogram: Toggle volatility histogram
Show ATR Overlay: Toggle ATR percentile circles
How to Use This Indicator
Step 1: Identify Current Regime
Check dashboard "Regime" row. Adjust strategy based on classification.
Step 2: Monitor Combined Score
Score >70% = expansion (use breakout strategies)
Score <30% = contraction (use mean reversion)
Score 40-60% = normal (use balanced approach)
Step 3: Check Momentum Direction
"Accelerating" = volatility increasing
"Decelerating" = volatility decreasing
"Stable" = no significant change
Step 4: Watch for Transition Warnings
⚠ symbols indicate >50% probability of regime change. Prepare to adjust strategy.
Step 5: Assess Cluster Status
"Strong" or "Moderate" cluster = persistent conditions likely to continue
Step 6: Consider Duration Ratio
Ratio >1.5x = extended regime, higher probability of mean reversion
Best Practices
Use regime classification to select appropriate trading strategies
Extreme contraction often precedes volatility breakouts - prepare for expansion
Extreme expansion often mean-reverts - reduce position sizes
Transition warnings provide early signal to adjust risk management
Volatility clusters suggest persistence - don't fight the regime
Extended regimes (>1.5x average) have higher reversal probability
BBWP and ATR percentile divergence suggests regime uncertainty
Historical statistics provide context for current regime duration
Combine with directional indicators - AVM shows conditions, not direction
Indicator Limitations
Regime classification is backward-looking - transitions lag actual changes
BBWP calculation is computationally intensive on large lookback periods
Transition predictions are probabilistic, not deterministic
Extreme regimes can persist longer than expected during major events
Historical statistics require sufficient data (50+ regime changes)
Clustering detection has fixed lookback - may miss longer-term patterns
Combined score weighting (60/40) may not be optimal for all instruments
Regime thresholds may need adjustment for different markets
Technical Implementation
Built with Pine Script v6 using:
Custom BBWP calculation with percentile ranking
ATR percentile analysis with normalized ATR
Weighted combined score (60% BBWP, 40% ATR)
Five-tier regime classification system
Momentum-based transition prediction with probability
Volatility clustering detection (20-bar lookback)
Historical regime tracking with arrays (last 50 regimes)
Duration ratio calculation vs historical averages
BBWP percentile bands (20th, 50th, 80th)
Adaptive background coloring based on regime and duration
Comprehensive dashboard with 12 metrics
The code is fully open-source and can be modified to suit individual trading styles.
Originality Statement
This indicator is original in its comprehensive volatility regime classification approach. While BBWP and ATR are established concepts, this indicator is justified because:
It combines BBWP and ATR percentile into weighted combined score for robust classification
The five-tier regime system provides granular volatility categorization
Momentum-based transition prediction with probability quantification is unique
Volatility clustering detection identifies persistent regime conditions
Historical regime statistics provide context for current regime duration
Duration ratio calculation identifies extended regimes with mean reversion potential
BBWP percentile bands add additional context layers
Adaptive background intensity based on regime stability
Each component contributes unique information: BBWP shows compression cycles, ATR shows absolute volatility, combined score provides robust classification, regime system categorizes conditions, transition prediction anticipates changes, clustering detects persistence, statistics provide context, and duration ratio identifies extremes. The indicator's value lies in presenting these complementary perspectives simultaneously with unified regime framework.
Disclaimer
This indicator is provided for educational and informational purposes only. It is not financial advice. Regime classifications do not guarantee future volatility behavior. Trading involves substantial risk of loss. Past performance does not guarantee future results. Always use proper risk management and never risk more than you can afford to lose.
-Made with passion by officialjackofalltrades
Pine Script® indicator






















