FXOption#

class rateslib.instruments.FXOption(pair, expiry, notional=NoInput.blank, eval_date=NoInput.blank, calendar=NoInput.blank, modifier=NoInput.blank, eom=NoInput.blank, delivery_lag=NoInput.blank, strike=NoInput.blank, premium=NoInput.blank, premium_ccy=NoInput.blank, payment_lag=NoInput.blank, option_fixing=NoInput.blank, delta_type=NoInput.blank, metric=NoInput.blank, curves=NoInput.blank, vol=NoInput.blank, spec=NoInput.blank)#

Bases: Sensitivities

Create an FX Option.

Parameters:

pair (str) – The currency pair for the FX rate which settles the option, in 3-digit codes, e.g. “eurusd”.
expiry (datetime, str) – The expiry of the option. If given in string tenor format, e.g. “1M” requires an eval_date. See notes.
notional (float, optional (defaults.notional)) – The amount in ccy1 (left side of pair) on which the option is based.
strike (float, Dual, Dual2, str in {"atm_forward", "atm_spot", "atm_delta", "[float]d"}) – The strike value of the option. If str, there are four possibilities as above. If giving a specific delta should end with a ‘d’ for delta e.g. “-25d”. Put deltas should be input including negative sign.
eval_date (datetime, optional) – Should be entered as today (also called horizon) and not spot. Spot is derived from delivery_lag and calendar.
modifier (str, optional (defaults.modifier)) – The modification rule, in {“F”, “MF”, “P”, “MP”} for date evaluation.
eom (bool, optional (defaults.eom_fx)) – Whether to use end-of-month rolls when expiry is given as a month or year tenor.
calendar (calendar or str, optional) – The holiday calendar object to use. If str, looks up named calendar from static data.
delivery_lag (int, optional (defaults.fx_delivery_lag)) – The number of business days after expiry that the physical settlement of the FX exchange occurs.
payment_lag (int or datetime, optional (defaults.payment_lag)) – The number of business days after expiry to pay premium. If a datetime is given this will set the premium date explicitly.
premium (float, optional) – The amount paid for the option. If not given assumes an unpriced Option and sets this as mid-market premium during pricing.
premium_ccy (str, optional (RHS)) – The currency in which the premium is paid. Can only be one of the two currencies in pair.
option_fixing (float) – The value determined at expiry to set the moneyness of the option.
delta_type (str in {"spot", "forward"}, optional (defaults.fx_delta_type)) – When deriving strike from delta use the equation associated with spot or forward delta. If premium currency is ccy1 (left side of pair) then this will produce premium adjusted delta values. If the premium_ccy is ccy2 (right side of pair) then delta values are unadjusted.
metric (str in {"pips_or_%", "vol", "premium"}, optional ("pips_or_%")) – The pricing metric returned by the rate method.
curves (Curve, LineCurve, str or list of such, optional) – For FXOptions curves should be expressed as a list with the discount curves entered either as Curve or str for discounting cashflows in the appropriate currency with a consistent collateral on each side. E.g. [None, “eurusd”, None, “usdusd”]. Forecasting curves are not relevant.
spec (str, optional) – An identifier to pre-populate many field with conventional values. See here for more info and available values.

Notes

Date calculations for FXOption products are very specific. See ‘Expiry and Delivery Rules’ in FX Option Pricing by I. Clark. Rateslib uses calendars with associated settlement calendars and the recognised market convention rules to derive dates.

In [1]: fxc = FXCall(
   ...:     pair="eursek",
   ...:     expiry="2M",
   ...:     eval_date=dt(2024, 6, 19),  # <- Wednesday
   ...:     strike=11.0,
   ...:     modifier="mf",
   ...:     calendar="tgt,stk|fed",
   ...:     delivery_lag=2,
   ...:     payment_lag=2,
   ...: )
   ...: 

In [2]: fxc.kwargs["delivery"]  # <- '2M' out of spot: Monday 24 Jun 2024
Out[2]: datetime.datetime(2024, 8, 26, 0, 0)

In [3]: fxc.kwargs["expiry"]    # <- '2b' before 'delivery'
Out[3]: datetime.datetime(2024, 8, 22, 0, 0)

In [4]: fxc.kwargs["payment"]  # <- '2b' after 'expiry'
Out[4]: datetime.datetime(2024, 8, 26, 0, 0)

Attributes Summary

style

Methods Summary

`analytic_greeks`([curves, solver, fx, base, ...])	Return various pricing metrics of the FX Option.
`cashflows`([curves, solver, fx, base, vol])	Return the properties of all periods used in calculating cashflows.
`cashflows_table`([curves, solver, fx, base])	Aggregate the values derived from a `cashflows()` method on an Instrument.
`delta`([curves, solver, fx, base, local])	Calculate delta risk of an Instrument against the calibrating instruments in a `Solver`.
`gamma`([curves, solver, fx, base, local])	Calculate cross-gamma risk of an Instrument against the calibrating instruments of a `Solver`.
`npv`([curves, solver, fx, base, local, vol])	Return the NPV of the Option.
`plot_payoff`([range, curves, solver, fx, ...])
`rate`([curves, solver, fx, base, vol, metric])	Return various pricing metrics of the FX Option.

Attributes Documentation

style = 'european'#

Methods Documentation

analytic_greeks(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank, local=False, vol=NoInput.blank)#

Return various pricing metrics of the FX Option.

Parameters:

curves (list of Curve) – Curves for discounting cashflows. List follows the structure used by IRDs and should be given as: [None, Curve for domestic ccy, None, Curve for foreign ccy]
solver (Solver, optional) – The numerical Solver that constructs Curves from calibrating instruments.
fx (FXForwards) – The object to project the relevant forward and spot FX rates.
base (str, optional) – Not used by analytic_greeks.
local (bool,) – Not used by analytic_greeks.
vol (float, or FXDeltaVolSmile) – The volatility used in calculation.

Return type:

float, Dual, Dual2

cashflows(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank, vol=NoInput.blank)#

Return the properties of all periods used in calculating cashflows.

Parameters:

curves (list of Curve) – Curves for discounting cashflows. List follows the structure used by IRDs and should be given as: [None, Curve for domestic ccy, None, Curve for foreign ccy]
solver (Solver, optional) – The numerical Solver that constructs Curves from calibrating instruments.
fx (FXForwards) – The object to project the relevant forward and spot FX rates.
base (str, optional) – Not used by rate.
vol (float, Dual, Dual2 or FXDeltaVolSmile) – The volatility used in calculation.

Return type:

DataFrame

cashflows_table(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank, **kwargs)#

Aggregate the values derived from a cashflows() method on an Instrument.

Parameters:

curves (CurveType, str or list of such, optional) – Argument input to the underlying cashflows method of the Instrument.
solver (Solver, optional) – Argument input to the underlying cashflows method of the Instrument.
fx (float, FXRates, FXForwards, optional) – Argument input to the underlying cashflows method of the Instrument.
base (str, optional) – Argument input to the underlying cashflows method of the Instrument.
kwargs (dict) – Additional arguments input the underlying cashflows method of the Instrument.

Return type:

DataFrame

delta(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank, local=False, **kwargs)#

Calculate delta risk of an Instrument against the calibrating instruments in a Solver.

Parameters:

curves (Curve, str or list of such, optional) –
A single Curve or id or a list of such. A list defines the following curves in the order:
- Forecasting Curve for leg1.
- Discounting Curve for leg1.
- Forecasting Curve for leg2.
- Discounting Curve for leg2.
solver (Solver, optional) – The Solver that calibrates Curves from given Instruments.
fx (float, FXRates, FXForwards, optional) – The immediate settlement FX rate that will be used to convert values into another currency. A given float is used directly. If giving a FXRates or FXForwards object, converts from local currency into base.
base (str, optional) – The base currency to convert cashflows into (3-digit code), set by default. Only used if fx_rate is an FXRates or FXForwards object.
local (bool, optional) – If True will ignore base - this is equivalent to setting base to None. Included only for argument signature consistent with npv.

Return type:

DataFrame

gamma(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank, local=False, **kwargs)#

Calculate cross-gamma risk of an Instrument against the calibrating instruments of a Solver.

Parameters:

curves (Curve, str or list of such, optional) –
A single Curve or id or a list of such. A list defines the following curves in the order:
- Forecasting Curve for leg1.
- Discounting Curve for leg1.
- Forecasting Curve for leg2.
- Discounting Curve for leg2.
solver (Solver, optional) – The Solver that calibrates Curves from given Instruments.
fx (float, FXRates, FXForwards, optional) – The immediate settlement FX rate that will be used to convert values into another currency. A given float is used directly. If giving a FXRates or FXForwards object, converts from local currency into base.
base (str, optional) – The base currency to convert cashflows into (3-digit code), set by default. Only used if fx_rate is an FXRates or FXForwards object.
local (bool, optional) – If True will ignore base. This is equivalent to setting base to None. Included only for argument signature consistent with npv.

Return type:

DataFrame

npv(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank, local=False, vol=NoInput.blank)#

Return the NPV of the Option.

Parameters:

curves (list of Curve) – Curves for discounting cashflows. List follows the structure used by IRDs and should be given as: [None, Curve for domestic ccy, None, Curve for foreign ccy]
solver (Solver, optional) – The numerical Solver that constructs Curves, Smiles or Surfaces from calibrating instruments.
fx (FXForwards) – The object to project the relevant forward and spot FX rates.
base (str, optional) – The base currency to convert cashflows into (3-digit code). If not given defaults to fx.base.
local (bool, optional) – If True will return a dict identifying NPV by local currencies on each period.

Return type:

float, Dual, Dual2 or dict of such.

plot_payoff(range=NoInput.blank, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank, local=False, vol=NoInput.blank)#

rate(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank, vol=NoInput.blank, metric=NoInput.blank)#

Return various pricing metrics of the FX Option.

Parameters:

curves (list of Curve) – Curves for discounting cashflows. List follows the structure used by IRDs and should be given as: [None, Curve for domestic ccy, None, Curve for foreign ccy]
solver (Solver, optional) – The numerical Solver that constructs Curves, Smiles or Surfaces from calibrating instruments.
fx (FXForwards) – The object to project the relevant forward and spot FX rates.
base (str, optional) – 3-digit currency to express values in (not used by the rate method).
vol (float, Dual, Dual2, FXDeltaVolSmile or FXDeltaVolSurface) – The volatility used in calculation.
metric (str in {"pips_or_%", "vol", "premium"}, optional) – The pricing metric type to return. See notes.

Return type:

float, Dual, Dual2

Notes

The available choices for the pricing metric that can be used are:

“pips_or_%”: if the premium_ccy is the foreign (RHS) currency then pips will be returned, else if the premium is the domestic (LHS) currency then % of notional will be returned.
“vol”: the volatility used to price the option at that strike / delta is returned.
“premium”: the monetary amount in premium_ccy payable at the payment date is returned.

If calculating the rate of an FXOptionStrat then the attributes rate_weight and rate_weight_vol will be used to combine the output for each individual FXOption within the strategy.

FXStrangle and FXBrokerFly have the additional metric ‘single_vol’ which is a more complex and integrated calculation.

FXOption#

This Page