Implied Volatility (IV) Features¶

Overview¶

The Implied Volatility (IV) feature block constructs volatility-regime and term-structure features from historical ATM implied volatility and canonical IV smile columns. These features operate exclusively on canonical underlying daily data and are fully deterministic, causal, and model-agnostic. No option-level joins, fitting, or smoothing beyond rolling statistics are performed.

The IV block is designed to capture:

Relative volatility regimes
Changes in implied volatility over time
Volatility of volatility
ATM term-structure shape

Required Input Columns¶

Mandatory¶

The following column must be present:

Column	Description
`iv_atm_hist`	Historical at-the-money implied volatility

This value is expected to be strictly positive and expressed in decimal units.

Optional (for term structure features)¶

If present, the following columns enable ATM term-structure features:

Column	Description
`iv_30_m100`	30-day ATM implied volatility
`iv_60_m100`	60-day ATM implied volatility

If these columns are missing, term-structure outputs are returned as null.

Produced Feature Columns¶

Volatility Regime Measures¶

Feature	Description
`iv_rank`	Rolling IV rank over lookback window
`iv_percentile`	Empirical percentile of current IV

IV Rank Definition

IV Rank is calculated by taking the difference between today’s implied volatility and the minimum implied volatility in the period, and then dividing that by the difference between the maximum and minimum implied volatility over the same period. Computed over a rolling window and bounded to [0, 1].

IV Changes¶

Feature	Description
`iv_change_1d`	1-day change in ATM IV
`iv_change_5d`	5-day change in ATM IV
`iv_change_21d`	21-day change in ATM IV

These features capture short, medium and monthly scale IV dynamics.

Volatility of Volatility¶

Feature	Description
`iv_vol_of_vol`	Rolling standard deviation of IV percentage changes

Computed as: - percent change of iv_atm_hist - rolling standard deviation over 21 days

ATM Term Structure (Optional)¶

Feature	Description
`iv_term_slope_30_60`	Difference: 60D ATM IV − 30D ATM IV
`iv_term_ratio_30_60`	Ratio: 60D ATM IV / 30D ATM IV

These features characterize contango vs backwardation in the ATM volatility term structure.

How to Call This Feature Block¶

Recommended (Public API)¶

Use the public IV feature API when working with canonical underlying data:

from ocf.features.api import iv_features

features = iv_features(
    underlying_daily,
    window_days=252,
)

This validates schema correctness and ensures a stable output contract.

Direct Builder Access (Advanced)¶

For controlled or testing environments, the builder can be called directly:

from ocf.features.iv import build_iv_features

features = build_iv_features(
    underlying_daily,
    window_days=252,
)

This bypasses schema validation and assumes canonical inputs.

As Part of the Composite Feature Set¶

The IV block can be enabled within the composite feature API:

from ocf.features.api import underlying_features

features = underlying_features(
    underlying_daily,
    include=["iv"],
)

or combined with other blocks:

features = underlying_features(
    underlying_daily,
    include=["ohlcv", "iv", "liquidity"],
)

Rolling Window Behavior¶

IV rank and percentile require a minimum of 20 observations
Rolling lookback defaults to 252 trading days
Early rows may contain null values
No forward-looking information is used

Masking Rules¶

All IV-derived features are masked (null) when iv_atm_hist is missing for a given date. This ensures consistency and prevents partial-feature leakage.

Configuration¶

Parameter	Default	Description
`window_days`	`252`	Lookback window for IV rank & percentile

Note¶

No curve fitting or smoothing is applied
Percentiles are empirical and not parametric
Term-structure features are ATM-only