FXDeltaVolSmile#

class rateslib.fx_volatility.FXDeltaVolSmile(nodes, eval_date, expiry, delta_type, id=NoInput.blank, ad=0)#

Bases: _BaseSmile

Create an FX Volatility Smile at a given expiry indexed by delta percent.

See also the FX Vol Surfaces section in the user guide.

Parameters:

  • nodes (dict[float, DualTypes]) – Key-value pairs for a delta index amount and associated volatility. See examples.

  • eval_date (datetime) – Acts as the initial node of a Curve. Should be assigned today’s immediate date.

  • expiry (datetime) – The expiry date of the options associated with this Smile

  • delta_type (str in {"spot", "spot_pa", "forward", "forward_pa"}) – The type of delta calculation that is used on the options to attain a delta which is referenced by the node keys.

  • id (str, optional) – The unique identifier to distinguish between Smiles in a multicurrency framework and/or Surface.

  • ad (int, optional) – Sets the automatic differentiation order. Defines whether to convert node values to float, Dual or Dual2. It is advised against using this setting directly. It is mainly used internally.

Notes

The delta axis of this Smile is a negated put delta, i.e. 0.25 corresponds to a put delta of -0.25. This permits increasing strike for increasing delta index. For a ‘forward’ delta type 0.25 corresponds to a call delta of 0.75 via put-call delta parity. For a ‘spot’ delta type it would not because under a ‘spot’ delta type put-call delta parity is not 1.0, but related to the spot versus forward interest rates.

The interpolation function between nodes is a cubic spline.

  • For an unadjusted delta_type the range of the delta index is set to [0,1], and the cubic spline is natural with second order derivatives set to zero at the endpoints.

  • For premium adjusted delta_types the range of the delta index is in [0, d] where d is set large enough to encompass 99.99% of all possible values. The right endpoint is clamped with a first derivative of zero to avoid uncontrolled behaviour. The value of d is derived using \(d = e^{\sigma \sqrt{t} (3.75 + \frac{1}{2} \sigma \sqrt{t})}\)

Attributes Summary

ad

Int in {0,1,2} describing the AD order associated with the Smile.

id

A str identifier to name the Smile used in Solver mappings.

meta

An instance of _FXSmileMeta.

nodes

An instance of _FXDeltaVolSmileNodes.

Methods Summary

get(delta, delta_type, phi, z_w)

Return a volatility for a provided real option delta.

get_from_strike(k, f[, expiry, w_deli, w_spot])

Given an option strike return associated delta and vol values.

plot([comparators, labels, x_axis, f])

Plot volatilities associated with the Smile.

update(nodes)

Update a Smile with new, manually passed nodes.

update_node(key, value)

Update a single node value on the Smile.

Attributes Documentation

ad#

Int in {0,1,2} describing the AD order associated with the Smile.

id#

A str identifier to name the Smile used in Solver mappings.

meta#

An instance of _FXSmileMeta.

nodes#

An instance of _FXDeltaVolSmileNodes.

Methods Documentation

get(delta, delta_type, phi, z_w)#

Return a volatility for a provided real option delta.

This function is more explicit than the __getitem__ method of the Smile because it permits forward/spot, adjusted/unadjusted and put/call option delta conversions, by deriving an appropriate delta index relevant to that of the Smile delta_type.

Parameters:

  • delta (float) – The delta to obtain a volatility for.

  • delta_type (str in {"spot", "spot_pa", "forward", "forward_pa"}) – The delta type the given delta is expressed in.

  • phi (float) – Whether the given delta is assigned to a put or call option.

  • z_w (DualTypes) – Required only for spot delta types. This is a scaling factor between spot and forward rate, equal to \(w_(m_{delivery})/w_(m_{spot})\), where w is curve for the domestic currency collateralised in the foreign currency. If not required enter 1.0.

Return type:

DualTypes

get_from_strike(k, f, expiry=NoInput.blank, w_deli=NoInput.blank, w_spot=NoInput.blank)#

Given an option strike return associated delta and vol values.

Parameters:

  • k (float, Dual, Dual2) – The strike of the option.

  • f (float, Dual, Dual2) – The forward rate at delivery of the option.

  • expiry (datetime, optional) – Typically used with Surfaces. If given, performs a check to ensure consistency of valuations. Raises if expiry requested and expiry of the Smile do not match. Used internally.

  • w_deli (DualTypes, optional) – Required only for spot/forward conversions.

  • w_spot (DualTypes, optional) – Required only for spot/forward conversions.

Returns:

tuple of float, Dual, Dual2

Return type:

(delta index, vol, k)

Notes

This function will return a delta index associated with the FXDeltaVolSmile and the volatility attributed to the delta at that point. Recall that the delta index is the negated put option delta for the given strike k.

plot(comparators=NoInput.blank, labels=NoInput.blank, x_axis=NoInput.blank, f=NoInput.blank)#

Plot volatilities associated with the Smile.

Warning

The ‘delta’ x_axis type for a SabrSmile is calculated based on a forward, unadjusted delta and is expressed as a negated put option delta consistent with the definition for a FXDeltaVolSmile.

Parameters:

  • comparators (list[Smile]) – A list of Smiles which to include on the same plot as comparators. Note the comments on FXDeltaVolSmile.plot.

  • labels (list[str]) – A list of strings associated with the plot and comparators. Must be same length as number of plots.

  • x_axis (str in {"strike", "moneyness", "delta"}) – ‘strike’ is the natural option for this SabrSmile types while ‘delta’ is the natural choice for DeltaVolSmile types. If ‘delta’ see the warning. If ‘moneyness’ the strikes are converted using f.

  • f (DualTypes) – The FX forward rate at delivery.

Returns:

(fig, ax, line)

Return type:

Matplotlib.Figure, Matplotplib.Axes, Matplotlib.Lines2D

update(nodes)#

Update a Smile with new, manually passed nodes.

For arguments see FXDeltaVolSmile

Return type:

None

Notes

Warning

Rateslib is an object-oriented library that uses complex associations. Although Python may not object to directly mutating attributes of a Smile instance, this should be avoided in rateslib. Only use official update methods to mutate the values of an existing Smile instance. This class is labelled as a mutable on update object.

update_node(key, value)#

Update a single node value on the Smile.

Parameters:

  • key (float) – The node date to update. Must exist in nodes.

  • value (float, Dual, Dual2, Variable) – Value to update on the Curve.

Return type:

None

Notes

Warning

Rateslib is an object-oriented library that uses complex associations. Although Python may not object to directly mutating attributes of a Curve instance, this should be avoided in rateslib. Only use official update methods to mutate the values of an existing Curve instance. This class is labelled as a mutable on update object.

Warning

This method does not validate the AD order of the input value. Ensure that any supplied values are consistent with the AD order of the object.