add_tenor#

rateslib.scheduling.add_tenor(start, tenor, modifier, calendar=NoInput.blank, roll=NoInput.blank, settlement=False, mod_days=False)#

Add a tenor to a given date under specific modification rules and holiday calendar.

Warning

Note this function does not validate the roll input, but expects it to be correct. That is this function acts on start as an unchecked date. See notes.

Parameters:

  • start (datetime) – The date to which to add the tenor.

  • tenor (str | Frequency) – The tenor to add, identified by calendar days, “D”, months, “M”, years, “Y” or business days, “B”, for example “10Y” or “5B”.

  • modifier (str, optional in {"NONE", "MF", "F", "MP", "P"} | Adjuster) – The modification rule to apply if the tenor is calendar days, months or years.

  • calendar (CustomBusinessDay or str, optional) – The calendar for use with business day adjustment and modification.

  • roll (str, int, RollDay, optional) – This is only required if the tenor is given in months or years. Ensures the tenor period associates with a schedule’s roll day.

  • settlement (bool, optional) – If modifier is string this determines whether to enforce the settlement with an associated settlement calendar, if provided.

  • mod_days (bool, optional) – If modifier is string and tenor is a day variant setting this to False will convert “MF” to “F” and “MP” to “P”.

Return type:

datetime

Notes

This method is a convenience function for coordinating a Frequency date manipulation and an Adjuster, from simple UI inputs. For example the following:

In [1]: add_tenor(dt(2023, 9, 29), "-6m", "MF", NamedCal("bus"), 31)
Out[1]: datetime.datetime(2023, 3, 31, 0, 0)

is internally mapped to the following, where next() performs an unchecked date period determination:

In [2]: unadjusted_date = Frequency.Months(-6, RollDay.Day(31)).next(dt(2023, 9, 29))

In [3]: Adjuster.ModifiedFollowing().adjust(unadjusted_date, NamedCal("bus"))
Out[3]: datetime.datetime(2023, 3, 31, 0, 0)

The allowed string inputs {‘B’, ‘D’, ‘W’, ‘M’, ‘Y’} for business days, calendar days, weeks, months and years are mapped to an appropriate Frequency variant (potentially also mapping a RollDay), and an appropriate Adjuster is derived from the combination of the modifier, settlement and mod_days arguments.

Read more about the settlement argument in the calendar user guide.

The mod_days argument is provided to avoid having to reconfigure Instrument specifications when a termination may differ between months or years, and days or weeks. Most Instruments will be defined by the typical modified following (“MF”) modifier, but this would prefer not to always apply.

In [4]: add_tenor(dt(2021, 1, 29), "1M", "MF", "bus")
Out[4]: datetime.datetime(2021, 2, 26, 0, 0)

while, the following will by default roll into a new month,

In [5]: add_tenor(dt(2021, 1, 22), "8d", "MF", "bus")
Out[5]: datetime.datetime(2021, 2, 1, 0, 0)

unless day type frequencies are also specifically modified,

In [6]: add_tenor(dt(2021, 1, 22), "8d", "MF", "bus", mod_days=True)
Out[6]: datetime.datetime(2021, 1, 29, 0, 0)

Examples

In [7]: add_tenor(dt(2022, 2, 28), "3M", "NONE")
Out[7]: datetime.datetime(2022, 5, 28, 0, 0)

In [8]: add_tenor(dt(2022, 12, 28), "4b", "F", get_calendar("ldn"))
Out[8]: datetime.datetime(2023, 1, 4, 0, 0)

In [9]: add_tenor(dt(2022, 12, 28), "4d", "F", get_calendar("ldn"))
Out[9]: datetime.datetime(2023, 1, 3, 0, 0)
On this page

This Page