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.25  1000000.00 0.99       None  2.01     NaN  -5025.13 -4998.89     1.00 -4998.89
            leg2 0  FloatPeriod  Regular  USD 2022-01-01 2022-04-01 2022-04-03     ACT360 0.25 -1000000.00 0.99       None  2.01    0.00   5025.13  4998.89     1.00  4998.89
instrument2 leg1 0  FixedPeriod  Regular  USD 2022-01-01 2022-04-01 2022-04-03     ACT360 0.25  1000000.00 0.99       None  3.01     NaN  -7534.11 -7494.78     1.00 -7494.78
                 1  FixedPeriod  Regular  USD 2022-04-01 2022-07-01 2022-07-03     ACT360 0.25  1000000.00 0.98       None  3.01     NaN  -7617.83 -7501.89     1.00 -7501.89
            leg2 0  FloatPeriod  Regular  USD 2022-01-01 2022-04-01 2022-04-03     ACT360 0.25 -1000000.00 0.99       None  2.01    0.00   5025.13  4998.89     1.00  4998.89
                 1  FloatPeriod  Regular  USD 2022-04-01 2022-07-01 2022-07-03     ACT360 0.25 -1000000.00 0.98       None  4.02    0.00  10152.28  9997.78     1.00  9997.78

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.25  1000000.00 0.99       None  2.01     NaN  -5025.13  -4998.89     1.00  -4998.89
            leg2 0  FloatPeriod  Regular  USD 2022-01-01 2022-04-01 2022-04-03     ACT360 0.25 -1000000.00 0.99       None  2.01    0.00   5025.13   4998.89     1.00   4998.89
instrument2 leg1 0  FixedPeriod  Regular  USD 2022-01-01 2022-04-01 2022-04-03     ACT360 0.25  1000000.00 0.99       None  4.04     NaN -10096.48  -9993.28     1.00  -9993.28
                 1  FixedPeriod  Regular  USD 2022-04-01 2022-07-01 2022-07-03     ACT360 0.25  1000000.00 0.98       None  4.04     NaN -10208.66 -10002.26     1.00 -10002.26
            leg2 0  FloatPeriod  Regular  USD 2022-01-01 2022-04-01 2022-04-03     ACT360 0.25 -1000000.00 0.99       None  4.04    0.00  10101.01   9997.77     1.00   9997.77
                 1  FloatPeriod  Regular  USD 2022-04-01 2022-07-01 2022-07-03     ACT360 0.25 -1000000.00 0.98       None  4.04    0.00  10204.08   9997.77     1.00   9997.77

Methods Summary

`cashflows`(args, *kwargs)
`cashflows_table`([curves, solver, fx, base])
`delta`(args, *kwargs)	Calculate the delta of the Instrument.
`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)#

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

delta(*args, **kwargs)#

Calculate the delta of the Instrument.

For arguments see Sensitivities.delta().

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