102 lines
3.0 KiB
Markdown
102 lines
3.0 KiB
Markdown
|
# 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.
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
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:
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
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).
|