IndexCurve#

class rateslib.curves.IndexCurve(*args, index_base=NoInput.blank, index_lag=NoInput.blank, **kwargs)#

Bases: Curve

A subclass of Curve with an index_base value for index calculations.

Parameters:

  • args (tuple) – Position arguments required by Curve.

  • index_base (float)

  • index_lag (int) – Number of months of by which the index lags the date. For example if the initial curve node date is 1st Sep 2021 based on the inflation index published 17th June 2023 then the lag is 3 months.

  • kwargs (dict) – Keyword arguments required by Curve.

Attributes Summary

collateral

Methods Summary

copy()

Create an identical copy of the curve object.

csolve()

Solves and sets the coefficients, c, of the PPSpline.

from_json(curve, **kwargs)

Reconstitute a curve from JSON.

index_value(date[, interpolation])

Calculate the accrued value of the index from the index_base.

plot(tenor[, right, left, comparators, ...])

Plot given forward tenor rates from the curve.

plot_index([right, left, comparators, ...])

Plot given forward tenor rates from the curve.

rate(effective, termination[, modifier, ...])

Calculate the rate on the Curve using DFs.

roll(tenor)

Create a new curve with its shape translated in time but an identical initial node date.

shift(spread[, id, composite, collateral])

Create a new curve by vertically adjusting the curve by a set number of basis points.

to_json()

Convert the parameters of the curve to JSON format.

translate(start[, t])

Create a new curve with an initial node date moved forward keeping all else constant.

Attributes Documentation

collateral = None#

Methods Documentation

copy()#

Create an identical copy of the curve object.

Return type:

Curve or LineCurve

csolve()#

Solves and sets the coefficients, c, of the PPSpline.

Return type:

None

Notes

Only impacts curves which have a knot sequence, t, and a PPSpline. Only solves if c not given at curve initialisation.

Uses the spline_endpoints attribute on the class to determine the solving method.

classmethod from_json(curve, **kwargs)#

Reconstitute a curve from JSON.

Parameters:

curve (str) – The JSON string representation of the curve.

Return type:

Curve or LineCurve

index_value(date, interpolation='daily')#

Calculate the accrued value of the index from the index_base.

Parameters:

  • date (datetime) – The date for which the index value will be returned.

  • interpolation (str in {"monthly", "daily"}) – The method for returning the index value. Monthly returns the index value for the start of the month and daily returns a value based on the interpolation between nodes (which is recommended “linear_index) for InflationCurve.

Return type:

None, float, Dual, Dual2

Examples

The SWESTR rate, for reference value date 6th Sep 2021, was published as 2.375% and the RFR index for that date was 100.73350964. Below we calculate the value that was published for the RFR index on 7th Sep 2021 by the Riksbank.

In [1]: index_curve = IndexCurve(
   ...:     nodes={
   ...:         dt(2021, 9, 6): 1.0,
   ...:         dt(2021, 9, 7): 1 / (1 + 2.375/36000)
   ...:     },
   ...:     index_base=100.73350964,
   ...:     convention="Act360",
   ...: )
   ...: 

In [2]: index_curve.rate(dt(2021, 9, 6), "1d")
Out[2]: 2.3750000000015703

In [3]: index_curve.index_value(dt(2021, 9, 7))
Out[3]: 100.7401552534832
plot(tenor, right=NoInput.blank, left=NoInput.blank, comparators=[], difference=False, labels=[])#

Plot given forward tenor rates from the curve.

Parameters:

  • tenor (str) – The tenor of the forward rates to plot, e.g. “1D”, “3M”.

  • right (datetime or str, optional) – The right bound of the graph. If given as str should be a tenor format defining a point measured from the initial node date of the curve. Defaults to the final node of the curve minus the tenor.

  • left (datetime or str, optional) – The left bound of the graph. If given as str should be a tenor format defining a point measured from the initial node date of the curve. Defaults to the initial node of the curve.

  • comparators (list[Curve]) – A list of curves which to include on the same plot as comparators.

  • difference (bool) – Whether to plot as comparator minus base curve or outright curve levels in plot. Default is False.

  • labels (list[str]) – A list of strings associated with the plot and comparators. Must be same length as number of plots.

Returns:

(fig, ax, line)

Return type:

Matplotlib.Figure, Matplotplib.Axes, Matplotlib.Lines2D

plot_index(right=NoInput.blank, left=NoInput.blank, comparators=[], difference=False, labels=[])#

Plot given forward tenor rates from the curve.

Parameters:

  • tenor (str) – The tenor of the forward rates to plot, e.g. “1D”, “3M”.

  • right (datetime or str, optional) – The right bound of the graph. If given as str should be a tenor format defining a point measured from the initial node date of the curve. Defaults to the final node of the curve minus the tenor.

  • left (datetime or str, optional) – The left bound of the graph. If given as str should be a tenor format defining a point measured from the initial node date of the curve. Defaults to the initial node of the curve.

  • comparators (list[Curve]) – A list of curves which to include on the same plot as comparators.

  • difference (bool) – Whether to plot as comparator minus base curve or outright curve levels in plot. Default is False.

  • labels (list[str]) – A list of strings associated with the plot and comparators. Must be same length as number of plots.

Returns:

(fig, ax, line)

Return type:

Matplotlib.Figure, Matplotplib.Axes, Matplotlib.Lines2D

rate(effective, termination, modifier=NoInput.blank, float_spread=None, spread_compound_method=None)#

Calculate the rate on the Curve using DFs.

If rates are sought for dates prior to the initial node of the curve None will be returned.

Parameters:

  • effective (datetime) – The start date of the period for which to calculate the rate.

  • termination (datetime or str) – The end date of the period for which to calculate the rate.

  • modifier (str, optional) – The day rule if determining the termination from tenor. If False is determined from the Curve modifier.

  • float_spread (float, optional) – A float spread can be added to the rate in certain cases.

  • spread_compound_method (str in {"none_simple", "isda_compounding"}) – The method if adding a float spread. If “none_simple” is used this results in an exact calculation. If “isda_compounding” or “isda_flat_compounding” is used this results in an approximation.

Return type:

Dual, Dual2 or float

Notes

Calculating rates from a curve implies that the conventions attached to the specific index, e.g. USD SOFR, or GBP SONIA, are applicable and these should be set at initialisation of the Curve. Thus, the convention used to calculate the rate is taken from the Curve from which rate is called.

modifier is only used if a tenor is given as the termination.

Major indexes, such as legacy IBORs, and modern RFRs typically use a convention which is either “Act365F” or “Act360”. These conventions do not need additional parameters, such as the termination of a leg, the frequency or a leg or whether it is a stub to calculate a DCF.

Adding Floating Spreads

An optimised method for adding floating spreads to a curve rate is provided. This is quite restrictive and mainly used internally to facilitate other parts of the library.

  • When spread_compound_method is “none_simple” the spread is a simple linear addition.

  • When using “isda_compounding” or “isda_flat_compounding” the curve is assumed to be comprised of RFR rates and an approximation is used to derive to total rate.

Examples

In [4]: curve_act365f = Curve(
   ...:     nodes={
   ...:         dt(2022, 1, 1): 1.0,
   ...:         dt(2022, 2, 1): 0.98,
   ...:         dt(2022, 3, 1): 0.978,
   ...:     },
   ...:     convention='Act365F'
   ...: )
   ...: 

In [5]: curve_act365f.rate(dt(2022, 2, 1), dt(2022, 3, 1))
Out[5]: 2.6657902424774402

Using a different convention will result in a different rate:

In [6]: curve_act360 = Curve(
   ...:     nodes={
   ...:         dt(2022, 1, 1): 1.0,
   ...:         dt(2022, 2, 1): 0.98,
   ...:         dt(2022, 3, 1): 0.978,
   ...:     },
   ...:     convention='Act360'
   ...: )
   ...: 

In [7]: curve_act360.rate(dt(2022, 2, 1), dt(2022, 3, 1))
Out[7]: 2.6292725679229547
roll(tenor)#

Create a new curve with its shape translated in time but an identical initial node date.

This curve adjustment is a simulation of a future state of the market where forward rates are assumed to have moved so that the present day’s curve shape is reflected in the future (or the past). This is often used in trade strategy analysis.

Parameters:

tenor (datetime or str) – The date or tenor by which to roll the curve. If a tenor, as str, will derive the datetime as measured from the initial node date. If supplying a negative tenor, or a past datetime, there is a limit to how far back the curve can be rolled - it will first roll backwards and then attempt to translate() forward to maintain the initial node date.

Return type:

Curve

Examples

The basic use of this function translates a curve forward in time and the plot demonstrates its rates are exactly the same as initially forecast.

In [8]: curve = Curve(
   ...:     nodes = {
   ...:         dt(2022, 1, 1): 1.0,
   ...:         dt(2023, 1, 1): 0.988,
   ...:         dt(2024, 1, 1): 0.975,
   ...:         dt(2025, 1, 1): 0.965,
   ...:         dt(2026, 1, 1): 0.955,
   ...:         dt(2027, 1, 1): 0.9475
   ...:     },
   ...:     t = [
   ...:         dt(2024, 1, 1), dt(2024, 1, 1), dt(2024, 1, 1), dt(2024, 1, 1),
   ...:         dt(2025, 1, 1),
   ...:         dt(2026, 1, 1),
   ...:         dt(2027, 1, 1), dt(2027, 1, 1), dt(2027, 1, 1), dt(2027, 1, 1),
   ...:     ],
   ...: )
   ...: 

In [9]: rolled_curve = curve.roll("6m")

In [10]: rolled_curve2 = curve.roll("-6m")

In [11]: curve.plot(
   ....:     "1d",
   ....:     comparators=[rolled_curve, rolled_curve2],
   ....:     labels=["orig", "rolled", "rolled2"],
   ....:     right=dt(2026, 7, 1),
   ....: )
   ....: 
Out[11]: 
(<Figure size 640x480 with 1 Axes>,
 <Axes: >,
 [<matplotlib.lines.Line2D at 0x7f0aa50b1710>,
  <matplotlib.lines.Line2D at 0x7f0aa5d09490>,
  <matplotlib.lines.Line2D at 0x7f0aa5d35b90>])

(Source code, png, hires.png, pdf)

../_images/rateslib-curves-IndexCurve-1.png
shift(spread, id=None, composite=True, collateral=None)#

Create a new curve by vertically adjusting the curve by a set number of basis points.

This curve adjustment preserves the shape of the curve but moves it up or down as a translation. This method is suitable as a way to assess value changes of instruments when a parallel move higher or lower in yields is predicted.

Parameters:

  • spread (float, Dual, Dual2) – The number of basis points added to the existing curve.

  • id (str, optional) – Set the id of the returned curve.

  • composite (bool, optional) – If True will return a CompositeCurve that adds a flat curve to the existing curve. This results in slower calculations but the curve will maintain a dynamic association with the underlying curve and will change if the underlying curve changes.

  • collateral (str, optional) – Designate a collateral tag for the curve which is used by other methods.

Return type:

Curve, CompositeCurve

Examples

In [12]: from rateslib.curves import Curve

In [13]: curve = Curve(
   ....:     nodes = {
   ....:         dt(2022, 1, 1): 1.0,
   ....:         dt(2023, 1, 1): 0.988,
   ....:         dt(2024, 1, 1): 0.975,
   ....:         dt(2025, 1, 1): 0.965,
   ....:         dt(2026, 1, 1): 0.955,
   ....:         dt(2027, 1, 1): 0.9475
   ....:     },
   ....:     t = [
   ....:         dt(2024, 1, 1), dt(2024, 1, 1), dt(2024, 1, 1), dt(2024, 1, 1),
   ....:         dt(2025, 1, 1),
   ....:         dt(2026, 1, 1),
   ....:         dt(2027, 1, 1), dt(2027, 1, 1), dt(2027, 1, 1), dt(2027, 1, 1),
   ....:     ],
   ....: )
   ....: 

In [14]: shifted_curve = curve.shift(25)

In [15]: curve.plot("1d", comparators=[shifted_curve], labels=["orig", "shift"])
Out[15]: 
(<Figure size 640x480 with 1 Axes>,
 <Axes: >,
 [<matplotlib.lines.Line2D at 0x7f0aa50be750>,
  <matplotlib.lines.Line2D at 0x7f0aa518ec50>])

(Source code, png, hires.png, pdf)

../_images/rateslib-curves-IndexCurve-2.png
to_json()#

Convert the parameters of the curve to JSON format.

Return type:

str

translate(start, t=False)#

Create a new curve with an initial node date moved forward keeping all else constant.

This curve adjustment preserves forward curve expectations as time evolves. This method is suitable as a way to create a subsequent opening curve from a previous day’s closing curve.

Parameters:

  • start (datetime) – The new initial node date for the curve, must be in the domain: (node_date[0], node_date[1]]

  • t (bool) – Set to True if the initial knots of the knot sequence should be translated forward.

Return type:

Curve

Examples

The basic use of this function translates a curve forward in time and the plot demonstrates its rates are exactly the same as initially forecast.

In [16]: curve = Curve(
   ....:     nodes = {
   ....:         dt(2022, 1, 1): 1.0,
   ....:         dt(2023, 1, 1): 0.988,
   ....:         dt(2024, 1, 1): 0.975,
   ....:         dt(2025, 1, 1): 0.965,
   ....:         dt(2026, 1, 1): 0.955,
   ....:         dt(2027, 1, 1): 0.9475
   ....:     },
   ....:     t = [
   ....:         dt(2024, 1, 1), dt(2024, 1, 1), dt(2024, 1, 1), dt(2024, 1, 1),
   ....:         dt(2025, 1, 1),
   ....:         dt(2026, 1, 1),
   ....:         dt(2027, 1, 1), dt(2027, 1, 1), dt(2027, 1, 1), dt(2027, 1, 1),
   ....:     ],
   ....: )
   ....: 

In [17]: translated_curve = curve.translate(dt(2022, 12, 1))

In [18]: curve.plot(
   ....:     "1d",
   ....:     comparators=[translated_curve],
   ....:     labels=["orig", "translated"],
   ....:     left=dt(2022, 12, 1),
   ....: )
   ....: 
Out[18]: 
(<Figure size 640x480 with 1 Axes>,
 <Axes: >,
 [<matplotlib.lines.Line2D at 0x7f0aa4c9e750>,
  <matplotlib.lines.Line2D at 0x7f0aa4c3f950>])

(Source code, png, hires.png, pdf)

../_images/rateslib-curves-IndexCurve-3_00_00.png 
In [19]: curve.nodes
Out[19]: 
{datetime.datetime(2022, 1, 1, 0, 0): 1.0,
 datetime.datetime(2023, 1, 1, 0, 0): 0.988,
 datetime.datetime(2024, 1, 1, 0, 0): 0.975,
 datetime.datetime(2025, 1, 1, 0, 0): 0.965,
 datetime.datetime(2026, 1, 1, 0, 0): 0.955,
 datetime.datetime(2027, 1, 1, 0, 0): 0.9475}

In [20]: translated_curve.nodes
Out[20]: 
{datetime.datetime(2022, 12, 1, 0, 0): 1.0,
 datetime.datetime(2023, 1, 1, 0, 0): 0.9989751829682344,
 datetime.datetime(2024, 1, 1, 0, 0): 0.9858307726660208,
 datetime.datetime(2025, 1, 1, 0, 0): 0.9757196878181642,
 datetime.datetime(2026, 1, 1, 0, 0): 0.9656086029703076,
 datetime.datetime(2027, 1, 1, 0, 0): 0.9580252893344151}

When a curve has a log-cubic spline the knot dates can be preserved or translated with the t argument. Preserving the knot dates preserves the interpolation of the curve. A knot sequence for a mixed curve which begins after start will not be affected in either case.

In [21]: curve = Curve(
   ....:     nodes={
   ....:         dt(2022, 1, 1): 1.0,
   ....:         dt(2022, 2, 1): 0.999,
   ....:         dt(2022, 3, 1): 0.9978,
   ....:         dt(2022, 4, 1): 0.9963,
   ....:         dt(2022, 5, 1): 0.9940
   ....:     },
   ....:     t = [dt(2022, 1, 1), dt(2022, 1, 1), dt(2022, 1, 1), dt(2022, 1, 1),
   ....:          dt(2022, 2, 1), dt(2022, 3, 1), dt(2022, 4, 1),
   ....:          dt(2022, 5, 1), dt(2022, 5, 1), dt(2022, 5, 1), dt(2022, 5, 1)]
   ....: )
   ....: 

In [22]: translated_curve = curve.translate(dt(2022, 1, 15))

In [23]: translated_curve2 = curve.translate(dt(2022, 1, 15), t=True)

In [24]: curve.plot("1d", left=dt(2022, 1, 15), comparators=[translated_curve, translated_curve2], labels=["orig", "translated", "translated2"])
Out[24]: 
(<Figure size 640x480 with 1 Axes>,
 <Axes: >,
 [<matplotlib.lines.Line2D at 0x7f0aa4bcbf10>,
  <matplotlib.lines.Line2D at 0x7f0aa4e8b350>,
  <matplotlib.lines.Line2D at 0x7f0aa4e8ba90>])

(Source code, png, hires.png, pdf)

../_images/rateslib-curves-IndexCurve-4.png