Files

T

Pratik Bhadane 602d675749 feat: add full derivatives analytics layer (options + futures)

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>

2026-03-24 02:41:50 +05:30

2.2 KiB

Raw Permalink Blame History

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:

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

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

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

See ferro_ta.analysis.futures and docs/derivatives-analytics.md for synthetic forwards, basis, carry, curve, and roll analytics.

2.2 KiB Raw Permalink Blame History