ATR Volatility Regime [NovaLens]Volatility regime tool built to separate two things ATR alone cannot tell you apart: where volatility currently sits in its own rolling history, and which direction the regime is rotating. Adds a velocity-gated release event on top, so the indicator flags fast coiled-spring releases on the confirmed bar - and refuses to fire on the slow leaks that only look like one.
Most volatility tools collapse one axis. A raw ATR plot tells you the bar range and nothing about whether that range is rare. A percentile-rank histogram tells you the rank but not whether vol is loading or unloading. ATR Volatility Regime separates the two by design:
Tier tracks where volatility sits in its own rolling history (Compression / Quiet / Normal / Elevated).
Phase tracks where volatility is rotating (Rising / Topping / Falling / Bottoming).
A Compression reading is not a breakout signal. It is the market saying "vol is loaded." Whether it actually releases depends on the next move. When a sustained compression actually breaks above mid-rank within a 5-bar velocity window, the indicator prints a Release diamond and pulses the pane background. Slow leaks that drift through Quiet for more than 5 bars are canceled, not reported. That single gate is what separates a real coiled-spring release from a sideways drift.
════════════════════════════════════════════
◉ HOW IT WORKS
The vol input. Wilder ATR over the chosen length, expressed as a percentage of close so the read is comparable across price levels and instruments. Mathematically guarded to stay clean across historical data gaps and unusual price series.
The percentile rank. The current ATR% is ranked against its own rolling lookback window (100 / 200 / 300 bars by Horizon). This is an asset-calibrated percentile - "P75 on BTC" means "vol higher than 75% of the last 200 BTC readings," not a market-wide cutoff. The same indicator works across SPY, BTC, EURUSD, and XAU without retuning. The raw rank drives the state engine; an EMA-smoothed copy drives the visual line so the plot reads calm without numbing event detection. Warm-up is honest: until the lookback fills, the panel shows "Warming up" and refuses to assign a tier. NA never collapses to a fake Normal.
The tier model. Four tiers cut on rawRank (P25, P50, P75) with asymmetric hysteresis: 1 confirmed bar to step up (so a vol breakout is not missed), 3 confirmed bars to step down (so a tier change only confirms when vol has actually died). The ribbon fill and oscillator line both color by tier. Extreme is a signal class, not a tier; it would flicker on and off at the P90 boundary if we colored the ribbon by it.
The phase model. Four phases (Rising / Topping / Falling / Bottoming) read off the rawRank slope. Slow rotations need 2 bars of confirmation to flip; violent moves with |delta rank| > 15 bypass the confirm and flip immediately. Peak and trough detection is plateau-aware: a strict ( greater-than on both sides) check missed the patterns where ATR percentile pins at 100 for multiple bars, so the algorithm uses greater-or-equal on the left side and greater-than on the right.
The events. Three signature events, each with its own gating:
Compression Release : velocity-gated. The Compression tier must run at least 10 bars to load the spring; on exit, rawRank must reach the mid (>= 50) within a 5-bar window. Slow leaks that drift through Quiet for more than 5 bars are canceled. Re-entering Compression also cancels the pending episode.
Extreme Touch : rawRank peaks at >= 90. Re-arm runs through a three-valve cascade (rank drop to <= 75, a higher pivot with a +2 rank headroom so a 98 peak after a 97 cannot re-fire, or 2x lookback time decay) so the same Extreme arc cannot duplicate-fire, but a genuinely higher pivot in the same arc still counts.
Cooling : armed when an Extreme fires; fires on the first confirmed bar after where rawRank falls below 75 within a 10-bar window. Disarms on fire or when the window expires. The armed-latch architecture means fast drops out of an Extreme are tracked after the Extreme event arms Cooling, instead of relying on a single fragile cross check that would miss the drop if the threshold was already crossed on the Extreme bar itself.
The Playbook Lens. Pure interpretation layer. Engine, percentile, tier, phase, and objective events are identical across lenses. The Lens recolors three visual surfaces only: the panel Playbook row text and tone, the Playbook Heatmap Strip at y = -5, and an optional Tint Price Candles by Playbook Fit overlay. Switching the Lens dropdown answers a different question against the same volatility truth: "does this regime align with the workflow I am running?" - context, never a directive.
════════════════════════════════════════════
◈ HOW TO READ IT
The pane shows the smoothed percentile rank line wrapped in a tier-colored ribbon with a Volatility Glow halo that breathes wider in the loaded zones (Compression and Extreme) and tightens in Normal. Threshold lines mark P25, P50, P75, and P90.
Deep blue (Compression): rawRank in [0, 25). Loaded spring.
Light blue (Quiet): rawRank in [25, 50). Below median, not stretched.
Gray (Normal): rawRank in [50, 75). Typical bar ranges.
Orange (Elevated): rawRank in . High vol relative to recent history.
Red (Extreme): event color, not a tier. Drives Extreme Touch markers.
Teal (Release): event color, not a tier. Drives Compression Release markers.
Markers, in order of conviction:
Compression Release (diamond on the line, Release color, with a matching pane background pulse): a >= 10 bar compression run resolved into Normal+ within 5 bars. Non-directional by design - a volatility state change, not a price direction call.
Extreme Touch (small circle anchored to the actual peak bar, Extreme color): rawRank just peaked at or above the 90th percentile of its rolling history. Reads as topping pressure of vol, not a directional reversal call.
Cooling (panel-only event, no chart marker): the first confirmed bar after an Extreme where rawRank fell back below 75 within a 10-bar window. Surfaces in the Last Event row and the Cooling alert.
The info panel synthesizes six rows: Volatility (tier + P-Score), Flow (phase), Age (bars in tier + the per-tier duration percentile so a 200-bar Quiet stretch is compared against historical Quiet stretches, not Elevated), Last Event / Context (state-based decay, no fixed timer), ATR Range (current bar range as % of price, with absolute price-unit ATR in the row tooltip), and Playbook (the Lens context read).
The Last Event row uses state-based decay , not an arbitrary 10-bar timer. A Compression Release stays visible while phase is Rising or tier is Normal+. An Extreme Touch stays visible while tier is Elevated. A Cooling read stays visible while tier is Normal or Elevated. When the event's regime context expires, the row returns to Context and summarizes the current regime instead of resizing or disappearing.
════════════════════════════════════════════
✦ HOW WE USE IT: THE COILED-SPRING ARC
This is the arc the indicator is built to catch - not the only path. Many compressions resolve sideways without a confirmed release, and the velocity gate is what filters those out.
A common pattern on a liquid index or crypto chart, Swing profile (default), Neutral lens: the line drops into Compression and parks there for 15-30 bars. The ribbon turns deep blue, the Glow widens, and the panel Age row may read something like "Mature · 22 bars" or "Extended · 22 bars" - meaning the current run has already lasted longer than most recent Compression stretches on this market. The spring is loaded.
The full arc reads in four panel updates:
Release. rawRank reaches 50+ within the 5-bar velocity window after exiting Compression. A Release diamond prints on the line, the pane background pulses teal for one bar, and the Last Event row reads "Compression Release".
Run. Within a few bars the tier transitions through Normal into Elevated, the phase row flips Rising, and the smoothed line climbs toward the upper distribution.
Touch. If the move keeps loading, rawRank peaks at 92-98 and an Extreme Touch circle prints on the peak bar - the smoothed line is now in the upper edge of its own rolling distribution. The Last Event row updates to "Extreme Touch".
Unwind. Within 10 bars rawRank falls below 75. Cooling fires and the Last Event row updates again.
The Playbook Lens reframes the same arc without changing a number. Flip to Breakout: the Heatmap Strip lights teal during the release window (favorable) and dims toward red as the move stretches into Extreme (less favorable). Flip to Mean Reversion: the strip stays red through the release (vol is the wrong direction for fading) and only lights teal when Cooling confirms and tier drifts back through Normal toward Quiet. Flip to Risk Control: Compression marks calmer bar-range context, Elevated and Extreme mark the wider-bar context. Same volatility truth, different playbook fit. The engine is identical across lenses; only the interpretation layer changes.
════════════════════════════════════════════
✦ OTHER APPLICATIONS
Breakout context : Compression Release diamonds after a loaded quiet regime, optionally combined with the Heatmap Strip reading favorable under the Breakout lens
Trend context : Rising Elevated or Rising Normal volatility as movement context for an external trend plan
Mean-reversion context : quieter or cooling regimes that may be more suitable for contained-range workflows
Volatility risk overlay : Elevated and Extreme states as wider-bar context when reviewing size, stops, or trade frequency
Vol regime classifier : use the Volatility row + Flow row in the panel as a top-down filter for any external trade plan, independent of the Lens
Alert-driven workflow : subscribe to Compression Release + Extreme Touch + Cooling and check the chart only when the volatility regime actually changes, not every bar
════════════════════════════════════════════
⚙ GETTING STARTED
ATR Volatility Regime ships with three pre-tuned Horizon profiles plus a Custom override. Pick a horizon and start reading the regime:
Intraday : ATR 14, lookback 100, smoothing 3. Faster events, lighter hysteresis (1 up / 2 down). Use on 1m through 1H charts.
Swing (default) : ATR 14, lookback 200, smoothing 5. Balanced. Start here on 1H through 1D charts.
Long-Term Hold : ATR 20, lookback 300, smoothing 5. Slower, rarer events, heavier hysteresis (2 up / 3 down). Use on 1D and above.
Custom : full manual control of ATR Period, Lookback Window, and Smoothing.
Core settings:
Horizon : selects the tuning bundle above. Start with Swing.
ATR Period (Custom) : Wilder ATR period for the volatility input, in BARS. 14 is the standard. Shorter = more reactive; longer = smoother. Applies only when Horizon = Custom.
Lookback Window (Custom) : rolling lookback the ATR% is percentile-ranked against. Larger = smoother distribution, fewer extreme reads, slower compression releases. Smaller = sharper, more events.
Smoothing (EMA) (Custom) : EMA bars applied to the percentile-rank for the visual DISPLAY layer (plot, ribbon, panel readouts). The RAW rank still drives tier, phase, and events - smoothing only calms the visual. Set to 1 to disable smoothing.
Playbook Lens:
Neutral (default) : factual regime read, heatmap stays gray. Use this to learn the engine.
Breakout : range-expansion context. Loaded Compression and Compression Release read favorable; already-stretched Elevated or Extreme states shift toward caution.
Trend : directional-movement context. Rising Elevated and Rising Normal regimes read favorable; topping or cooling volatility shifts toward caution.
Mean Reversion : contained-range context. Quiet, Cooling, and Normal/Falling regimes read favorable; Release, Elevated, and Extreme regimes shift toward caution.
Risk Control : stretched-volatility context. Compression reads calm; Elevated and Extreme states warn that bar ranges are wide.
The Lens NEVER changes the engine - same tier, same phase, same Compression Release, same Extreme Touch, same alerts. Only the panel Playbook row text, the Heatmap Strip color, and the optional candle tint move.
Display:
Show Compression Releases (hero): diamond on the line + pane background pulse on release. On by default.
Show Extreme Touches : circle on the peak bar at rawRank >= 90. On by default.
Show Price Chart Markers : mirrors Compression Release diamonds and Extreme bar tints onto the price chart. OFF by default to keep the price chart clean.
Show Raw Rank Line : faint unsmoothed percentile rank line behind the smoothed display line. OFF by default. Toggle on to debug fast vol changes.
Show Volatility Glow : halo that widens at the loaded extremes (Compression and Extreme) and tightens in Normal. On by default.
Show Info Panel : 6-row state panel. On by default.
Panel Position : Top Right (default), Top Left, Bottom Right, Bottom Left, Middle Right.
Theme : Auto (detect chart background), Dark, or Light.
Show Playbook Heatmap Strip : thick band at y = -5 that recolors with the Lens. On by default.
Tint Price Candles by Playbook Fit : paints price-chart candles with the Release / Extreme palette per the active Lens. OFF by default; disabled automatically when Lens = Neutral.
Appearance / Palette (6 color pickers):
Compression, Quiet, Normal, Elevated, Extreme, Release - each on its own line with a state-explainer tooltip. The Display Rank line, Raw Rank, Tier Ribbon fill, Volatility Glow, Heatmap Strip, panel tier text, candle tints, and event markers all reference these inputs so users can adapt the palette (color-blind, light-mode, brand themes) without forking the script.
════════════════════════════════════════════
△ LIMITATIONS
Warm-up : the lookback window must fill before any tier is assigned. On Swing (200) that is 200 bars; on Long-Term Hold (300) that is 300. Until then, the panel shows "Warming up" and the state engine refuses to fake a Normal read.
Visual smoothing lag : the visible line is intentionally calmer than the raw engine. ATR is a backward-looking Wilder-smoothed measure, and the display line is lightly EMA-smoothed on top, so fast volatility expansions can look slightly delayed in the visible plot. The rawRank engine is the sharper layer underneath and is what actually drives the tier, phase, events, and alerts. The smoothed line is the readable copy; do not read a slight visual delay as the event engine being slow.
Percentile is relative, not absolute : a "Compression" read on a chronically quiet asset can still be wider than an "Elevated" read on a chronically loud asset. The indicator compares each asset against ITS OWN history, not across markets.
Regime shifts shrink the window : a structural vol regime change (e.g. a quiet 2-year period followed by a sustained higher-vol regime) takes about one lookback window to fully recalibrate. The first few weeks after a regime shift can read noisier than the steady-state.
Compression Release is non-directional : the diamond and the pane pulse tell you the spring released, not which way price went. Combine with directional context (trend, structure, or a separate momentum tool) for direction.
Extreme Touch is a state read, not a reversal call : rawRank pinning above 90 means vol is rare for this market; it does not mean price is about to reverse. Cooling tells you the unwind has begun, not where the next leg goes.
Playbook Lens is interpretation, not validation : the Heatmap Strip recolors regime context based on the active Lens. It is not a backtested edge - it is a quick visual answer to "does my workflow want this regime?"
════════════════════════════════════════════
🔔 ALERTS
Four alert conditions are built in so you can monitor without checking every bar manually:
Compression Release : a sustained compression (>= 10 bars) confirmed above mid-rank within 5 bars. The hero event.
Extreme Touch : rawRank peaked above P90. Fires on the bar after the actual peak (peak detection requires the next bar to confirm the turn-down).
Cooling : the first confirmed bar after an Extreme where rawRank falls below 75 within 10 bars.
Compression Entry : rawRank dropped below P25 (sustained tier transition into Compression).
All four alerts fire on bar close (gated on barstate.isconfirmed). Each alert message is a pure JSON payload with ticker, price, timeframe, and timestamp fields for webhook routing.
Four alerts by design - concentrated on the signature events. Tier and phase transitions stay visible in the info panel for users who want them on the chart, but they do not fire alerts. Keeping the alert stream lean is what makes "subscribe and let the regime come to you" a useful workflow instead of a notification flood.
════════════════════════════════════════════
⌁ NOTES
Based on the classical ATR percentile-rank construction, with asymmetric hysteresis and a velocity-gated compression-release definition layered on top.
Repaint: intrabar-only. Closed-bar alerts are confirmed; current-bar visuals may update until the bar closes. All alert conditions are gated on barstate.isconfirmed. Peak-confirmed events (Extreme Touch) print on the bar AFTER the actual peak, on a one-bar offset, so the marker aligns with the true peak bar.
References: J. Welles Wilder Jr., New Concepts in Technical Trading Systems (1978), Trend Research; percentile-rank concept widely used across volatility studies.
Open-source under MPL 2.0. Free to use, fork, study.
NovaLens
Pine Script® indicator






















