abaquant.derivatives.models.diagnostics¶

Import path: abaquant.derivatives.models.diagnostics

Domain: Derivative pricing, simulation, calibration, diagnostics, and strategy analysis.

Purpose¶

Scalar option diagnostics for AbaQuant pricing models.

When to use it¶

This module implements or supports one derivative model. Read the parameter constraints, pricing measure, numerical method, and limiting cases before comparing outputs across models.

Public objects¶

class: DerivativeDiagnosticsReport — Computed scalar diagnostics for one vanilla derivative contract. * DerivativeDiagnosticsReport.as_dict — Return a plain dictionary representation of the diagnostics report.
class: DerivativeScenarioGrid — Scenario-grid result for one vanilla option model. * DerivativeScenarioGrid.as_dict — Return a serialization-friendly representation of the grid. * DerivativeScenarioGrid.pivot — Return a spot-by-volatility pivot table for one scenario metric. * DerivativeScenarioGrid.visualize — Return a figure for this derivative scenario grid.
function: validate_option_type — Normalize and validate a vanilla option type label.
function: vanilla_intrinsic_value_from_prices — Return the current intrinsic value of a vanilla option.
function: option_price — Return the call or put price from a scalar pricing model.
function: current_intrinsic_value — Return the current intrinsic value for a scalar pricing model.
function: current_extrinsic_value — Return the model value in excess of current intrinsic value.
function: spot_moneyness — Return spot moneyness for a scalar model.
function: forward_moneyness — Return forward moneyness for a scalar model.
function: break_even_price — Return a premium-adjusted terminal break-even price.
function: select_option_greeks — Select option-specific Greek names from a raw model Greek mapping.
function: model_greeks — Return option-specific Greeks when a model exposes them.
function: derivative_scenario_grid — Evaluate a vanilla option model over spot and volatility scenarios.
function: derivative_diagnostics — Build a complete scalar diagnostics report for one vanilla derivative.
class: OptionDiagnosticsMixin — Mixin adding scalar vanilla diagnostics to pricing model classes. * OptionDiagnosticsMixin.price — Return this model’s call or put price. * OptionDiagnosticsMixin.intrinsic_value — Return the current intrinsic value of the option. * OptionDiagnosticsMixin.extrinsic_value — Return the option’s model value above intrinsic value. * OptionDiagnosticsMixin.moneyness — Return the current spot-to-strike moneyness ratio. * OptionDiagnosticsMixin.forward_moneyness — Return the forward-to-strike moneyness ratio. * OptionDiagnosticsMixin.break_even_price — Return the premium-adjusted terminal break-even price. * OptionDiagnosticsMixin.scenario_grid — Evaluate this option model over a spot–volatility scenario grid. * OptionDiagnosticsMixin.report — Return an exportable report for this option model. * OptionDiagnosticsMixin.diagnostics — Return a complete scalar derivative diagnostics report.

Detailed reference¶

Scalar option diagnostics for AbaQuant pricing models.

Purpose¶

The module defines a compact diagnostics report for vanilla option models and a mixin that adds moneyness, intrinsic value, extrinsic value, break-even, and Greek summaries to scalar pricing classes.

Conventions¶

Moneyness is reported as spot divided by strike. Forward moneyness uses the model’s explicit forward_price when present; otherwise it uses spot_price * exp((risk_free_rate - dividend_yield) * maturity_years). All prices are expressed in the same units as the model’s underlying and strike.

class abaquant.derivatives.models.diagnostics.DerivativeDiagnosticsReport(option_type, price, intrinsic_value, extrinsic_value, moneyness, forward_moneyness, greeks, break_even_price, provenance=None)¶

Bases: object

Computed scalar diagnostics for one vanilla derivative contract.

Parameters:

option_type ({"call", "put"}) – Vanilla option family used for the report.
price (float) – Model value of the option in currency units.
intrinsic_value (float) – Immediate-exercise payoff at the current underlying price.
extrinsic_value (float) – Difference between model value and intrinsic value.
moneyness (float) – Spot moneyness, defined as spot_price / strike_price.
forward_moneyness (float) – Forward moneyness, defined as forward price divided by strike price.
greeks (Mapping[str, float]) – Option-specific sensitivity dictionary when the model exposes Greeks.
break_even_price (float) – Terminal underlying price at which intrinsic payoff equals the model premium, ignoring financing, trading costs, and bid–ask effects.
provenance (DataProvenance | None)

as_dict()¶

Return a plain dictionary representation of the diagnostics report.

Returns:: Dictionary containing all scalar diagnostics and the nested Greek dictionary under the "greeks" key.
Return type:: dict[str, object]

class abaquant.derivatives.models.diagnostics.DerivativeScenarioGrid(option_type, data, base_spot_price, base_volatility, volatility_attribute, provenance=None)¶

Bases: object

Scenario-grid result for one vanilla option model.

Parameters:

option_type ({"call", "put"}) – Vanilla option family used for every scenario row.
data (pandas.DataFrame) – Long-form scenario table. Required columns are spot_price, volatility, price, intrinsic_value, extrinsic_value, moneyness, forward_moneyness, and break_even_price. Greek columns are included when the model exposes them.
base_spot_price (float) – Spot price on the model used to seed the scenario calculation.
base_volatility (float) – Volatility-like attribute value on the model before perturbation.
volatility_attribute (str) – Name of the model attribute varied across the volatility axis.
provenance (DataProvenance | None)

Notes

The grid is long-form rather than matrix-form so it can be filtered, grouped, exported, or pivoted without losing diagnostics columns.

as_dict()¶

Return a serialization-friendly representation of the grid.

Return type:: dict[str, object]

pivot(value='price')¶

Return a spot-by-volatility pivot table for one scenario metric.

Parameters:: value (str, default="price") – Metric column to pivot.
Returns:: Matrix indexed by volatility and columned by spot_price.
Return type:: pandas.DataFrame

visualize(*, metric='price', chart='surface', backend=None, theme=None, save_path=None, filename=None)¶

Return a figure for this derivative scenario grid.

Parameters:

metric (str, default="price") – Scenario metric to display. Common values are "price", "extrinsic_value", "delta", "gamma", "theta", and "vega".
chart ({"surface", "heatmap", "curves"}, default="surface") – Visual form for the long-form scenario grid.
backend ({"matplotlib", "plotly"}, optional) – Backend override for this figure.
theme (VisualizationTheme, optional) – Per-call style override.
save_path (str or pathlib.Path, optional) – Explicit export path.
filename (str, optional) – Filename relative to the active theme’s save directory.

Returns:

Backend-native figure object.

Return type:

matplotlib.figure.Figure or plotly.graph_objects.Figure

class abaquant.derivatives.models.diagnostics.OptionDiagnosticsMixin¶

Bases: object

Mixin adding scalar vanilla diagnostics to pricing model classes.

price(option_type='call')¶

Return this model’s call or put price.

Parameters:: option_type ({"call", "put"}, default="call") – Vanilla option family.
Returns:: Model price in currency units.
Return type:: float

intrinsic_value(option_type='call')¶

Return the current intrinsic value of the option.

Parameters:: option_type ({"call", "put"}, default="call") – Vanilla option family.
Returns:: Immediate-exercise payoff at the current spot price.
Return type:: float

extrinsic_value(option_type='call')¶

Return the option’s model value above intrinsic value.

Parameters:: option_type ({"call", "put"}, default="call") – Vanilla option family.
Returns:: price(option_type) - intrinsic_value(option_type).
Return type:: float

moneyness()¶

Return the current spot-to-strike moneyness ratio.

Returns:: Ratio spot_price / strike_price.
Return type:: float

forward_moneyness()¶

Return the forward-to-strike moneyness ratio.

Returns:: Forward moneyness under the model’s forward convention.
Return type:: float

break_even_price(option_type='call')¶

Return the premium-adjusted terminal break-even price.

Parameters:: option_type ({"call", "put"}, default="call") – Vanilla option family.
Returns:: Break-even terminal price ignoring financing and trading costs.
Return type:: float

scenario_grid(*, spot_prices, volatilities, option_type='call')¶

Evaluate this option model over a spot–volatility scenario grid.

Parameters:

spot_prices (Sequence[float]) – Positive underlying prices for the scenario axis.
volatilities (Sequence[float]) – Positive annualized decimal volatility values for the scenario axis.
option_type ({"call", "put"}, default="call") – Vanilla option family.

Returns:

Long-form scenario grid with prices, decomposition, moneyness, break-even levels, and model Greeks where available.

Return type:

DerivativeScenarioGrid

report(option_type='call')¶

Return an exportable report for this option model.

Parameters:: option_type ({"call", "put"}, default="call") – Vanilla option family.
Returns:: Report object with to_markdown(), to_html(), and to_pdf() export methods.
Return type:: ExportableReport

diagnostics(option_type='call')¶

Return a complete scalar derivative diagnostics report.

Parameters:: option_type ({"call", "put"}, default="call") – Vanilla option family.
Returns:: Immutable price, decomposition, moneyness, Greek, and break-even report for this model.
Return type:: DerivativeDiagnosticsReport

abaquant.derivatives.models.diagnostics.break_even_price(model, option_type)¶

Return a premium-adjusted terminal break-even price.

Parameters:

model (object) – Scalar pricing model exposing price and strike inputs.
option_type ({"call", "put"}) – Vanilla option family.

Returns:

strike_price + premium for calls and strike_price - premium for puts, ignoring financing and trading frictions.

Return type:

float

abaquant.derivatives.models.diagnostics.current_extrinsic_value(model, option_type)¶

Return the model value in excess of current intrinsic value.

Parameters:

model (object) – Scalar pricing model exposing price and vanilla payoff inputs.
option_type ({"call", "put"}) – Vanilla option family.

Returns:

Extrinsic value, equal to model price minus current intrinsic value.

Return type:

float

abaquant.derivatives.models.diagnostics.current_intrinsic_value(model, option_type)¶

Return the current intrinsic value for a scalar pricing model.

Parameters:

model (object) – Model exposing spot_price and strike_price attributes.
option_type ({"call", "put"}) – Vanilla option family.

Returns:

Current intrinsic value in currency units.

Return type:

float

abaquant.derivatives.models.diagnostics.derivative_diagnostics(model, option_type='call')¶

Build a complete scalar diagnostics report for one vanilla derivative.

Parameters:

model (object) – Scalar option-pricing model exposing call_price(), put_price(), spot_price, and strike_price.
option_type ({"call", "put"}, default="call") – Vanilla option family.

Returns:

Immutable scalar diagnostics report.

Return type:

DerivativeDiagnosticsReport

abaquant.derivatives.models.diagnostics.derivative_scenario_grid(model, *, spot_prices, volatilities, option_type='call')¶

Evaluate a vanilla option model over spot and volatility scenarios.

Parameters:

model (object) – Scalar option-pricing model exposing spot, strike, price, and a supported volatility-like attribute.
spot_prices (Sequence[float]) – Underlying prices used for the spot scenario axis.
volatilities (Sequence[float]) – Annualized decimal volatility values used for the volatility axis.
option_type ({"call", "put"}, default="call") – Vanilla option family to price in every grid cell.

Returns:

Long-form grid containing prices, decomposition, moneyness, break-even, and Greeks where available.

Return type:

DerivativeScenarioGrid

abaquant.derivatives.models.diagnostics.forward_moneyness(model)¶

Return forward moneyness for a scalar model.

Parameters:: model (object) – Model exposing strike_price and either forward_price or the spot/rate/dividend/maturity inputs needed to form a forward price.
Returns:: Ratio of forward price to strike price.
Return type:: float

abaquant.derivatives.models.diagnostics.model_greeks(model, option_type)¶

Return option-specific Greeks when a model exposes them.

Parameters:

model (object) – Pricing model that may expose a greeks() method.
option_type ({"call", "put"}) – Vanilla option family.

Returns:

Normalized option-specific Greek mapping. An empty dictionary is returned when the model has no Greek method.

Return type:

dict[str, float]

abaquant.derivatives.models.diagnostics.option_price(model, option_type)¶

Return the call or put price from a scalar pricing model.

Parameters:

model (object) – Pricing model exposing call_price() and put_price() methods.
option_type ({"call", "put"}) – Vanilla option family.

Returns:

Model option value in currency units.

Return type:

float

abaquant.derivatives.models.diagnostics.select_option_greeks(raw_greeks, option_type)¶

Select option-specific Greek names from a raw model Greek mapping.

Parameters:

raw_greeks (Mapping[str, object]) – Raw mapping returned by a model’s greeks() method. The function accepts both generic keys such as "gamma" and option-specific keys such as "call_delta".
option_type ({"call", "put"}) – Vanilla option family used to resolve option-specific keys.

Returns:

Normalized Greek dictionary using canonical names where available: delta, gamma, vega, theta, rho, vanna, volga, and charm.

Return type:

dict[str, float]

abaquant.derivatives.models.diagnostics.spot_moneyness(model)¶

Return spot moneyness for a scalar model.

Parameters:: model (object) – Model exposing spot_price and strike_price.
Returns:: Ratio spot_price / strike_price.
Return type:: float

abaquant.derivatives.models.diagnostics.validate_option_type(option_type)¶

Normalize and validate a vanilla option type label.

Parameters:: option_type (str) – Candidate option type label.
Returns:: Normalized option type, either "call" or "put".
Return type:: str
Raises:: ValueError – If option_type is not "call" or "put".

abaquant.derivatives.models.diagnostics.vanilla_intrinsic_value_from_prices(spot_price, strike_price, option_type)¶

Return the current intrinsic value of a vanilla option.

Parameters:

spot_price (float) – Current underlying price.
strike_price (float) – Option strike price.
option_type ({"call", "put"}) – Vanilla option family.

Returns:

Current intrinsic value, max(S-K, 0) for a call and max(K-S, 0) for a put.

Return type:

float