Volatility Percentile [EXCAVO]

ATR Percentile Rank with Four-State Volatility Classification and Trend Detection

The Volatility Percentile measures where the current Average True Range stands
relative to its own history using a percentile rank. Rather than comparing ATR to a
fixed threshold, the indicator continuously evaluates whether current volatility is
low, normal, elevated, or extreme relative to the recent distribution - adapting
automatically to each instrument and timeframe.

This is not a basic ATR display. The percentile rank provides a normalized, context-aware
measure of volatility that remains comparable across assets, timeframes, and market cycles.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
▸ HOW TO USE

Step 1 → Add the indicator to a new pane. The histogram appears immediately,
colored by the current volatility state (blue, gray, orange, or red).
Step 2 → Read the state from the histogram color and dashboard. Blue = Low,
Gray = Normal, Orange = Elevated, Red = Extreme.
Step 3 → Note the percentile value. Above 80% indicates the current ATR is
in the top 20% of its historical range - unusually wide price swings.
Below 25% indicates unusually quiet conditions.
Step 4 → Check the Vol Trend row in the dashboard. RISING means the ATR is
accelerating above its 20-bar average. FALLING means it is contracting.
Step 5 → Set up state-change alerts to receive notifications when volatility
transitions between states on bar close.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
▸ HOW IT CALCULATES

◆ ATR Percentile Rank
The indicator computes ATR(length) on each bar, then applies ta.percentrank() over
the lookback period. The percentile rank answers: "Out of the last N bars, what
percentage had an ATR lower than today's?" A result of 80 means 80% of recent bars
had a smaller ATR - current volatility is in the top 20% historically. The rank
always falls between 0 and 100, making it directly comparable across instruments.

◆ Smoothing
The raw percentile rank is passed through a simple moving average of configurable
length (default 3 bars). This suppresses single-bar spikes that would otherwise
cause false state transitions. The smoothed value is used for both the histogram
display and state classification. Setting smoothing to 1 disables it entirely.

◆ Four-State Classification
The smoothed percentile is compared against three configurable thresholds to assign
one of four states: Low (below 25th percentile), Normal (25th to 60th), Elevated
(60th to 80th), or Extreme (above 80th). State boundaries are user-adjustable,
allowing calibration for instruments that spend more time at elevated volatility
levels (such as crypto) versus lower-volatility markets.

◆ Volatility Trend
A secondary calculation compares the current ATR to its 20-bar simple moving average.
ATR above 105% of the SMA is classified as RISING. ATR below 95% of the SMA is
classified as FALLING. Between those bands the trend is STABLE. This early-warning
layer detects momentum in volatility before a state boundary is crossed.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
▸ WHAT MAKES IT DIFFERENT

◆ Percentile Rank vs Fixed Threshold
A fixed ATR threshold (e.g., "ATR > 500 = high volatility") fails when applied across
different instruments or timeframes. The percentile approach self-calibrates: the same
indicator works on BTCUSD hourly and EURUSD daily without parameter changes, because
it measures volatility relative to the instrument's own recent history.

◆ Four States Instead of Two
Most volatility filters use a binary high/low split. Separating Normal from Elevated
and Extreme provides more granular awareness: Elevated volatility may still be
tradable, while Extreme conditions warrant a different approach to position sizing.
The four-state model also makes transitions visible earlier - Elevated appears before
Extreme is reached.

◆ Volatility Trend Detection
The Vol Trend layer detects whether ATR is currently accelerating or decelerating,
independently of which state it is in. It is possible to be in Normal state with
RISING trend (volatility building) or in Elevated state with FALLING trend
(volatility contracting back toward normal). This combination is visible only in the
dashboard and is not represented by the histogram color alone.

◆ ATR / Price Ratio
The dashboard shows ATR expressed as a percentage of the current close price. This
normalized measure is directly comparable across instruments and useful for estimating
stop distance relative to price without manual calculation.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
▸ DASHBOARD

Real-time panel showing current volatility conditions:

• State - active volatility state (LOW / NORMAL / ELEVATED / EXTREME), colored by type
• Percentile - current smoothed ATR percentile rank (0-100%)
• ATR - raw ATR value in price units for the current bar
• ATR / Price - ATR expressed as a percentage of close price
• Vol Trend - volatility momentum (RISING / FALLING / STABLE) vs 20-bar ATR average
• Lookback - active lookback period used for percentile calculation

Legend table (bottom left) explains histogram colors and boundary lines. Both panels
toggle in Dashboard settings.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
▸ SETTINGS

Engine

• ATR Length - 14 bars (period for Average True Range calculation)
• Lookback Period - 200 bars (history window for percentile rank)
• Smoothing - 3 bars (applied to raw percentile; 1 = no smoothing)

State Thresholds

• Low / Normal - 25 (percentile boundary between Low and Normal states)
• Normal / Elevated - 60 (percentile boundary between Normal and Elevated states)
• Elevated / Extreme - 80 (percentile boundary between Elevated and Extreme states)

Visualization

• Low Vol Color - default blue
• Extreme Vol Color - default red
• Elevated Vol Color - default orange
• Show State Ribbon - OFF (colored markers at pane bottom)
• Background Highlight - ON (subtle tint matching active state)

Alerts

• JSON Alerts - OFF (enable for bot integration)

Dashboard

• Dashboard Position - Top Right
• Show Dashboard - ON
• Show Legend - ON

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
▸ ALERTS

• Extreme Volatility - state transitioned to Extreme on bar close
• Elevated Volatility - state transitioned to Elevated on bar close
• Normal Volatility - state transitioned to Normal on bar close
• Low Volatility - state transitioned to Low on bar close
• Volatility State Change - any state transition detected on bar close

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Best regards,
EXCAVO

Disclaimer
Trading involves significant risk. This indicator is a technical analysis tool
and does not constitute financial advice, investment recommendations, or a
guarantee of future results. Past indicator behavior does not guarantee future
performance. Always use proper risk management and your own judgment.