Pratik Bhadane
602d675749
Implements all phases of the derivatives expansion plan: Rust core (crates/ferro_ta_core/src/options/, src/futures/): - BSM and Black-76 pricing (scalar + vectorized batch) - Greeks: delta, gamma, vega, theta, rho - Implied volatility solver (Newton + bisection fallback) - Smile/skew metrics: ATM IV, 25-delta RR/BF, skew slope, convexity - Chain helpers: moneyness labels, strike selection by offset or delta - Synthetic forwards, basis, annualized basis, implied carry, carry spread - Continuous contract stitching: weighted, back-adjusted, ratio-adjusted - Curve analytics: calendar spreads, slope, contango/backwardation summary PyO3 bindings (src/options/, src/futures/): - All Rust functions registered and exposed via _ferro_ta extension Python API (python/ferro_ta/analysis/): - options.py: pricing, greeks, IV, smile, chain, legacy iv_rank/percentile/zscore - futures.py: basis, carry, curve, roll, synthetic, continuous contracts - options_strategy.py: typed strategy schemas (expiry/strike selectors, leg presets, risk controls, simulation limits) - derivatives_payoff.py: multi-leg payoff aggregation and Greeks aggregation Bug fix: wrap _to_f64 calls in iv_rank/iv_percentile/iv_zscore to raise FerroTAInputError (not plain ValueError) for 2D array input. Docs: derivatives.rst, derivatives-analytics.md, options-volatility.md, quickstart.rst, index.rst, api/analysis.rst all updated. Tests: 2053 pass, 12 skipped. All CI checks pass locally. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
80 lines
2.2 KiB
Markdown
80 lines
2.2 KiB
Markdown
# Options and Implied Volatility
|
|
|
|
`ferro-ta` exposes options analytics from `ferro_ta.analysis.options`.
|
|
|
|
## Scope
|
|
|
|
The module now covers both classic IV-series helpers and model-based option
|
|
analytics:
|
|
|
|
- `iv_rank`, `iv_percentile`, `iv_zscore`
|
|
- Black-Scholes-Merton pricing
|
|
- Black-76 pricing
|
|
- Delta, gamma, vega, theta, rho
|
|
- Implied volatility inversion
|
|
- Smile metrics and chain helpers
|
|
|
|
Heavy computation runs in Rust through the `_ferro_ta` extension.
|
|
|
|
## IV-series helpers
|
|
|
|
The original rolling helpers remain available and keep their public names:
|
|
|
|
```python
|
|
import numpy as np
|
|
from ferro_ta.analysis.options import iv_rank, iv_percentile, iv_zscore
|
|
|
|
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)
|
|
pct = iv_percentile(iv, window=5)
|
|
z = iv_zscore(iv, window=5)
|
|
```
|
|
|
|
These helpers accept a 1-D IV series and return rolling statistics with
|
|
`NaN` during the warmup period.
|
|
|
|
## Pricing and Greeks
|
|
|
|
```python
|
|
from ferro_ta.analysis.options import greeks, implied_volatility, option_price
|
|
|
|
price = option_price(100.0, 100.0, 0.05, 1.0, 0.20, option_type="call")
|
|
iv = implied_volatility(price, 100.0, 100.0, 0.05, 1.0, option_type="call")
|
|
g = greeks(100.0, 100.0, 0.05, 1.0, 0.20, option_type="call")
|
|
```
|
|
|
|
Conventions:
|
|
|
|
- Volatility is decimal annualized volatility: `0.20` means 20%.
|
|
- Rates are decimal annualized rates: `0.05` means 5%.
|
|
- `time_to_expiry` is measured in years.
|
|
- `model="bsm"` uses spot as the underlying input.
|
|
- `model="black76"` uses forward as the underlying input.
|
|
|
|
## Smile and chain helpers
|
|
|
|
```python
|
|
from ferro_ta.analysis.options import label_moneyness, select_strike, smile_metrics
|
|
|
|
strikes = [80, 90, 100, 110, 120]
|
|
vols = [0.30, 0.25, 0.20, 0.22, 0.27]
|
|
|
|
metrics = smile_metrics(strikes, vols, 100.0, 0.5)
|
|
labels = label_moneyness(strikes, 100.0, option_type="call")
|
|
atm = select_strike(strikes, 100.0, selector="ATM")
|
|
delta_strike = select_strike(
|
|
strikes,
|
|
100.0,
|
|
selector="DELTA0.25",
|
|
option_type="call",
|
|
volatilities=vols,
|
|
time_to_expiry=0.5,
|
|
)
|
|
```
|
|
|
|
## Related futures analytics
|
|
|
|
See `ferro_ta.analysis.futures` and
|
|
[`docs/derivatives-analytics.md`](./derivatives-analytics.md) for synthetic
|
|
forwards, basis, carry, curve, and roll analytics.
|