ferro-ta/docs/options-volatility.md

Options and Implied Volatility

ferro-ta provides optional helpers for implied volatility (IV) analysis via the ferro_ta.options module. This document describes the scope, data format, dependency strategy, and limitations.

---

Scope

The ferro_ta.options module focuses on IV series analysis:

• IV rank — where today's IV sits relative to the min/max over a look-back window.
• IV percentile — fraction of observations over a look-back window at or below today's IV.
• IV z-score — how many standard deviations today's IV is above the rolling mean.

These functions accept any 1-D IV series (e.g. VIX daily closes, single-name 30-day IV, etc.) and return rolling statistics.

Out of scope (for now): Black-Scholes pricing, Greeks, option chain parsing, synthetic forward construction, dividend adjustment. For full option-pricing functionality consider py_vollib, mibian, or similar.

---

Data format

All functions accept a 1-D NumPy array (or any array-like) of IV values. IV values are typically in percentage points (e.g. VIX = 20 means 20% annualised volatility), but the helpers are unit-agnostic — they only compare values within the rolling window.

import numpy as np
from ferro_ta.options import iv_rank, iv_percentile, iv_zscore

# VIX-like daily close series
iv = np.array([18.5, 22.3, 19.1, 25.0, 30.2, 27.8, 21.4, 19.0])

rank = iv_rank(iv, window=5)        # rolling IV rank in [0, 1]
pct  = iv_percentile(iv, window=5)  # rolling IV percentile in [0, 1]
z    = iv_zscore(iv, window=5)      # rolling z-score

---

Dependency strategy

The ferro_ta.options module uses only NumPy (already a core dependency). No additional packages are required for the helpers described here.

For advanced option analytics (Black-Scholes, volatility surface interpolation), install the optional extra:

pip install "ferro-ta[options]"

This may install additional packages in the future (e.g. py_vollib).

---

API reference

iv_rank(iv_series, window=252)

Rolling IV rank.

rank_t = (IV_t - min(IV[t-window+1:t+1])) / (max(IV[t-window+1:t+1]) - min(IV[t-window+1:t+1]))

Returns values in [0, 1]. NaN for the first window - 1 bars.

iv_percentile(iv_series, window=252)

Rolling IV percentile: fraction of the window bars whose IV was at or below the current value.

iv_zscore(iv_series, window=252)

Rolling z-score: (IV_t - rolling_mean) / rolling_std.

---

Limitations

• All functions use O(n × window) time complexity (pure Python loops). For large windows or series consider vectorised alternatives.
• No option chain support; the module assumes IV series as input.
• Streaming (bar-by-bar) versions of these functions are not yet implemented. For live use, maintain a rolling buffer and call the functions on the buffer at each bar.

---

See also

• ferro_ta.options — module source.
• ferro_ta.statistic — general statistical functions (STDDEV, VAR, CORREL, etc.).
• ferro_ta.volatility — price-based volatility indicators (ATR, NATR).