gavindiaz/ferro-ta
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add full derivatives analytics layer (options + futures)

Browse Source 
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>
This commit is contained in:
Pratik Bhadane
2026-03-24 02:41:50 +05:30
co-authored by Claude Sonnet 4.6
parent 2d5000262f
commit 602d675749
47 changed files with 4538 additions and 280 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/unit/test_data_pipeline.py
+12 -4
View File
@@ -622,9 +622,15 @@ class TestComputeMany:
close=close,
)
np.testing.assert_allclose(results[0], SMA(close, timeperiod=10), equal_nan=True)
np.testing.assert_allclose(results[1], EMA(close, timeperiod=12), equal_nan=True)
np.testing.assert_allclose(results[2], RSI(close, timeperiod=14), equal_nan=True)
np.testing.assert_allclose(
results[0], SMA(close, timeperiod=10), equal_nan=True
)
np.testing.assert_allclose(
results[1], EMA(close, timeperiod=12), equal_nan=True
)
np.testing.assert_allclose(
results[2], RSI(close, timeperiod=14), equal_nan=True
)
def test_hlc_indicators_match_public_api(self):
from ferro_ta import ADX, ATR
@@ -653,7 +659,9 @@ class TestComputeMany:
from ferro_ta.data.batch import compute_many
_, _, _, close, _ = _make_ohlcv(80)
result = compute_many([("STDDEV", {"timeperiod": 10, "nbdev": 2.0})], close=close)
result = compute_many(
[("STDDEV", {"timeperiod": 10, "nbdev": 2.0})], close=close
)
np.testing.assert_allclose(
result[0], STDDEV(close, timeperiod=10, nbdev=2.0), equal_nan=True
)
tests/unit/test_derivatives.py
+218
View File
@@ -0,0 +1,218 @@
import numpy as np
import pytest
class TestOptionsAnalytics:
def test_black_scholes_price_scalar(self):
from ferro_ta.analysis.options import black_scholes_price
price = black_scholes_price(
100.0,
100.0,
0.05,
1.0,
0.2,
option_type="call",
)
assert price == pytest.approx(10.4506, rel=1e-4)
def test_black_76_price_vectorized(self):
from ferro_ta.analysis.options import black_76_price
price = black_76_price(
np.array([100.0, 105.0]),
np.array([100.0, 100.0]),
0.03,
1.0,
np.array([0.2, 0.25]),
option_type="call",
)
assert isinstance(price, np.ndarray)
assert price.shape == (2,)
assert np.all(price > 0.0)
def test_greeks_and_iv_recovery(self):
from ferro_ta.analysis.options import greeks, implied_volatility, option_price
price = option_price(
100.0,
100.0,
0.05,
1.0,
0.2,
option_type="call",
model="bsm",
)
iv = implied_volatility(
price,
100.0,
100.0,
0.05,
1.0,
option_type="call",
model="bsm",
)
result = greeks(
100.0,
100.0,
0.05,
1.0,
0.2,
option_type="call",
model="bsm",
)
assert iv == pytest.approx(0.2, rel=1e-6)
assert result.delta == pytest.approx(0.6368, rel=1e-3)
assert result.gamma > 0.0
assert result.vega > 0.0
def test_smile_and_chain_helpers(self):
from ferro_ta.analysis.options import (
label_moneyness,
select_strike,
smile_metrics,
term_structure_slope,
)
strikes = np.array([80.0, 90.0, 100.0, 110.0, 120.0])
vols = np.array([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")
assert metrics.atm_iv == pytest.approx(0.20, rel=1e-6)
assert metrics.skew_slope < 0.0
assert labels.tolist() == ["ITM", "ITM", "ATM", "OTM", "OTM"]
assert select_strike(strikes, 101.0, selector="ATM") == 100.0
assert (
select_strike(strikes, 101.0, option_type="call", selector="OTM2") == 120.0
)
assert select_strike(
strikes,
100.0,
selector="DELTA0.25",
option_type="call",
volatilities=vols,
time_to_expiry=0.5,
) in set(strikes.tolist())
assert term_structure_slope([0.1, 0.5, 1.0], [0.18, 0.20, 0.22]) > 0.0
class TestFuturesAnalytics:
def test_basis_and_curve_helpers(self):
from ferro_ta.analysis.futures import (
annualized_basis,
basis,
calendar_spreads,
carry_spread,
curve_summary,
implied_carry_rate,
synthetic_forward,
)
assert basis(100.0, 103.0) == pytest.approx(3.0)
assert annualized_basis(100.0, 103.0, 0.25) > 0.0
assert implied_carry_rate(100.0, 103.0, 0.25) > 0.0
assert carry_spread(100.0, 103.0, 0.02, 0.25) > -1.0
assert synthetic_forward(8.0, 5.0, 100.0, 0.02, 0.5) > 100.0
assert np.allclose(calendar_spreads([100.0, 101.0, 103.0]), [1.0, 2.0])
summary = curve_summary(100.0, [0.1, 0.5, 1.0], [101.0, 102.0, 104.0])
assert summary.is_contango is True
assert summary.slope > 0.0
def test_roll_helpers(self):
from ferro_ta.analysis.futures import (
back_adjusted_continuous_contract,
ratio_adjusted_continuous_contract,
roll_yield,
weighted_continuous_contract,
)
front = np.array([100.0, 101.0, 102.0, 103.0])
nxt = np.array([101.0, 102.0, 103.0, 104.0])
weights = np.array([0.0, 0.25, 0.75, 1.0])
weighted = weighted_continuous_contract(front, nxt, weights)
back_adjusted = back_adjusted_continuous_contract(front, nxt, weights)
ratio_adjusted = ratio_adjusted_continuous_contract(front, nxt, weights)
assert weighted.shape == front.shape
assert back_adjusted.shape == front.shape
assert ratio_adjusted.shape == front.shape
assert roll_yield(100.0, 102.0, 30.0 / 365.0) > 0.0
class TestStrategyAndPayoff:
def test_strategy_schema_and_preset(self):
from ferro_ta.analysis.options_strategy import (
DerivativesStrategy,
ExpirySelector,
ExpirySelectorKind,
LegPreset,
StrategyLeg,
StrikeSelector,
StrikeSelectorKind,
build_strategy_preset,
)
preset = build_strategy_preset(
LegPreset.STRADDLE,
name="ATM Straddle",
underlying="NIFTY",
expiry_selector=ExpirySelector(ExpirySelectorKind.CURRENT_WEEK),
)
custom = DerivativesStrategy(
name="Custom Single",
legs=(
StrategyLeg(
"NIFTY",
ExpirySelector(ExpirySelectorKind.CURRENT_WEEK),
StrikeSelector(
StrikeSelectorKind.EXPLICIT, explicit_strike=22000.0
),
"call",
),
),
)
assert len(preset.legs) == 2
assert custom.to_dict()["name"] == "Custom Single"
def test_payoff_and_aggregate_greeks(self):
from ferro_ta.analysis.derivatives_payoff import (
PayoffLeg,
aggregate_greeks,
strategy_payoff,
)
spot_grid = np.array([90.0, 100.0, 110.0])
legs = [
PayoffLeg(
instrument="option",
side="long",
option_type="call",
strike=100.0,
premium=5.0,
volatility=0.2,
time_to_expiry=0.5,
),
PayoffLeg(
instrument="option",
side="short",
option_type="call",
strike=110.0,
premium=2.0,
volatility=0.22,
time_to_expiry=0.5,
),
PayoffLeg(instrument="future", side="long", entry_price=100.0),
]
payoff = strategy_payoff(spot_grid, legs=legs)
greeks = aggregate_greeks(100.0, legs=legs)
assert payoff.shape == spot_grid.shape
assert payoff[1] == pytest.approx(-3.0)
assert greeks.delta > 0.0
assert greeks.gamma > 0.0