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).
|