IIRS#

class rateslib.instruments.IIRS(*args, fixed_rate=NoInput.blank, index_base=NoInput.blank, index_fixings=NoInput.blank, index_method=NoInput.blank, index_lag=NoInput.blank, notional_exchange=False, payment_lag_exchange=NoInput.blank, leg2_float_spread=NoInput.blank, leg2_fixings=NoInput.blank, leg2_fixing_method=NoInput.blank, leg2_method_param=NoInput.blank, leg2_spread_compound_method=NoInput.blank, leg2_payment_lag_exchange=NoInput.inherit, **kwargs)#

Bases: BaseDerivative

Create an indexed interest rate swap (IIRS) composing an IndexFixedLeg and a FloatLeg.

For more information see the Cookbook Article: “Using Curves with an Index and Inflation Instruments”.

Parameters:

  • args (dict) – Required positional args to BaseDerivative.

  • fixed_rate (float or None) – The fixed rate applied to the ZeroFixedLeg. If None will be set to mid-market when curves are provided.

  • index_base (float or None, optional) – The base index applied to all periods.

  • index_fixings (float, or Series, optional) – If a float scalar, will be applied as the index fixing for the first period. If a list of n fixings will be used as the index fixings for the first n periods. If a datetime indexed Series will use the fixings that are available in that object, and derive the rest from the curve.

  • index_method (str) – Whether the indexing uses a daily measure for settlement or the most recently monthly data taken from the first day of month.

  • index_lag (int, optional) – The number of months by which the index value is lagged. Used to ensure consistency between curves and forecast values. Defined by default.

  • notional_exchange (bool, optional) – Whether the legs include final notional exchanges and interim amortization notional exchanges.

  • kwargs (dict) – Required keyword arguments to BaseDerivative.

Examples

Construct a curve to price the example.

In [1]: usd = Curve(
   ...:     nodes={
   ...:         dt(2022, 1, 1): 1.0,
   ...:         dt(2027, 1, 1): 0.85,
   ...:         dt(2032, 1, 1): 0.65,
   ...:     },
   ...:     id="usd",
   ...: )
   ...: 

In [2]: us_cpi = Curve(
   ...:     nodes={
   ...:         dt(2022, 1, 1): 1.0,
   ...:         dt(2027, 1, 1): 0.85,
   ...:         dt(2032, 1, 1): 0.70,
   ...:     },
   ...:     id="us_cpi",
   ...:     index_base=100,
   ...:     index_lag=3,
   ...: )
   ...:

Create the IIRS, and demonstrate the rate(), and npv().

In [3]: iirs = IIRS(
   ...:     effective=dt(2022, 1, 1),
   ...:     termination="4Y",
   ...:     frequency="A",
   ...:     calendar="nyc",
   ...:     currency="usd",
   ...:     fixed_rate=2.05,
   ...:     convention="1+",
   ...:     notional=100e6,
   ...:     index_base=100.0,
   ...:     index_method="monthly",
   ...:     index_lag=3,
   ...:     notional_exchange=True,
   ...:     leg2_convention="Act360",
   ...:     curves=["us_cpi", "usd", "usd", "usd"],
   ...: )
   ...: 

In [4]: iirs.rate(curves=[us_cpi, usd, usd, usd])
Out[4]: -0.0030306301766618304

In [5]: iirs.npv(curves=[us_cpi, usd, usd, usd])
Out[5]: -8209016.800924331

A DataFrame of cashflows().

In [6]: iirs.cashflows(curves=[us_cpi, usd, usd, usd])
Out[6]: 
                    Type    Period  Ccy  Acc Start    Acc End    Payment   Convention       DCF     Notional        DF Collateral      Rate  Spread  Real Cashflow  Index Base   Index Val  Index Ratio      Cashflow           NPV  FX Rate       NPV Ccy
leg1 0  IndexFixedPeriod   Regular  USD 2022-01-03 2023-01-03 2023-01-05  YearsMonths  1.000000  100000000.0  0.967691       None  2.050000     NaN     -2050000.0       100.0  103.301942     1.033019 -2.117690e+06 -2.049270e+06      1.0 -2.049270e+06
     1  IndexFixedPeriod   Regular  USD 2023-01-03 2024-01-02 2024-01-04  YearsMonths  1.000000  100000000.0  0.936844       None  2.050000     NaN     -2050000.0       100.0  106.712911     1.067129 -2.187615e+06 -2.049453e+06      1.0 -2.049453e+06
     2  IndexFixedPeriod   Regular  USD 2024-01-02 2025-01-02 2025-01-06  YearsMonths  1.000000  100000000.0  0.906656       None  2.050000     NaN     -2050000.0       100.0  110.246321     1.102463 -2.260050e+06 -2.049088e+06      1.0 -2.049088e+06
     3  IndexFixedPeriod   Regular  USD 2025-01-02 2026-01-02 2026-01-06  YearsMonths  1.000000  100000000.0  0.877676       None  2.050000     NaN     -2050000.0       100.0  113.886590     1.138866 -2.334675e+06 -2.049088e+06      1.0 -2.049088e+06
     4     IndexCashflow  Exchange  USD        NaT 2026-01-02 2026-01-02          NaN       NaN  100000000.0  0.877988       None       NaN     NaN   -100000000.0       100.0  113.886590     1.138866 -1.138866e+08 -9.999110e+07      1.0 -9.999110e+07
leg2 0       FloatPeriod   Regular  USD 2022-01-03 2023-01-03 2023-01-05       Act360  1.013889 -100000000.0  0.967691       None  3.256709     0.0            NaN         NaN         NaN          NaN  3.301942e+06  3.195261e+06      1.0  3.195261e+06
     1       FloatPeriod   Regular  USD 2023-01-03 2024-01-02 2024-01-04       Act360  1.011111 -100000000.0  0.936844       None  3.256564     0.0            NaN         NaN         NaN          NaN  3.292748e+06  3.084790e+06      1.0  3.084790e+06
     2       FloatPeriod   Regular  USD 2024-01-02 2025-01-02 2025-01-06       Act360  1.016667 -100000000.0  0.906656       None  3.256855     0.0            NaN         NaN         NaN          NaN  3.311136e+06  3.002062e+06      1.0  3.002062e+06
     3       FloatPeriod   Regular  USD 2025-01-02 2026-01-02 2026-01-06       Act360  1.013889 -100000000.0  0.877676       None  3.256709     0.0            NaN         NaN         NaN          NaN  3.301942e+06  2.898034e+06      1.0  2.898034e+06
     4          Cashflow  Exchange  USD        NaT        NaT 2026-01-02          NaN       NaN -100000000.0  0.877988       None       NaN     NaN            NaN         NaN         NaN          NaN  1.000000e+08  8.779884e+07      1.0  8.779884e+07

For accurate sensitivity calculations; delta() and gamma(), construct a curve model.

In [7]: sofr_kws = dict(
   ...:     effective=dt(2022, 1, 1),
   ...:     frequency="A",
   ...:     convention="Act360",
   ...:     calendar="nyc",
   ...:     currency="usd",
   ...:     curves=["usd"]
   ...: )
   ...: 

In [8]: cpi_kws = dict(
   ...:     effective=dt(2022, 1, 1),
   ...:     frequency="A",
   ...:     convention="1+",
   ...:     calendar="nyc",
   ...:     leg2_index_method="monthly",
   ...:     currency="usd",
   ...:     curves=["usd", "usd", "us_cpi", "usd"]
   ...: )
   ...: 

In [9]: instruments = [
   ...:     IRS(termination="5Y", **sofr_kws),
   ...:     IRS(termination="10Y", **sofr_kws),
   ...:     ZCIS(termination="5Y", **cpi_kws),
   ...:     ZCIS(termination="10Y", **cpi_kws),
   ...: ]
   ...: 

In [10]: solver = Solver(
   ....:     curves=[usd, us_cpi],
   ....:     instruments=instruments,
   ....:     s=[3.40, 3.60, 2.2, 2.05],
   ....:     instrument_labels=["5Y", "10Y", "5Yi", "10Yi"],
   ....:     id="us",
   ....: )
   ....: 
SUCCESS: `func_tol` reached after 6 iterations (levenberg_marquardt), `f_val`: 3.5046302421456396e-17, `time`: 0.0280s

In [11]: iirs.delta(solver=solver)
Out[11]: 
local_ccy                          usd
display_ccy                        usd
type        solver label              
instruments us     5Y     3.939866e+04
                   10Y   -1.330715e+02
                   5Yi   -3.921842e+04
                   10Yi  -1.094967e-14

In [12]: iirs.gamma(solver=solver)
Out[12]: 
type                                             instruments                                          
solver                                                    us                                          
label                                                     5Y           10Y           5Yi          10Yi
local_ccy display_ccy type        solver label                                                        
usd       usd         instruments us     5Y    -1.932786e+01  1.194852e-01  1.525726e+01  1.638187e-16
                                         10Y    1.194852e-01 -6.353520e-02 -5.153234e-02 -5.533078e-19
                                         5Yi    1.525726e+01 -5.153234e-02 -1.132286e+01 -1.215746e-16
                                         10Yi   1.638187e-16 -5.533078e-19 -1.215746e-16  4.538964e-16

Attributes Summary

fixed_rate

If set will also set the fixed_rate of the contained leg1.

float_spread

If set will also set the float_spread of contained leg1.

index_base

If set will also set the index_base of the contained leg1.

leg2_fixed_rate

If set will also set the fixed_rate of the contained leg2.

leg2_float_spread

If set will also set the float_spread of contained leg2.

leg2_index_base

If set will also set the index_base of the contained leg1.

Methods Summary

analytic_delta(*args[, leg])

Return the analytic delta of a leg of the derivative object.

cashflows([curves, solver, fx, base])

Return the properties of all legs used in calculating cashflows.

cashflows_table([curves, solver, fx, base])

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

delta(*args, **kwargs)

Calculate the delta of the Instrument.

exo_delta(*args, **kwargs)

Calculate the delta of the Instrument, measured against user defined Variable s.

fixings_table([curves, solver, fx, base, ...])

Return a DataFrame of fixing exposures on the FloatLeg.

gamma(*args, **kwargs)

Calculate the gamma of the Instrument.

npv([curves, solver, fx, base, local])

Return the NPV of the derivative object by summing legs.

rate([curves, solver, fx, base])

Return the mid-market rate of the IRS.

spread([curves, solver, fx, base])

Return the mid-market float spread (bps) required to equate to the fixed rate.

Attributes Documentation

fixed_rate#

If set will also set the fixed_rate of the contained leg1.

Note

fixed_rate, float_spread, leg2_fixed_rate and leg2_float_spread are attributes only applicable to certain Instruments. AttributeErrors are raised if calling or setting these is invalid.

Type:

float or None

float_spread#

If set will also set the float_spread of contained leg1.

Type:

float or None

index_base#

If set will also set the index_base of the contained leg1.

Note

index_base and leg2_index_base are attributes only applicable to certain Instruments. AttributeErrors are raised if calling or setting these is invalid.

Type:

float or None

leg2_fixed_rate#

If set will also set the fixed_rate of the contained leg2.

Type:

float or None

leg2_float_spread#

If set will also set the float_spread of contained leg2.

Type:

float or None

leg2_index_base#

If set will also set the index_base of the contained leg1.

Note

index_base and leg2_index_base are attributes only applicable to certain Instruments. AttributeErrors are raised if calling or setting these is invalid.

Type:

float or None

Methods Documentation

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

Return the analytic delta of a leg of the derivative object.

Parameters:

  • args – Required positional arguments supplied to BaseLeg.analytic_delta.

  • leg (int in [1, 2]) – The leg identifier of which to take the analytic delta.

  • kwargs – Required Keyword arguments supplied to BaseLeg.analytic_delta().

Return type:

float, Dual, Dual2

Examples

In [13]: curve = Curve({dt(2021,1,1): 1.00, dt(2025,1,1): 0.83}, id="SONIA")

In [14]: fxr = FXRates({"gbpusd": 1.25}, base="usd")

In [15]: irs = IRS(
   ....:     effective=dt(2022, 1, 1),
   ....:     termination="6M",
   ....:     frequency="Q",
   ....:     currency="gbp",
   ....:     notional=1e9,
   ....:     fixed_rate=5.0,
   ....: )
   ....: 

In [16]: irs.analytic_delta(curve, curve)
Out[16]: 47156.00216054951

In [17]: irs.analytic_delta(curve, curve, fxr)
Out[17]: <Dual: 58945.002701, (fx_gbpusd), [47156.0]>

In [18]: irs.analytic_delta(curve, curve, fxr, "gbp")
Out[18]: 47156.00216054951
cashflows(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank)#

Return the properties of all legs used in calculating cashflows.

Parameters:

  • curves (CurveType, str or list of such, optional) –

    A single Curve, LineCurve or id or a list of such. A list defines the following curves in the order:

  • solver (Solver, optional) – The numerical Solver that constructs Curves from calibrating 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). Only used if fx is an FXRates or FXForwards object. If not given defaults to fx.base.

Return type:

DataFrame

Notes

If only one curve is given this is used as all four curves.

If two curves are given the forecasting curve is used as the forecasting curve on both legs and the discounting curve is used as the discounting curve for both legs.

If three curves are given the single discounting curve is used as the discounting curve for both legs.

Examples

In [1]: irs.cashflows([curve], fx=fxr)
Out[1]: 
               Type   Period  Ccy  Acc Start    Acc End    Payment Convention       DCF      Notional        DF Collateral      Rate  Spread      Cashflow           NPV  FX Rate       NPV Ccy
leg1 0  FixedPeriod  Regular  GBP 2022-01-01 2022-04-01 2022-04-03     Act360  0.250000  1.000000e+09  0.943382       None  5.000000     NaN -1.250000e+07 -1.179228e+07     1.25 -1.474035e+07
     1  FixedPeriod  Regular  GBP 2022-04-01 2022-07-01 2022-07-03     Act360  0.252778  1.000000e+09  0.932497       None  5.000000     NaN -1.263889e+07 -1.178572e+07     1.25 -1.473215e+07
leg2 0  FloatPeriod  Regular  GBP 2022-01-01 2022-04-01 2022-04-03     Act360  0.250000 -1.000000e+09  0.943382       None  4.617734     0.0  1.154434e+07  1.089072e+07     1.25  1.361340e+07
     1  FloatPeriod  Regular  GBP 2022-04-01 2022-07-01 2022-07-03     Act360  0.252778 -1.000000e+09  0.932497       None  4.618029     0.0  1.167335e+07  1.088536e+07     1.25  1.360670e+07
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(*args, **kwargs)#

Calculate the delta of the Instrument.

For arguments see Sensitivities.delta().

exo_delta(*args, **kwargs)#

Calculate the delta of the Instrument, measured against user defined Variable s.

For arguments see Sensitivities.exo_delta().

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

Parameters:

  • curves (Curve, str or list of such) –

    A single Curve or id or a list of such. A list defines the following curves in the order:

    • Forecasting Curve for floating leg.

    • Discounting Curve for both legs.

  • solver (Solver, optional) –

    The numerical Solver that constructs Curve from calibrating instruments.

    Note

    The arguments fx and base are unused by single currency derivatives rates calculations.

  • approximate (bool, optional) – Perform a calculation that is broadly 10x faster but potentially loses precision upto 0.1%.

Return type:

DataFrame

gamma(*args, **kwargs)#

Calculate the gamma of the Instrument.

For arguments see Sensitivities.gamma().

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

Return the NPV of the derivative object by summing legs.

Parameters:

  • curves (Curve, LineCurve, str or list of such) –

    A single Curve, LineCurve or id or a list of such. A list defines the following curves in the order:

  • solver (Solver, optional) – The numerical Solver that constructs Curves from calibrating 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). Only used if fx is an FXRates or FXForwards object. If not given defaults to fx.base.

  • local (bool, optional) – If True will return a dict identifying NPV by local currencies on each leg. Useful for multi-currency derivatives and for ensuring risk sensitivities are allocated to local currencies without conversion.

Return type:

float, Dual or Dual2, or dict of such.

Notes

If only one curve is given this is used as all four curves.

If two curves are given the forecasting curve is used as the forecasting curve on both legs and the discounting curve is used as the discounting curve for both legs.

If three curves are given the single discounting curve is used as the discounting curve for both legs.

Examples

In [1]: irs.npv(curve)
Out[1]: -1801917.2427671738

In [2]: irs.npv([curve], fx=fxr)
Out[2]: <Dual: -2252396.553459, (fx_gbpusd), [-1801917.2]>

In [3]: irs.npv([curve], fx=fxr, base="gbp")
Out[3]: -1801917.2427671738
rate(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank)#

Return the mid-market rate of the IRS.

Parameters:

  • curves (Curve, str or list of such) –

    A single Curve or id or a list of such. A list defines the following curves in the order:

    • Forecasting Curve for floating leg.

    • Discounting Curve for both legs.

  • solver (Solver, optional) –

    The numerical Solver that constructs Curve from calibrating instruments.

    Note

    The arguments fx and base are unused by single currency derivatives rates calculations.

Return type:

float, Dual or Dual2

Notes

The arguments fx and base are unused by single currency derivatives rates calculations.

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

Return the mid-market float spread (bps) required to equate to the fixed rate.

Parameters:

  • curves (Curve, str or list of such) –

    A single Curve or id or a list of such. A list defines the following curves in the order:

    • Forecasting Curve for floating leg.

    • Discounting Curve for both legs.

  • solver (Solver, optional) –

    The numerical Solver that constructs Curve from calibrating instruments.

    Note

    The arguments fx and base are unused by single currency derivatives rates calculations.

Return type:

float, Dual or Dual2

Notes

If the IRS is specified without a fixed_rate this should always return the current leg2_float_spread value or zero since the fixed rate used for calculation is the implied rate including the current leg2_float_spread parameter.

Examples

For the most common parameters this method will be exact.

In [1]: irs.spread(curves=usd)
Out[1]: <Dual: 164.392050, (usd0, usd1, usd2), [-1988.2, 2355.4, -0.0]>

In [2]: irs.leg2_float_spread = -6.948753

In [3]: irs.npv(curves=usd)
Out[3]: <Dual: -8505248.782773, (usd0, usd1, usd2), [90826272.4, -117680895.1, 0.0]>

When a non-linear spread compound method is used for float RFR legs this is an approximation, via second order Taylor expansion.

In [4]: irs = IRS(
   ...:     effective=dt(2022, 2, 15),
   ...:     termination=dt(2022, 8, 15),
   ...:     frequency="Q",
   ...:     convention="30e360",
   ...:     leg2_convention="Act360",
   ...:     leg2_fixing_method="rfr_payment_delay",
   ...:     leg2_spread_compound_method="isda_compounding",
   ...:     payment_lag=2,
   ...:     fixed_rate=2.50,
   ...:     leg2_float_spread=0,
   ...:     notional=50000000,
   ...:     currency="usd",
   ...: )
   ...: 

In [5]: irs.spread(curves=usd)
Out[5]: <Dual: -86.344764, (usd0, usd1, usd2), [-1971.6, 2335.8, 0.0]>

In [6]: irs.leg2_float_spread = -111.060143

In [7]: irs.npv(curves=usd)
Out[7]: <Dual: -61445.960013, (usd0, usd1, usd2), [4844862.3, -5812643.8, 0.0]>

In [8]: irs.spread(curves=usd)
Out[8]: <Dual: -86.344696, (usd0, usd1, usd2), [-1971.6, 2335.8, 0.0]>

The leg2_float_spread is determined through NPV differences. If the difference is small since the defined spread is already quite close to the solution the approximation is much more accurate. This is shown above where the second call to irs.spread is different to the previous call, albeit the difference is 1/10000th of a basis point.