abaquant.marketdata.option_chain_analytics

Import path: abaquant.marketdata.option_chain_analytics

Domain: Provider-neutral market-data facades, normalized records, caching, and analytics.

Purpose

Listed-option-chain analytics that connect provider data to pricing models.

When to use it

Use this package to retrieve or inject quotes, price history, option chains, and financial statements while preserving a stable analytical interface.

Public objects

  • class: OptionSkewSummary — Linear implied-volatility skew summary for one listed option slice. * OptionSkewSummary.as_dict — Return a serialization-friendly representation of the skew summary.

  • class: OptionChainAnalytics — Provider-independent analytics for one ticker’s listed option chains. * OptionChainAnalytics.enriched_chain — Return the chain with midpoint, moneyness, and log-moneyness columns. * OptionChainAnalytics.iv_smile — Return implied volatility by strike and moneyness for one expiry. * OptionChainAnalytics.iv_surface — Return a long-form implied-volatility surface across expirations. * OptionChainAnalytics.skew — Estimate linear implied-volatility skew against log-moneyness. * OptionChainAnalytics.term_structure — Return implied volatility across expirations for one strike. * OptionChainAnalytics.rich_cheap_table — Compare listed market prices with model values contract by contract. * OptionChainAnalytics.open_interest_grid — Return open interest by expiry, strike, and option type. * OptionChainAnalytics.visualize — Visualize a listed-option-chain analytic table. * OptionChainAnalytics.calibrate_bsm_flat_vol — Calibrate one flat Black–Scholes–Merton volatility to the chain. * OptionChainAnalytics.calibrate_sabr — Calibrate SABR smile parameters to listed implied volatilities. * OptionChainAnalytics.calibrate_heston — Calibrate Heston parameters to listed option observations.

Detailed reference

Listed-option-chain analytics that connect provider data to pricing models.

The module turns normalized listed option chains into applied analytics such as implied-volatility smiles, term structures, rich/cheap comparisons, and open- interest grids. It does not retrieve data directly; retrieval remains the responsibility of TickerOptionAnalytics and the configured market provider.

class abaquant.marketdata.option_chain_analytics.OptionSkewSummary(option_type, observations, slope, intercept, at_the_money_iv)

Bases: object

Linear implied-volatility skew summary for one listed option slice.

Parameters:

  • option_type (Literal['call', 'put'])

  • observations (int)

  • slope (float)

  • intercept (float)

  • at_the_money_iv (float | None)

option_type

Option family used for the fitted slice.

Type:

{“call”, “put”}

observations

Number of finite observations used in the fit.

Type:

int

slope

Least-squares slope of implied volatility against log-moneyness.

Type:

float

intercept

Least-squares intercept of implied volatility against log-moneyness.

Type:

float

at_the_money_iv

Implied volatility at the observation with moneyness closest to one.

Type:

float | None

as_dict()

Return a serialization-friendly representation of the skew summary.

Return type:

dict[str, float | int | str | None]

class abaquant.marketdata.option_chain_analytics.OptionChainAnalytics(ticker, expiry, chain, provenance=None)

Bases: object

Provider-independent analytics for one ticker’s listed option chains.

Parameters:

  • ticker (object) – Applied ticker object exposing symbol, spot(), and options.chain(...).

  • expiry (str) – Primary expiration date in ISO YYYY-MM-DD form.

  • chain (pandas.DataFrame) – Normalized raw option chain for expiry.

  • provenance (DataProvenance | None)

Notes

This object keeps market-data retrieval separate from option analytics. The primary chain is supplied at construction, while multi-expiry methods fetch extra expirations lazily through ticker.options.chain only when needed.

enriched_chain(*, spot_price=None)

Return the chain with midpoint, moneyness, and log-moneyness columns.

Parameters:

spot_price (float | None, default=None) – Current underlying price. When omitted, ticker.spot() is used.

Returns:

Copy of the normalized option chain with derived market_price, moneyness, log_moneyness, and days_to_expiry columns.

Return type:

pandas.DataFrame

iv_smile(*, option_type='call', spot_price=None, min_open_interest=None)

Return implied volatility by strike and moneyness for one expiry.

Parameters:

  • option_type ({"call", "put"}, default="call") – Listed option family used for the smile.

  • spot_price (float | None, default=None) – Current underlying price used to compute moneyness.

  • min_open_interest (float | None, default=None) – Optional minimum open-interest filter. If omitted, no liquidity filter is applied.

Returns:

Sorted table with strike, moneyness, log_moneyness, implied_volatility, market_price, and open_interest when available.

Return type:

pandas.DataFrame

iv_surface(*, expiries=None, option_type='call', spot_price=None)

Return a long-form implied-volatility surface across expirations.

Parameters:

  • expiries (sequence of str | None, default=None) – Expiration dates to include. When omitted, all provider-listed expirations are requested. If the provider cannot supply them, the primary expiry is used.

  • option_type ({"call", "put"}, default="call") – Option family used for the surface.

  • spot_price (float | None, default=None) – Current underlying price used to compute moneyness.

Returns:

Long-form surface with one row per contract containing expiry, strike, moneyness, days_to_expiry, and implied_volatility.

Return type:

pandas.DataFrame

skew(*, option_type='call', spot_price=None)

Estimate linear implied-volatility skew against log-moneyness.

Parameters:

  • option_type ({"call", "put"}, default="call") – Option family used for the fitted smile.

  • spot_price (float | None, default=None) – Current underlying price used to compute moneyness.

Returns:

Least-squares slope/intercept and the closest-to-the-money IV.

Return type:

OptionSkewSummary

term_structure(*, strike=None, option_type='call', expiries=None, spot_price=None)

Return implied volatility across expirations for one strike.

Parameters:

  • strike (float | None, default=None) – Target strike. When omitted, the current spot price is used and the nearest listed strike is selected for each expiry.

  • option_type ({"call", "put"}, default="call") – Option family used for the term structure.

  • expiries (sequence of str | None, default=None) – Expirations to include. When omitted, all provider-listed expirations are requested.

  • spot_price (float | None, default=None) – Current spot price. Used as the default target strike and for moneyness calculations.

Returns:

Table with nearest-strike IV by expiry.

Return type:

pandas.DataFrame

rich_cheap_table(*, model='bsm', risk_free_rate, option_type=None, volatility='listed', dividend_yield=0.0, spot_price=None)

Compare listed market prices with model values contract by contract.

Parameters:

  • model ({"bsm"}, default="bsm") – Pricing model used for theoretical values. Only Black–Scholes– Merton is supported in this release.

  • risk_free_rate (float) – Annual risk-free rate in decimal units.

  • option_type ({"call", "put"} | None, default=None) – Optional option family filter. When omitted, calls and puts are included.

  • volatility (float or {"listed"}, default="listed") – Volatility used in the BSM model. "listed" uses each contract’s provider-reported implied volatility.

  • dividend_yield (float, default=0.0) – Continuous dividend yield in decimal annual units.

  • spot_price (float | None, default=None) – Current underlying price. When omitted, ticker.spot() is used.

Returns:

Contract-level table with market price, model value, difference, relative difference, and rich/cheap label. Positive differences mean the listed contract is rich versus the model value.

Return type:

pandas.DataFrame

open_interest_grid(*, expiries=None, option_type=None, spot_price=None)

Return open interest by expiry, strike, and option type.

Parameters:

  • expiries (sequence of str | None, default=None) – Expiration dates to include. When omitted, all provider-listed expirations are requested.

  • option_type ({"call", "put"} | None, default=None) – Optional option family filter.

  • spot_price (float | None, default=None) – Current underlying price used to compute moneyness.

Returns:

Long-form table suitable for open-interest heatmaps.

Return type:

pandas.DataFrame

visualize(*, chart='iv_smile', option_type='call', metric='implied_volatility', backend=None, theme=None, save_path=None, filename=None, **kwargs)

Visualize a listed-option-chain analytic table.

Parameters:

  • chart ({"iv_smile", "iv_surface", "term_structure", "rich_cheap", "open_interest_heatmap"}, default="iv_smile") – Listed-option-chain diagnostic to render.

  • option_type ({"call", "put"}, default="call") – Option family used when the selected chart accepts a family filter.

  • metric (str, default="implied_volatility") – Surface metric used by chart="iv_surface".

  • backend (str | None) – Standard AbaQuant visualization overrides.

  • theme – Standard AbaQuant visualization overrides.

  • save_path – Standard AbaQuant visualization overrides.

  • filename – Standard AbaQuant visualization overrides.

  • **kwargs (object) – Additional arguments forwarded to the underlying analytics method.

Returns:

Backend-native figure object.

Return type:

matplotlib.figure.Figure or plotly.graph_objects.Figure

calibrate_bsm_flat_vol(*, option_type='call', risk_free_rate, dividend_yield=0.0, objective='price', spot_price=None, maturity_years=None, **kwargs)

Calibrate one flat Black–Scholes–Merton volatility to the chain.

Parameters:

  • option_type ({"call", "put"}, default="call") – Listed option family used during the fit.

  • risk_free_rate (float) – Continuously compounded annual risk-free rate.

  • dividend_yield (float, default=0.0) – Continuous annual dividend yield.

  • objective ({"price", "iv"}, default="price") – Whether to fit listed premiums or listed implied volatilities.

  • spot_price (float | None, default=None) – Spot price override. When omitted, ticker.spot() is used.

  • maturity_years (float | None, default=None) – Time to expiration override. When omitted, days to the analytics object’s primary expiry are used.

  • **kwargs (object) – Additional keyword arguments forwarded to abaquant.derivatives.calibration.BSMFlatVolCalibration.

Returns:

Fitted flat-volatility calibration result.

Return type:

CalibrationResult

calibrate_sabr(*, option_type='call', beta=1.0, risk_free_rate=0.0, dividend_yield=0.0, spot_price=None, forward_price=None, maturity_years=None, **kwargs)

Calibrate SABR smile parameters to listed implied volatilities.

Parameters:

  • option_type ({"call", "put"}, default="call") – Listed option family used during the fit.

  • beta (float, default=1.0) – Fixed SABR elasticity parameter.

  • risk_free_rate (float, default=0.0) – Continuously compounded annual risk-free rate.

  • dividend_yield (float, default=0.0) – Continuous annual dividend yield.

  • spot_price (float | None, default=None) – Spot price override. When omitted, ticker.spot() is used.

  • forward_price (float | None, default=None) – Forward price override. When omitted, it is inferred from spot and carry assumptions.

  • maturity_years (float | None, default=None) – Time to expiration override.

  • **kwargs (object) – Additional keyword arguments forwarded to abaquant.derivatives.calibration.SABRSmileCalibration.

Returns:

SABR calibration result.

Return type:

CalibrationResult

calibrate_heston(*, option_type='call', risk_free_rate, dividend_yield=0.0, spot_price=None, maturity_years=None, objective='iv', **kwargs)

Calibrate Heston parameters to listed option observations.

Parameters:

  • option_type ({"call", "put"}, default="call") – Listed option family used during the fit.

  • risk_free_rate (float) – Continuously compounded annual risk-free rate.

  • dividend_yield (float, default=0.0) – Continuous annual dividend yield.

  • spot_price (float | None, default=None) – Spot price override. When omitted, ticker.spot() is used.

  • maturity_years (float | None, default=None) – Time to expiration override.

  • objective ({"price", "iv"}, default="iv") – Whether the fit targets premiums or implied volatilities.

  • **kwargs (object) – Additional keyword arguments forwarded to abaquant.derivatives.calibration.HestonCalibration.

Returns:

Heston stochastic-volatility calibration result.

Return type:

CalibrationResult