FXStrangle#

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

Bases: _BaseFXOptionStrat

An FX Strangle _BaseFXOptionStrat.

A Strangle is composed of a lower strike FXPut and a higher strike FXCall.

Examples

In [1]: fxs = FXStrangle(
   ...:     expiry="3m",
   ...:     strike=["-10d", "10d"],
   ...:     eval_date=dt(2020, 1, 1),
   ...:     spec="eurusd_call",
   ...:     notional=1000000,
   ...: )
   ...: 

In [2]: fxs.cashflows()
Out[2]: 
                      Type  Ccy    Payment   Notional    DF  Cashflow   NPV  FX Rate Base Ccy NPV Ccy Collateral
inst0 leg1 0   FXPutPeriod  USD 2020-04-03  1000000.0  None       NaN  None      1.0      USD    None       None
      leg2 0      Cashflow  USD 2020-04-03        0.0  None      -0.0  None      1.0      USD    None       None
inst1 leg1 0  FXCallPeriod  USD 2020-04-03  1000000.0  None       NaN  None      1.0      USD    None       None
      leg2 0      Cashflow  USD 2020-04-03        0.0  None      -0.0  None      1.0      USD    None       None

Pricing

The pricing mirrors that for an FXCall. All options use the same curves. Allowable inputs are:

curves = [rate_curve, disc_curve]  #  two curves are applied in the given order
curves = {"rate_curve": rate_curve, "disc_curve": disc_curve}  # dict form is explicit

Any FXOption also requires an FXForwards as input to the fx argument.

A vol argument must be provided to each Instrument. This can either be a single value universally used for all, or an individual item as part of a sequence. Allowed inputs are:

vol = 12.0 | vol_obj  # a single item universally applied
vol = [12.0, 12.0]  # values for the Put and Call respectively

FXStrangles have peculiar market conventions. If the strikes are given as delta percentages then numeric values will first be derived using the ‘single_vol’ approach. Any ‘premium’ or ‘pips_or_%’ values can then be calculated using those strikes and this volatility. The following pricing metric are available, with examples:

In [3]: eur = Curve({dt(2020, 1, 1): 1.0, dt(2021, 1, 1): 0.98})

In [4]: usd = Curve({dt(2020, 1, 1): 1.0, dt(2021, 1, 1): 0.96})

In [5]: fxf = FXForwards(
   ...:     fx_rates=FXRates({"eurusd": 1.10}, settlement=dt(2020, 1, 3)),
   ...:     fx_curves={"eureur": eur, "eurusd": eur, "usdusd": usd},
   ...: )
   ...: 

In [6]: fxvs = FXDeltaVolSmile(
   ...:     nodes={0.25: 11.0, 0.5: 9.8, 0.75: 10.7},
   ...:     expiry=dt(2020, 4, 1),
   ...:     eval_date=dt(2020, 1, 1),
   ...:     delta_type="forward",
   ...: )
   ...:

  • ‘single_vol’: the singular volatility value that when applied to each option separately yields a summed premium amount equal to the summed premium when each option is valued with the appropriate volatility from an object (with the strikes determined by the single vol). ‘vol’ is an alias for single vol and returns the same value.

    In [7]: fxs.rate(vol=fxvs, curves=[eur, usd], fx=fxf, metric="single_vol")
Out[7]: <Dual: 12.163490, (762861, 762860, 7bc231, ...), [0.2, -0.2, -0.0, ...]>

In [8]: fxs.rate(vol=[12.163490, 12.163490], curves=[eur, usd], fx=fxf, metric="premium")
Out[8]: <Dual: 6400.519064, (762861, 762860, 7bc231, ...), [-295.8, 6690.4, -1694.1, ...]>

    This requires an iterative calculation for which the tolerance is set to 1e-6 with a maximum allowed number of iterations of 10.

  • ‘premium’: the summed cash premium amount, of both options, applicable to the ‘payment’ date. If strikes are given as delta percentages then they are first determined using the ‘single_vol’.

    In [9]: fxs.rate(vol=fxvs, curves=[eur, usd], fx=fxf, metric="premium")
Out[9]: <Dual: 6400.518927, (762861, 762860, 7bc231, ...), [-165.4, 6562.6, -1694.1, ...]>

  • ‘pips_or_%’: if the premium currency is LHS of pair this is a % of notional, whilst if the premium currency is RHS this gives a number of pips of the FX rate. Summed over both options. For strikes set with delta percentages these are first determined using the ‘single_vol’.

    In [10]: fxs.rate(vol=fxvs, curves=[eur, usd], fx=fxf, metric="pips_or_%")
Out[10]: <Dual: 64.005189, (762861, 762860, 7bc231, ...), [-1.7, 65.6, -16.9, ...]>
Parameters:

  • . –

    Note

    The following define fx option and generalised settlement parameters.

  • expiry (datetime, str, required) – The expiry of the option. If given in string tenor format, e.g. “1M” requires an eval_date. See Notes.

  • strike (2-tuple of float, Variable, str, required) – The strikes of the put and the call in order.

  • pair (str, required) – The currency pair for the FX rate which settles the option, in 3-digit codes, e.g. “eurusd”. May be included as part of spec.

  • notional (float, optional (set by ‘defaults’)) – The notional amount of each option expressed in units of LHS of pair.

  • eval_date (datetime, optional) – Only required if expiry is given as string tenor. Should be entered as today (also called horizon) and not spot. Spot is derived from delivery_lag and calendar.

  • modifier (str, optional (set by ‘defaults’)) – The modification rule, in {“F”, “MF”, “P”, “MP”} for date evaluation.

  • eom (bool, optional (set by ‘defaults’)) – 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 (set by ‘defaults’)) – The number of business days after expiry that the physical settlement of the FX exchange occurs.

  • payment_lag (int or datetime, optional (set by ‘defaults’)) – The number of business days after expiry to pay premium. If a datetime is given this will set the premium date explicitly.

  • premium_ccy (str, optional (set as RHS of ‘pair’)) – The currency in which the premium is paid. Can only be one of the two currencies in pair.

  • delta_type (FXDeltaMethod, str, optional (set by ‘defaults’)) –

    When deriving strike from delta use the equation associated with ‘spot’ or ‘forward’ delta. If premium currency is LHS of pair then this will produce premium adjusted delta values. If the premium_ccy is RHS of pair then delta values are unadjusted.

    Note

    The following define additional rate parameters.

  • premium (2-tuple of float, optional) – The amount paid for the put and call in order. If not given assumes unpriced Options and sets this as mid-market premium during pricing.

  • option_fixings (2-tuple of float, Dual, Dual2, Variable, Series, str, optional) –

    The value of each option’s FXFixing. If a scalar, is used directly. If a string identifier, links to the central fixings object and data loader.

    Note

    The following are meta parameters.

  • metric (str, optional (set as “single_vol”)) – The pricing metric returned by the rate method. See Pricing.

  • curves (_BaseCurve, str, dict, _Curves, Sequence, optional) – Pricing objects passed directly to the Instrument’s methods’ curves argument. See Pricing.

  • vol (str, Smile, Surface, float, Dual, Dual2, Variable, Sequence) – Pricing objects passed directly to the Instrument’s methods’ vol argument. See Pricing.

  • spec (str, optional) – An identifier to pre-populate many field with conventional values. See here for more info and available values.

Attributes Summary

instruments

kwargs

The _KWArgs of the Instrument.

leg1

The CustomLeg of the Instrument containing the FXOptionPeriod.

leg2

The CustomLeg of the Instrument containing the premium Cashflow.

legs

A list of the Legs of the Instrument.

rate_scalar

A scaling quantity associated with the Solver risk calculations.

settlement_params

The default _SettlementParams of the Instrument.

Methods Summary

analytic_delta(*args[, leg])

Not implemented for Option types.

analytic_greeks([curves, solver, fx, vol])

Return various pricing metrics of the FX Option.

cashflows(*[, curves, solver, fx, vol, ...])

Return aggregated cashflow data for the Instrument.

cashflows_table(*[, curves, solver, fx, ...])

Aggregate the values derived from a cashflows(), grouped by date, settlement currency and collateral.

delta(*[, curves, solver, fx, vol, base, ...])

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

exo_delta(*[, curves, solver, fx, vol, ...])

Calculate delta risk of an Instrument against some exogenous user created Variables, via a Solver.

gamma(*[, curves, solver, fx, vol, base, ...])

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

local_analytic_rate_fixings(*[, curves, ...])

Calculate the sensitivity to rate fixings of the Instrument, expressed in local settlement currency per basis point.

local_fixings(identifiers[, scalars, ...])

Calculate the sensitivity to fixings of the Instrument, expressed in local settlement currency.

npv(*[, curves, solver, fx, vol, base, ...])

Calculate the NPV of the Instrument converted to any other base accounting currency.

plot_payoff([range, curves, solver, fx, ...])

Return a plot of the payoff at expiry, indexed by the FXFixing value.

rate(*[, curves, solver, fx, vol, base, ...])

Calculate some pricing rate metric for the Instrument.

reset_fixings([state])

Resets any fixings values of the Instrument derived using the given data state.

spread(*[, curves, solver, fx, vol, base, ...])

Not implemented for Option types.

Attributes Documentation

instruments#
kwargs#

The _KWArgs of the Instrument.

leg1#

The CustomLeg of the Instrument containing the FXOptionPeriod.

leg2#

The CustomLeg of the Instrument containing the premium Cashflow.

legs#

A list of the Legs of the Instrument.

rate_scalar#

A scaling quantity associated with the Solver risk calculations.

settlement_params#

The default _SettlementParams of the Instrument.

This is used to define a base currency when one is not specified.

Methods Documentation

analytic_delta(*args, leg=1, **kwargs)#

Not implemented for Option types. Use analytic_greeks().

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

Return various pricing metrics of the FX Option.

Examples

In [11]: eur = Curve({dt(2020, 1, 1): 1.0, dt(2021, 1, 1): 0.98})

In [12]: usd = Curve({dt(2020, 1, 1): 1.0, dt(2021, 1, 1): 0.96})

In [13]: fxf = FXForwards(
   ....:     fx_rates=FXRates({"eurusd": 1.10}, settlement=dt(2020, 1, 3)),
   ....:     fx_curves={"eureur": eur, "eurusd": eur, "usdusd": usd},
   ....: )
   ....: 

In [14]: fxvs = FXDeltaVolSmile(
   ....:     nodes={0.25: 11.0, 0.5: 9.8, 0.75: 10.7},
   ....:     delta_type="forward",
   ....:     eval_date=dt(2020, 1, 1),
   ....:     expiry=dt(2020, 4, 1)
   ....: )
   ....: 

In [15]: fxc = FXCall(
   ....:     expiry="3m",
   ....:     strike=1.10,
   ....:     eval_date=dt(2020, 1, 1),
   ....:     spec="eurusd_call",
   ....: )
   ....: 

In [16]: fxc.analytic_greeks(fx=fxf, curves=[eur, usd], vol=fxvs)
Out[16]: 
{'gamma': <Dual: 7.253419, (fx_eurusd), [-37.2]>,
 'vega': <Dual: 0.216177, (fx_eurusd), [-0.3]>,
 '_kega': <Dual: -0.043519, (fx_eurusd), [-10.0]>,
 '_kappa': <Dual: -0.526091, (fx_eurusd), [-7.2]>,
 '_delta_index': <Dual: 0.448847, (fx_eurusd), [-7.2]>,
 '__delta_type': <FXDeltaMethod.Spot: 1>,
 '__vol': <Dual: 0.098816, (fx_eurusd), [0.2]>,
 '__strike': 1.1,
 '__forward': <Dual: 1.105654, (fx_eurusd), [1.0]>,
 '__sqrt_t': 0.49931459871823364,
 '__bs76': <Dual: 0.024395, (fx_eurusd), [0.6]>,
 '__notional': 1000000.0,
 '__class': 'FXCallPeriod',
 'delta': <Dual: 0.548391, (fx_eurusd), [7.2]>,
 'delta_eur': <Dual: 548391.021065, (fx_eurusd), [7195052.9]>,
 'gamma_eur_1%': <Dual: 79787.606331, (fx_eurusd), [-336787.9]>,
 'vega_usd': <Dual: 2161.767238, (fx_eurusd), [-3114.7]>,
 'delta_sticky': <Dual: 0.588371, (fx_eurusd), [10.9]>,
 'vomma': <Dual: 0.022286, (fx_eurusd), [8.2]>,
 'vanna': <Dual: -0.315659, (fx_eurusd), [-71.1]>}
Parameters:

  • curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.

  • solver (Solver, optional) – A Solver object containing Curve, Smile, Surface, or Cube mappings for pricing.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting FX rates, if necessary.

  • vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.

Return type:

dict

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

Return aggregated cashflow data for the Instrument.

Warning

This method is a convenience method to provide a visual representation of all associated calculation data. Calling this method to extract certain values should be avoided. It is more efficient to source relevant parameters or calculations from object attributes or other methods directly.

Examples

In [17]: irs = IRS(dt(2000, 1, 1), "3Y", spec="usd_irs", fixed_rate=1.0)

In [18]: irs.cashflows()
Out[18]: 
               Type  Ccy    Payment   Notional   Period Convention       DCF  Acc Start    Acc End    DF      Cashflow   NPV  FX Rate Base Ccy NPV Ccy Collateral  Rate  Spread
leg1 0  FixedPeriod  USD 2001-01-04  1000000.0  Regular     Act360  1.013889 2000-01-03 2001-01-02  None -10138.888889  None      1.0      USD    None       None   1.0     NaN
     1  FixedPeriod  USD 2002-01-04  1000000.0  Regular     Act360  1.013889 2001-01-02 2002-01-02  None -10138.888889  None      1.0      USD    None       None   1.0     NaN
     2  FixedPeriod  USD 2003-01-06  1000000.0  Regular     Act360  1.013889 2002-01-02 2003-01-02  None -10138.888889  None      1.0      USD    None       None   1.0     NaN
leg2 0  FloatPeriod  USD 2001-01-04 -1000000.0  Regular     Act360  1.013889 2000-01-03 2001-01-02  None           NaN  None      1.0      USD    None       None   NaN     0.0
     1  FloatPeriod  USD 2002-01-04 -1000000.0  Regular     Act360  1.013889 2001-01-02 2002-01-02  None           NaN  None      1.0      USD    None       None   NaN     0.0
     2  FloatPeriod  USD 2003-01-06 -1000000.0  Regular     Act360  1.013889 2002-01-02 2003-01-02  None           NaN  None      1.0      USD    None       None   NaN     0.0

Providing relevant pricing objects will ensure all data that can be calculated is returned.

In [19]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2010, 1, 1): 0.75})

In [20]: irs.cashflows(curves=[curve])
Out[20]: 
               Type  Ccy    Payment   Notional   Period Convention       DCF  Acc Start    Acc End        DF      Cashflow           NPV  FX Rate Base Ccy       NPV Ccy Collateral      Rate  Spread
leg1 0  FixedPeriod  USD 2001-01-04  1000000.0  Regular     Act360  1.013889 2000-01-03 2001-01-02  0.971359 -10138.888889  -9848.496702      1.0      USD  -9848.496702       None  1.000000     NaN
     1  FixedPeriod  USD 2002-01-04  1000000.0  Regular     Act360  1.013889 2001-01-02 2002-01-02  0.943835 -10138.888889  -9569.435745      1.0      USD  -9569.435745       None  1.000000     NaN
     2  FixedPeriod  USD 2003-01-06  1000000.0  Regular     Act360  1.013889 2002-01-02 2003-01-02  0.916946 -10138.888889  -9296.817681      1.0      USD  -9296.817681       None  1.000000     NaN
leg2 0  FloatPeriod  USD 2001-01-04 -1000000.0  Regular     Act360  1.013889 2000-01-03 2001-01-02  0.971359  29161.694029  28326.461668      1.0      USD  28326.461668       None  2.876222     0.0
     1  FloatPeriod  USD 2002-01-04 -1000000.0  Regular     Act360  1.013889 2001-01-02 2002-01-02  0.943835  29161.694029  27523.820438      1.0      USD  27523.820438       None  2.876222     0.0
     2  FloatPeriod  USD 2003-01-06 -1000000.0  Regular     Act360  1.013889 2002-01-02 2003-01-02  0.916946  29161.694029  26739.710399      1.0      USD  26739.710399       None  2.876222     0.0
Parameters:

  • curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.

  • solver (Solver, optional) – A Solver object containing Curve, Smile, Surface, or Cube mappings for pricing.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting FX rates, if necessary.

  • vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.

  • base (str, optional (set to settlement currency)) – The currency to convert the local settlement NPV to.

  • settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.

  • forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

DataFrame

cashflows_table(*, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, base=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Aggregate the values derived from a cashflows(), grouped by date, settlement currency and collateral.

Examples

In [21]: irs = IRS(dt(2000, 1, 1), "3Y", spec="usd_irs", fixed_rate=1.0)

In [22]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2010, 1, 1): 0.75})

In [23]: irs.cashflows_table(curves=[curve])
Out[23]: 
local_ccy               USD
collateral_ccy          NaN
payment                    
2001-01-04      19022.80514
2002-01-04      19022.80514
2003-01-06      19022.80514
Parameters:

  • curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.

  • solver (Solver, optional) – A Solver object containing Curve, Smile, Surface, or Cube mappings for pricing.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting FX rates, if necessary.

  • vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.

  • base (str, optional (set to settlement currency)) – The currency to convert the local settlement NPV to.

  • local (bool, optional (set as False)) – An override flag to return a dict of NPV values indexed by string currency.

  • settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.

  • forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

DataFrame

delta(*, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, base=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

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

Examples

In [24]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2002, 1, 1): 0.85, dt(2010, 1, 1): 0.75})

In [25]: solver = Solver(
   ....:     curves=[curve],
   ....:     instruments=[
   ....:         IRS(dt(2000, 1, 1), "2Y", spec="usd_irs", curves=[curve]),
   ....:         IRS(dt(2000, 1, 1), "5Y", spec="usd_irs", curves=[curve]),
   ....:     ],
   ....:     s=[2.0, 2.25],
   ....:     instrument_labels=["2Y", "5Y"],
   ....:     id="US_RATES"
   ....: )
   ....: 
SUCCESS: `func_tol` reached after 6 iterations (levenberg_marquardt), `f_val`: 8.499591036903249e-16, `time`: 0.0029s

In [26]: irs = IRS(dt(2000, 1, 1), "3Y", spec="usd_irs", curves=[curve])

In [27]: irs.delta(solver=solver)
Out[27]: 
local_ccy                          usd
display_ccy                        usd
type        solver   label            
instruments US_RATES 2Y     129.580448
                     5Y     162.173287
Parameters:

  • curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.

  • solver (Solver, required) – A Solver object containing Curve, Smile, Surface, or Cube mappings for pricing.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting FX rates, if necessary.

  • vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.

  • base (str, optional (set to settlement currency)) – The currency to convert the local settlement NPV to.

  • settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.

  • forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

DataFrame

Notes

Delta measures the sensitivity of the PV to a change in any of the calibrating instruments of the given Solver. Values are returned according to the rate_scalar quantity at an Instrument level and according to the metric used to derive the rate() method of each Instrument.

exo_delta(*, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, base=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank, vars, vars_scalar=NoInput.blank, vars_labels=NoInput.blank)#

Calculate delta risk of an Instrument against some exogenous user created Variables, via a Solver.

See What are exogenous variables? in the cookbook.

Examples

This example calculates the risk of the fixed rate increasing by 1bp and the notional increasing by 1mm. Mathematically this should be equivalent to the npv and the analytic delta (although the calculation is based on AD and is completely independent of the solver).

In [28]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2002, 1, 1): 0.85, dt(2010, 1, 1): 0.75})

In [29]: solver = Solver(
   ....:     curves=[curve],
   ....:     instruments=[
   ....:         IRS(dt(2000, 1, 1), "2Y", spec="usd_irs", curves=[curve]),
   ....:         IRS(dt(2000, 1, 1), "5Y", spec="usd_irs", curves=[curve]),
   ....:     ],
   ....:     s=[2.0, 2.25],
   ....:     instrument_labels=["2Y", "5Y"],
   ....:     id="US_RATES"
   ....: )
   ....: 
SUCCESS: `func_tol` reached after 6 iterations (levenberg_marquardt), `f_val`: 8.499591036903249e-16, `time`: 0.0029s

In [30]: irs = IRS(dt(2000, 1, 1), "3Y", spec="usd_irs", fixed_rate=Variable(3.0, ["R"]), notional=Variable(1e6, ["N"]), curves=[curve])

In [31]: irs.exo_delta(solver=solver, vars=["R", "N"], vars_scalar=[1e-2, 1e6])
Out[31]: 
local_ccy                          usd
display_ccy                        usd
type      solver   label              
exogenous US_RATES R       -291.752073
                   N     -25123.690181

In [32]: irs.analytic_delta()
Out[32]: <Dual: 291.752073, (N, 1f9be0, 1f9be1, ...), [0.0, 49.2, 239.9, ...]>

In [33]: irs.npv()
Out[33]: <Dual: -25123.690181, (N, R, 1f9be0, ...), [-0.0, -29175.2, 982218.9, ...]>
Parameters:

  • curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.

  • solver (Solver, required) – A Solver object containing Curve, Smile, Surface, or Cube mappings for pricing.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting FX rates, if necessary.

  • vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.

  • base (str, optional (set to settlement currency)) – The currency to convert the local settlement NPV to.

  • settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.

  • forward (datetime, optional) – The future date to project the PV to using the disc_curve.

  • vars (list[str], required) – The variable tags which to determine sensitivities for.

  • vars_scalar (list[float], optional) – Scaling factors for each variable, for example converting rates to basis point etc. Defaults to ones.

  • vars_labels (list[str], optional) – Alternative names to relabel variables in DataFrames.

Return type:

DataFrame

gamma(*, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, base=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

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

Examples

In [34]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2002, 1, 1): 0.85, dt(2010, 1, 1): 0.75})

In [35]: solver = Solver(
   ....:     curves=[curve],
   ....:     instruments=[
   ....:         IRS(dt(2000, 1, 1), "2Y", spec="usd_irs", curves=[curve]),
   ....:         IRS(dt(2000, 1, 1), "5Y", spec="usd_irs", curves=[curve]),
   ....:     ],
   ....:     s=[2.0, 2.25],
   ....:     instrument_labels=["2Y", "5Y"],
   ....:     id="US_RATES"
   ....: )
   ....: 
SUCCESS: `func_tol` reached after 6 iterations (levenberg_marquardt), `f_val`: 8.499591036903249e-16, `time`: 0.0030s

In [36]: irs = IRS(dt(2000, 1, 1), "3Y", spec="usd_irs", curves=[curve])

In [37]: irs.gamma(solver=solver)
Out[37]: 
type                                             instruments          
solver                                              US_RATES          
label                                                     2Y        5Y
local_ccy display_ccy type        solver   label                      
usd       usd         instruments US_RATES 2Y      -0.029442 -0.038104
                                           5Y      -0.038104 -0.010190
Parameters:

  • curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.

  • solver (Solver, required) – A Solver object containing Curve, Smile, Surface, or Cube mappings for pricing.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting FX rates, if necessary.

  • vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.

  • base (str, optional (set to settlement currency)) – The currency to convert the local settlement NPV to.

  • settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.

  • forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

DataFrame

Notes

Gamma measures the second order cross-sensitivity of the PV to a change in any of the calibrating instruments of the given Solver. Values are returned according to the rate_scalar quantity at an Instrument level and according to the metric used to derive the rate() method of each Instrument.

local_analytic_rate_fixings(*, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Calculate the sensitivity to rate fixings of the Instrument, expressed in local settlement currency per basis point.

Examples

In [38]: curve1 = Curve({dt(2000, 1, 1): 1.0, dt(2010, 1, 1): 0.75}, id="Eur1mCurve")

In [39]: curve3 = Curve({dt(2000, 1, 1): 1.0, dt(2010, 1, 1): 0.70}, id="Eur3mCurve")

In [40]: irs = IRS(dt(2000, 1, 1), "20m", spec="eur_irs3", curves=[{"1m": curve1, "3m": curve3}, curve1])

In [41]: irs.local_analytic_rate_fixings()
Out[41]: 
identifier  Eur1mCurve Eur3mCurve
local_ccy          eur        eur
display_ccy        eur        eur
frequency           1M         3M
obs_dates                        
1999-12-30     8.81934   7.215824
2000-02-28         NaN  25.251470
2000-05-30         NaN  25.069179
2000-08-30         NaN  24.619619
2000-11-29         NaN  24.177105
2001-02-27         NaN  24.535960
2001-05-30         NaN  24.884455
Parameters:

  • curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.

  • solver (Solver, optional) – A Solver object containing Curve, Smile, Surface, or Cube mappings for pricing.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting FX rates, if necessary.

  • vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.

  • settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.

  • forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

DataFrame

Notes

This analytic method will index the sensitivities with series identifier according to the Curve id which has forecast the fixing.

local_fixings(identifiers, scalars=NoInput.blank, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Calculate the sensitivity to fixings of the Instrument, expressed in local settlement currency.

Parameters:

  • identifiers (Sequence of tuple[str, Series], required) – These are the series string identifiers and the data values that will be used in each Series to determine the sensitivity against.

  • scalars (Sequence of floats, optional (each set as 1.0)) – A sequence of scalars to multiply the sensitivities by for each on of the identifiers.

  • curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.

  • solver (Solver, optional) – A Solver object containing Curve, Smile, Surface, or Cube mappings for pricing.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting FX rates, if necessary.

  • vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.

  • settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.

  • forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

DataFrame

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

Calculate the NPV of the Instrument converted to any other base accounting currency.

Examples

In [42]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2010, 1, 1): 0.75})

In [43]: irs = IRS(dt(2000, 1, 1), "3Y", spec="usd_irs", fixed_rate=1.0, curves=[curve])

In [44]: irs.npv()
Out[44]: 53875.24237805192

In [45]: irs.npv(local=True)
Out[45]: {'usd': 53875.24237805192}
Parameters:

  • curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.

  • solver (Solver, optional) – A Solver object containing Curve, Smile, Surface, or Cube mappings for pricing.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting FX rates, if necessary.

  • vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.

  • base (str, optional (set to settlement currency)) – The currency to convert the local settlement NPV to.

  • local (bool, optional (set as False)) – An override flag to return a dict of NPV values indexed by string currency.

  • settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.

  • forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

float, Dual, Dual2, Variable or dict of such indexed by string currency.

Notes

If base is not given then this function will return the value obtained from determining the PV in local settlement currency.

If base is provided this then an FXForwards object may be required to perform conversions. An FXRates object is also allowed for this conversion although best practice does not recommend it due to possible settlement date conflicts.

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

Return a plot of the payoff at expiry, indexed by the FXFixing value.

Parameters:

  • range (list of float, optional) – A range of values for the FXFixing value at expiry to use as the x-axis.

  • curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.

  • solver (Solver, optional) – A Solver object containing Curve, Smile, Surface, or Cube mappings for pricing.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting FX rates, if necessary.

  • vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.

Return type:

(Figure, Axes, list[Lines2D])

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

Calculate some pricing rate metric for the Instrument.

Examples

The default metric for an IRS is its fixed ‘rate’.

In [1]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2010, 1, 1): 0.75})

In [2]: irs = IRS(dt(2000, 1, 1), "3Y", spec="usd_irs", curves=[curve], fixed_rate=2.0)

In [3]: irs.rate()       # <- `fixed_rate` on fixed leg to equate value with float leg
Out[3]: 2.87622187684324
Parameters:

  • curves (_Curves, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.

  • solver (Solver, optional) – A Solver object containing Curve, Smile, Surface, or Cube mappings for pricing.

  • fx (FXForwards, optional) – The FXForwards object used for forecasting FX rates, if necessary.

  • vol (_Vol, optional) – Pricing objects. See Pricing on each Instrument for details of allowed inputs.

  • base (str, optional (set to settlement currency)) – The currency to convert the local settlement NPV to.

  • local (bool, optional (set as False)) – An override flag to return a dict of NPV values indexed by string currency.

  • settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.

  • forward (datetime, optional) – The future date to project the PV to using the disc_curve.

  • metric (str, optional) – The specific calculation to perform and the value to return. See Pricing on each Instrument for details of allowed inputs.

Return type:

float, Dual, Dual2, Variable

reset_fixings(state=NoInput.blank)#

Resets any fixings values of the Instrument derived using the given data state.

Parameters:

state (int, optional) – The state id of the data series that set the fixing. Only fixings determined by this data will be reset. If not given resets all fixings.

Return type:

None

spread(*, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, vol=NoInput.blank, base=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Not implemented for Option types. Use rate().