VolatilityRegime — Volatility Regime

Current volatility expressed as a percentile of its own long history: 0 means the calmest this instrument has been in the lookback, 100 the most violent. Self-normalising, so the same thresholds work on any instrument.

Signature

VolatilityRegime(period, rank_period, on=<source>)

Argument	Type	Required	Notes
period	int Param or literal	Yes	Short window the volatility is measured over. Default 20, bounds 2–200.
rank_period	int Param or literal	Yes	Long window it is ranked within. Default 252, bounds 2–1000.
on=	symbol, OHLCV field, or indicator	No	Source. Defaults to the trade symbol’s close.

Formula

$$ \text{VolRegime} = \text{PercentRank}\big(\sigma(\text{returns}, n),\ m\big) $$

Warmup

period + rank_period bars for a full ranking; before that it ranks against the history available.

Reading the value

vr.value
vr.value > 80

Example

class RegimeSizing(Strategy):
    """Only take new risk in the calmer half of the volatility distribution."""
    trade = Symbol()
    sizing = FixedCapital()

    def execute(self):
        vr = VolatilityRegime(20, 252, on=self.trade)
        sma = SMA(50, on=self.trade)
        if vr.value < 50 and self.trade.close > sma.value and self.trade.is_flat:
            self.buy(self.trade, reason=f"Vol percentile {vr.value:.0f}")
        if vr.value > 85 and self.trade.is_long:
            self.sell(self.trade, self.trade.position, reason="Volatility regime shift")

Notes

• Proven by an assert-via-trade run on SPY daily (stayed inside 0–100 on every bar; zero alarm trades).
• Percentile, not level — it says “unusual for this instrument”, never “high in absolute terms”. Pair with HistoricalVolatility when the absolute number matters.