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 aFloatLeg
.- 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 thecurve
.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 = IndexCurve( ...: 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()
, andnpv()
.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.054047718921930166 In [5]: iirs.npv(curves=[us_cpi, usd, usd, usd]) Out[5]: -8435241.191493511
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 1+ 1.00 100000000.00 0.97 None 2.05 NaN -2050000.00 100.00 103.53 1.04 -2122313.32 -2053744.44 1.00 -2053744.44 1 IndexFixedPeriod Regular USD 2023-01-03 2024-01-02 2024-01-04 1+ 1.00 100000000.00 0.94 None 2.05 NaN -2050000.00 100.00 107.05 1.07 -2194626.63 -2056021.81 1.00 -2056021.81 2 IndexFixedPeriod Regular USD 2024-01-02 2025-01-02 2025-01-06 1+ 1.00 100000000.00 0.91 None 2.05 NaN -2050000.00 100.00 110.59 1.11 -2267138.07 -2055514.75 1.00 -2055514.75 3 IndexFixedPeriod Regular USD 2025-01-02 2026-01-02 2026-01-06 1+ 1.00 100000000.00 0.88 None 2.05 NaN -2050000.00 100.00 114.12 1.14 -2339451.39 -2053279.96 1.00 -2053279.96 4 IndexCashflow Exchange USD NaT 2026-01-02 2026-01-02 None NaN 100000000.00 0.88 None NaN NaN -100000000.00 100.00 114.12 1.14 -114119579.92 -100195662.42 1.00 -100195662.42 leg2 0 FloatPeriod Regular USD 2022-01-03 2023-01-03 2023-01-05 Act360 1.01 -100000000.00 0.97 None 3.26 0.00 NaN NaN NaN NaN 3301941.56 3195260.61 1.00 3195260.61 1 FloatPeriod Regular USD 2023-01-03 2024-01-02 2024-01-04 Act360 1.01 -100000000.00 0.94 None 3.26 0.00 NaN NaN NaN NaN 3292747.82 3084789.56 1.00 3084789.56 2 FloatPeriod Regular USD 2024-01-02 2025-01-02 2025-01-06 Act360 1.02 -100000000.00 0.91 None 3.26 0.00 NaN NaN NaN NaN 3311136.13 3002062.04 1.00 3002062.04 3 FloatPeriod Regular USD 2025-01-02 2026-01-02 2026-01-06 Act360 1.01 -100000000.00 0.88 None 3.26 0.00 NaN NaN NaN NaN 3301941.56 2898034.33 1.00 2898034.33 4 Cashflow Exchange USD NaT NaT 2026-01-02 None NaN -100000000.00 0.88 None NaN NaN NaN NaN NaN NaN 100000000.00 87798835.65 1.00 87798835.65
For accurate sensitivity calculations;
delta()
andgamma()
, 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.5046314313449345e-17, `time`: 0.0164s In [11]: iirs.delta(solver=solver) Out[11]: local_ccy usd display_ccy usd type solver label instruments us 5Y 39435.73 10Y -133.20 5Yi -40125.24 10Yi 0.00 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 -19.35 0.12 15.60 -0.00 10Y 0.12 -0.06 -0.05 0.00 5Yi 15.60 -0.05 -15.70 0.00 10Yi -0.00 0.00 0.00 -0.00
Attributes Summary
If set will also set the
fixed_rate
of the contained leg1.If set will also set the
float_spread
of contained leg1.If set will also set the
index_base
of the contained leg1.If set will also set the
fixed_rate
of the contained leg2.If set will also set the
float_spread
of contained leg2.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])delta
(*args, **kwargs)Calculate the delta of the Instrument.
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
andleg2_float_spread
are attributes only applicable to certainInstruments
. 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
andleg2_index_base
are attributes only applicable to certainInstruments
. 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
andleg2_index_base
are attributes only applicable to certainInstruments
. 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:
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 constructsCurves
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
orFXForwards
object, converts from local currency intobase
.base (str, optional) – The base currency to convert cashflows into (3-digit code). Only used if
fx
is anFXRates
orFXForwards
object. If not given defaults tofx.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.25 1000000000.00 0.94 None 5.00 NaN -12500000.00 -11792277.34 1.25 -14740346.67 1 FixedPeriod Regular GBP 2022-04-01 2022-07-01 2022-07-03 ACT360 0.25 1000000000.00 0.93 None 5.00 NaN -12638888.89 -11785723.74 1.25 -14732154.68 leg2 0 FloatPeriod Regular GBP 2022-01-01 2022-04-01 2022-04-03 ACT360 0.25 -1000000000.00 0.94 None 4.62 0.00 11544335.50 10890720.47 1.25 13613400.59 1 FloatPeriod Regular GBP 2022-04-01 2022-07-01 2022-07-03 ACT360 0.25 -1000000000.00 0.93 None 4.62 0.00 11673351.69 10885363.37 1.25 13606704.21
- 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(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 constructsCurves
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
orFXForwards
object, converts from local currency intobase
.base (str, optional) – The base currency to convert cashflows into (3-digit code). Only used if
fx
is anFXRates
orFXForwards
object. If not given defaults tofx.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:
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.2427669652 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.2427669652
- 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:solver (Solver, optional) –
The numerical
Solver
that constructsCurve
from calibrating instruments.Note
The arguments
fx
andbase
are unused by single currency derivatives rates calculations.
- Return type:
Notes
The arguments
fx
andbase
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:solver (Solver, optional) –
The numerical
Solver
that constructsCurve
from calibrating instruments.Note
The arguments
fx
andbase
are unused by single currency derivatives rates calculations.
- Return type:
Notes
If the
IRS
is specified without afixed_rate
this should always return the currentleg2_float_spread
value or zero since the fixed rate used for calculation is the implied rate including the currentleg2_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 toirs.spread
is different to the previous call, albeit the difference is 1/10000th of a basis point.