_WithSensitivities#

class rateslib.instruments.protocols._WithSensitivities(*args, **kwargs)#

Bases: _WithNPV, Protocol

Protocol to establish delta and gamma calculations using a Solver of any Instrument type.

Methods Summary

`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`.

Methods Documentation

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 [152]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2002, 1, 1): 0.85, dt(2010, 1, 1): 0.75})

In [153]: 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.0031s

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

In [155]: irs.delta(solver=solver)
Out[155]: 
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 [156]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2002, 1, 1): 0.85, dt(2010, 1, 1): 0.75})

In [157]: 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.0032s

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

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

In [160]: irs.analytic_delta()
Out[160]: <Dual: 291.752073, (N, 1d8f50, 1d8f51, ...), [0.0, 49.2, 239.9, ...]>

In [161]: irs.npv()
Out[161]: <Dual: -25123.690181, (N, R, 1d8f50, ...), [-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 [162]: curve = Curve({dt(2000, 1, 1): 1.0, dt(2002, 1, 1): 0.85, dt(2010, 1, 1): 0.75})

In [163]: 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 [164]: irs = IRS(dt(2000, 1, 1), "3Y", spec="usd_irs", curves=[curve])

In [165]: irs.gamma(solver=solver)
Out[165]: 
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.

_WithSensitivities#

This Page