Schedule#

class rateslib.scheduling.Schedule(effective, termination, frequency, stub=NoInput.blank, front_stub=NoInput.blank, back_stub=NoInput.blank, roll=NoInput.blank, eom=NoInput.blank, modifier=NoInput.blank, calendar=NoInput.blank, payment_lag=NoInput.blank, eval_date=NoInput.blank, eval_mode=NoInput.blank)#

Bases: object

Generate a schedule of dates according to a regular pattern and calendar inference.

Parameters:

effective (datetime) – The adjusted or unadjusted effective date.
termination (datetime or str) – The adjusted or unadjusted termination date. If a string, then a tenor must be given expressed in days (“D”), months (“M”) or years (“Y”), e.g. “48M”.
frequency (str in {"M", "B", "Q", "T", "S", "A", "Z"}, optional) – The frequency of the schedule where the options are: M(onthly), B(i-monthly), T(hirdly), Q(uarterly), S(emi-annually), A(nnually), Z(ero-coupon).
stub (str combining {"SHORT", "LONG"} with {"FRONT", "BACK"}, optional) – The stub type to enact on the swap. Can provide two types, for example “SHORTFRONTLONGBACK”.
front_stub (datetime, optional) – An adjusted or unadjusted date for the first stub period.
back_stub (datetime, optional) – An adjusted or unadjusted date for the back stub period. See notes for combining stub, front_stub and back_stub and any automatic stub inference.
roll (int in [1, 31] or str in {"eom", "imm", "som"}, optional) – The roll day of the schedule. Inferred if not given.
eom (bool, optional) – Use an end of month preference rather than regular rolls for inference. Set by default. Not required if roll is specified.
modifier (str, optional) – The modification rule, in {“NONE”, “F”, “MF”, “P”, “MP”}
calendar (calendar or str, optional) – The holiday calendar object to use. If string will call get_calendar().
payment_lag (int, optional) – The number of business days to lag payments by.
eval_date (datetime, optional) – Only required if effective is given as a string tenor, to provide a point of reference.
eval_mode (str in {"swaps_align", "swaptions_align"}) – The method for determining the effective and termination dates if both are provided as string tenors. See notes.

ueffective#

Type:: datetime

effective#

Type:: datetime

utermination#

Type:: datetime

termination#

Type:: datetime

frequency#

Type:: str

stub#

Type:: str

front_stub#

Type:: datetime

back_stub#

Type:: datetime

roll#

Type:: int or str

eom#

Type:: bool

modifier#

Type:: str

calendar#

Type:: calendar

payment_lag#

Type:: int

uschedule#

Type:: list[datetime]

aschedule#

Type:: list[datetime]

pschedule#

Type:: list[datetime]

stubs#

Type:: list[bool]

eval_date#

Type:: datetime

eval_mode#

Type:: str

Notes

Zero coupon schedules

If frequency is Z then stub arguments are ignored.

Inferred termination date and roll from tenor - The 1Y1Y problem

When generating schedules implied from tenor effective and termination dates there exist two methods for doing this. Both have practical reasons to exist. This results in the eval_mode argument which allows either “swaps_align” or “swaptions_align”. So, what is the difference and the purpose?

Swaps Align

When a EUR swap dealer trades a 1Y1Y swap he will hedge it in the interbank market with a 1Y and a 2Y swap. 1Y and 2Y swaps have roll days that are generated from the same evaluation date. For a perfect hedge the 1Y1Y swap should also have the same roll day and its periods should align with the second half of the 2Y swap. To achieve this, the effective date is calculated unadjusted and the termination date is derived from that unadjusted date. Then under rateslib inferral rules this will produce the correct schedule.

For example, today is Tue 15th Aug ‘23 and spot is Thu 17th Aug ‘23:

A 1Y trade has effective, termination and roll of: Tue 17th Aug ‘23, Mon 19th Aug ‘24, 17.
A 2Y trade has effective, termination and roll of: Tue 17th Aug ‘23, Mon 18th Aug ‘25, 17.
A 1Y1Y trade has effective, termination and roll of: Mon 19th Aug ‘24, Mon 18th Aug ‘25, 17.

In [1]: sch = Schedule(
   ...:     effective="1Y",
   ...:     termination="1Y",
   ...:     frequency="S",
   ...:     calendar="tgt",
   ...:     eval_date=dt(2023, 8, 17),
   ...:     eval_mode="swaps_align",
   ...: )
   ...: 

In [2]: sch
Out[2]: 
freq: S,  stub: SHORTFRONT,  roll: 17,  pay lag: 2,  modifier: MF
    Period Unadj Acc Start Unadj Acc End  Acc Start    Acc End    Payment
0  Regular      2024-08-17    2025-02-17 2024-08-19 2025-02-17 2025-02-19
1  Regular      2025-02-17    2025-08-17 2025-02-17 2025-08-18 2025-08-20

Swaptions Align

When a swaptions dealer trades a 1Y1Y swaption, that trade will settle against the 1Y swap evaluated as of the expiry date (in 1Y) against the swap ISDA fixing. The delta exposure the swaption trader experiences is best hedged with a swap matching those dates. This means that the effective date of the swap should be derived from an adjusted date.

For example, today is Tue 15th Aug ‘23:

A 1Y expiring swaption has an expiry on Thu 15th Aug ‘24.
At expiry a spot starting 1Y swap has effective, termination, and roll of: Mon 19th Aug ‘24, Tue 19th Aug ‘25, 19.

In [3]: sch = Schedule(
   ...:     effective="1Y",
   ...:     termination="1Y",
   ...:     frequency="S",
   ...:     calendar="tgt",
   ...:     eval_date=dt(2023, 8, 17),
   ...:     eval_mode="swaptions_align",
   ...: )
   ...: 

In [4]: sch
Out[4]: 
freq: S,  stub: SHORTFRONT,  roll: 19,  pay lag: 2,  modifier: MF
    Period Unadj Acc Start Unadj Acc End  Acc Start    Acc End    Payment
0  Regular      2024-08-19    2025-02-19 2024-08-19 2025-02-19 2025-02-21
1  Regular      2025-02-19    2025-08-19 2025-02-19 2025-08-19 2025-08-21

Note

To avoid these, it is recommended to provide effective, termination, as unadjusted dates (and also front_stub and back_stub) since this eliminates the combinatorial aspect of date inference. Also providing roll is more explicit.

Inferred stub dates from inputs

The following input arguments are provided; stub, front_stub and back_stub. These are optional and in the case one or more are NoInput, then the code will attempt to infer stub scheduling.

Inference when `stub` is *None* in combination with stub dates#
`front_stub`:	datetime	datetime	NoInput	NoInput
`back_stub`:	datetime	NoInput	datetime	NoInput
`stub` defaults to:	“FRONTBACK”	“FRONT”	“BACK”	`defaults.stub` (“SHORTFRONT”)
Method called:	`_check_regular_swap()`	`_check_regular_swap()`	`_check_regular_swap()`	`_infer_stub_date()`

In the case that _check_regular_swap() is called this will attempt to ensure that the given stub dates align either with each other, or with the associated effective or termination dates. If they do not align then an error is raised.

In the case all are NoInput and _infer_stub_date() is called this will first check for a regular swap to ensure a stub is required and if so will generate the appropriate stub at the front or back as necessary.

Inference when `stub` is given in combination with stub dates#
`front_stub`:	datetime	datetime	NoInput	NoInput
`back_stub`:	datetime	NoInput	datetime	NoInput
`stub` is dual sided	`_check_regular_swap()`	`_infer_stub_date()`	`_infer_stub_date()`	ValueError
`stub` is front sided	ValueError	`_check_regular_swap()`	ValueError	`_infer_stub_date()`
`stub` is back sided	ValueError	ValueError	`_check_regular_swap()`	`_infer_stub_date()`

Handling stubs and rolls

If front_stub and back_stub are given, the stub is not used. There is no validation check to ensure that the given dated stubs conform to the stub type, for example if the front stub conforms to a long front or a short front.

Dates only object

A Schedule is a dates only object, meaning the attributes necessary for cashflow calculation and generation, such as day count convention and notional amounts are not attributed to this object. Those will be handled by the appropriate Leg object.

Attributes Summary

`n_periods`	Number of periods contained in the schedule.
`table`	Rows of schedule dates and information.

Attributes Documentation

n_periods#

Number of periods contained in the schedule.

Type:: int

table#

Rows of schedule dates and information.

Type:: DataFrame