VolatilityRegimeClassifier
Ranks recent volatility against recent history: 0 low, 1 normal, 2 high, 3 extreme.
It measures how large recent price moves are: the standard deviation of the last vol_window bar-to-bar returns of the close, not annualized. It ranks that figure against the last max_history readings of the same measure and gives a percentile from 0 to 1, counting the current bar. The percentile falls into one of four bands, 0 low, 1 normal, 2 high or 3 extreme, set by the low_pct, high_pct and extreme_pct cut-offs.
How to read it
- Regime, percentile and volatility share one pane below the price on one scale. Volatility is about 0.0001, so its line hugs zero and is hard to see.
- The regime line steps between the levels 0 (low), 1 (normal), 2 (high) and 3 (extreme). A step is a change in how big the moves are compared with recent history, not in price direction.
- With default settings the first 69 bars of a chart are blank while the 20-bar window and the 50-reading history fill.
What it outputs
- Regime
- Whole-number volatility regime from the percentile: 0 low, 1 normal, 2 high, 3 extreme. Blank during warm-up.
- Percentile
- Share of recent volatility readings at or below the current one, from 0 to 1, counting the current bar. Its floor is 1 over the history length, which is 0.0005 once 2000 readings are stored.
- Volatility
- Standard deviation of the last vol_window bar-to-bar returns of the close, not annualized. On SPY it is about 0.013% per bar at the median.
Settings
- vol_window
- Bars of returns in each volatility reading. Raising it smooths the reading and slows regime changes. Lowering it reacts within minutes but is noisier. At 1 every reading is zero, so every bar reads as extreme.
- min_history
- Volatility readings needed before any regime shows. Raising it blanks more of the chart's start. Lowering it shows regimes sooner, but the first readings rank against very few values and often read as extreme.
- max_history
- How many past volatility readings the rank looks back over. Raising it makes regimes steadier and slower to shift. Lowering it makes them follow the last few readings. The SPY sample has 960 bars a day, so the default 2000 covers about two sessions.
- low_pct
- The percentile at or below which a bar reads 0 (low). Raising it puts more bars in low, lowering it makes low rarer. Keep it between 0 and 1: the catalog slider runs to 26, and any value above 1 makes every bar low.
- high_pct
- The top of the normal band. Bars above it and up to extreme_pct read 2 (high). Raising it moves bars from high into normal. Lowering it makes high more common. Keep it between low_pct and extreme_pct, or a band disappears.
- extreme_pct
- The percentile above which a bar reads 3 (extreme). Raising it makes extreme rarer: at 0.99 only the top 1% of bars read 3. Lowering it to 0.9 makes about one bar in ten extreme.
Pitfalls
- Extreme is not a shock. Readings are ranked against recent history, so about one bar in twenty reads 3 even when nothing unusual happens. On the SPY sample the 95th percentile of regime was 3.
- It measures how big the moves are, not which way price goes. Its correlation with close was between -0.04 and -0.10 on the sample, so it does not track the price level.