Spread#

class rateslib.instruments.Spread(instrument1, instrument2)#

Bases: Sensitivities

A spread instrument defined as the difference in rate between two Instruments.

Parameters:

instrument1 (Instrument) – The initial instrument, usually the shortest tenor, e.g. 5Y in 5s10s.
instrument2 (Instrument) – The second instrument, usually the longest tenor, e.g. 10Y in 5s10s.

Notes

When using a Spread each Instrument must either have pricing parameters pre-defined using the appropriate pricing mechanisms or share common pricing parameters defined at price time.

Examples

Creating a dynamic Spread where the Instruments are dynamically priced, and each share the pricing arguments.

In [1]: curve1 = Curve({dt(2022, 1, 1): 1.0, dt(2022, 4, 1):0.995, dt(2022, 7, 1):0.985})

In [2]: irs1 = IRS(dt(2022, 1, 1), "3M", "Q")

In [3]: irs2 = IRS(dt(2022, 1, 1), "6M", "Q")

In [4]: spread = Spread(irs1, irs2)

In [5]: spread.npv(curve1)
Out[5]: -9.094947017729282e-13

In [6]: spread.rate(curve1)
Out[6]: 100.35948641272844

In [7]: spread.cashflows(curve1)
Out[7]: 
                           Type   Period  Ccy  Acc Start    Acc End    Payment Convention       DCF   Notional        DF Collateral      Rate  Spread      Cashflow          NPV  FX Rate      NPV Ccy
instrument1 leg1 0  FixedPeriod  Regular  USD 2022-01-01 2022-04-01 2022-04-03     Act360  0.250000  1000000.0  0.994779       None  2.010050     NaN  -5025.125628 -4998.890113      1.0 -4998.890113
            leg2 0  FloatPeriod  Regular  USD 2022-01-01 2022-04-01 2022-04-03     Act360  0.250000 -1000000.0  0.994779       None  2.010050     0.0   5025.125628  4998.890113      1.0  4998.890113
instrument2 leg1 0  FixedPeriod  Regular  USD 2022-01-01 2022-04-01 2022-04-03     Act360  0.250000  1000000.0  0.994779       None  3.013645     NaN  -7534.112788 -7494.778183      1.0 -7494.778183
                 1  FixedPeriod  Regular  USD 2022-04-01 2022-07-01 2022-07-03     Act360  0.252778  1000000.0  0.984781       None  3.013645     NaN  -7617.825153 -7501.892155      1.0 -7501.892155
            leg2 0  FloatPeriod  Regular  USD 2022-01-01 2022-04-01 2022-04-03     Act360  0.250000 -1000000.0  0.994779       None  2.010050     0.0   5025.125628  4998.890113      1.0  4998.890113
                 1  FloatPeriod  Regular  USD 2022-04-01 2022-07-01 2022-07-03     Act360  0.252778 -1000000.0  0.984781       None  4.016288     0.0  10152.284264  9997.780225      1.0  9997.780225

Creating an assigned Spread, where each Instrument has its own assigned pricing arguments.

In [8]: curve1 = Curve({dt(2022, 1, 1): 1.0, dt(2022, 4, 1):0.995, dt(2022, 7, 1):0.985})

In [9]: curve2 = Curve({dt(2022, 1, 1): 1.0, dt(2022, 4, 1):0.99, dt(2022, 7, 1):0.98})

In [10]: irs1 = IRS(dt(2022, 1, 1), "3M", "Q", curves=curve1)

In [11]: irs2 = IRS(dt(2022, 1, 1), "6M", "Q", curves=curve2)

In [12]: spread = Spread(irs1, irs2)

In [13]: spread.npv()
Out[13]: -4.547473508864641e-12

In [14]: spread.rate()
Out[14]: 202.8540729223891

In [15]: spread.cashflows()
Out[15]: 
                           Type   Period  Ccy  Acc Start    Acc End    Payment Convention       DCF   Notional        DF Collateral      Rate  Spread      Cashflow           NPV  FX Rate       NPV Ccy
instrument1 leg1 0  FixedPeriod  Regular  USD 2022-01-01 2022-04-01 2022-04-03     Act360  0.250000  1000000.0  0.994779       None  2.010050     NaN  -5025.125628  -4998.890113      1.0  -4998.890113
            leg2 0  FloatPeriod  Regular  USD 2022-01-01 2022-04-01 2022-04-03     Act360  0.250000 -1000000.0  0.994779       None  2.010050     0.0   5025.125628   4998.890113      1.0   4998.890113
instrument2 leg1 0  FixedPeriod  Regular  USD 2022-01-01 2022-04-01 2022-04-03     Act360  0.250000  1000000.0  0.989779       None  4.038591     NaN -10096.477451  -9993.282636      1.0  -9993.282636
                 1  FixedPeriod  Regular  USD 2022-04-01 2022-07-01 2022-07-03     Act360  0.252778  1000000.0  0.979781       None  4.038591     NaN -10208.660534 -10002.255281      1.0 -10002.255281
            leg2 0  FloatPeriod  Regular  USD 2022-01-01 2022-04-01 2022-04-03     Act360  0.250000 -1000000.0  0.989779       None  4.040404     0.0  10101.010101   9997.768958      1.0   9997.768958
                 1  FloatPeriod  Regular  USD 2022-04-01 2022-07-01 2022-07-03     Act360  0.252778 -1000000.0  0.979781       None  4.036780     0.0  10204.081633   9997.768958      1.0   9997.768958

Methods Summary

`cashflows`(args, *kwargs)
`delta`(args, *kwargs)	Calculate the delta of the Instrument.
`exo_delta`(vars[, curves, solver, fx, base, ...])	Calculate delta risk of an Instrument against some exogenous user created Variables.
`fixings_table`([curves, solver, fx, base, ...])	Return a DataFrame of fixing exposures on the Instruments.
`gamma`(args, *kwargs)	Calculate the gamma of the Instrument.
`npv`(args, *kwargs)	Return the NPV of the composited object by summing instrument NPVs.
`rate`(args, *kwargs)	Return the mid-market rate of the composited via the difference of instrument rates.

Methods Documentation

cashflows(*args, **kwargs)#

delta(*args, **kwargs)#

Calculate the delta of the Instrument.

For arguments see Sensitivities.delta().

exo_delta(vars, curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank, local=False, vars_scalar=NoInput.blank, vars_labels=NoInput.blank, **kwargs)#

Calculate delta risk of an Instrument against some exogenous user created Variables.

See What are exogenous variables? in the cookbook.

Parameters:

vars (list[str]) – The variable tags which to determine sensitivities for.
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.
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

fixings_table(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank, approximate=False, right=NoInput.blank)#

Return a DataFrame of fixing exposures on the Instruments.

For arguments see XCS.fixings_table(), and/or IRS.fixings_table()

Return type:: DataFrame

gamma(*args, **kwargs)#

Calculate the gamma of the Instrument.

For arguments see Sensitivities.gamma().

npv(*args, **kwargs)#

Return the NPV of the composited object by summing instrument NPVs.

Parameters:

args – Positional arguments required for the npv method of both of the underlying Instruments.
kwargs – Keyword arguments required for the npv method of both of the underlying Instruments.

Return type:

float, Dual or Dual2

Notes

If the argument local is added to return a dict of currencies, ensure that this is added as a keyword argument and not a positional argument. I.e. use local=True.

rate(*args, **kwargs)#

Return the mid-market rate of the composited via the difference of instrument rates.

Parameters:

args – Positional arguments required for the rate method of both of the underlying Instruments.
kwargs – Keyword arguments required for the rate method of both of the underlying Instruments.

Return type:

float, Dual or Dual2

Spread#

This Page