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, str) – The unadjusted effective date. If given as adjusted, unadjusted alternatives may be inferred. If given as string tenor will be calculated from eval_date and eval_mode.

• termination (datetime, str) – The unadjusted termination date. If given as adjusted, unadjusted alternatives may be inferred. If given as string tenor will be calculated from effective.

• frequency (Frequency, str in {"M", "Q", "S", "A", "Z", "_D", "_B", "_W", "_M", "_Y"}) – The frequency of the schedule. If given as string will derive a Frequency aligning with: monthly (“M”), quarterly (“Q”), semi-annually (“S”), annually(“A”) or zero-coupon (“Z”), or a set number of calendar or business days (“_D”, “_B”), weeks (“_W”), months (“_M”) or years (“_Y”). Where required, the RollDay is derived as per roll and business day calendar as per calendar.

• stub (StubInference, str in {"ShortFront", "LongFront", "ShortBack", "LongBack"}, optional) – The stub type used if stub inference is required. If given as string will derive a StubInference.

• front_stub (datetime, optional) – The unadjusted date for the start stub period. If given as adjusted, unadjusted alternatives may be inferred.

• back_stub (datetime, optional) – The unadjusted date for the back stub period. If given as adjusted, unadjusted alternatives may be inferred. See notes for combining stub, front_stub and back_stub and any automatic stub inference.

• roll (RollDay, int in [1, 31], str in {"eom", "imm", "som"}, optional) – The roll day of the schedule. If not given or not available in frequency will be inferred for monthly frequency variants.

• eom (bool, optional) – Use an end of month preference rather than regular rolls for roll inference. Set by default. Not required if roll is defined.

• modifier (Adjuster, str in {"NONE", "F", "MF", "P", "MP"}, optional) – The Adjuster used for adjusting unadjusted schedule dates into adjusted dates. If given as string must define simple date rolling rules.

• calendar (calendar, str, optional) – The business day calendar object to use. If string will call get_calendar().

• payment_lag (Adjuster, int, optional) – The Adjuster to use to map adjusted schedule dates into a payment date. If given as integer will define 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.

Examples

Original InputsCore Inputs

The original inputs allow for a more UI friendly input for the most common schedules.

In [1]: s = Schedule(
   ...:     effective=dt(2024, 1, 3),
   ...:     termination=dt(2024, 11, 29),
   ...:     frequency="Q",
   ...:     stub="ShortFront",
   ...:     modifier="MF",
   ...:     payment_lag=2,
   ...:     calendar="tgt",
   ...:     eom=True,
   ...: )
   ...: 

In [2]: print(s)
freq: 3M (roll: 31), accrual adjuster: MF, payment adjuster: 2B,
    Period Unadj Acc Start Unadj Acc End  Acc Start    Acc End    Payment
0     Stub      2024-01-03    2024-02-29 2024-01-03 2024-02-29 2024-03-04
1  Regular      2024-02-29    2024-05-31 2024-02-29 2024-05-31 2024-06-04
2  Regular      2024-05-31    2024-08-31 2024-05-31 2024-08-30 2024-09-03
3  Regular      2024-08-31    2024-11-30 2024-08-30 2024-11-29 2024-12-03

Notes

Inference

It is not necessary to rely on inference if inputs are defined directly. However three types of inference will be performed otherwise:

• Unadjusted date inference if any dates including stubs are given as adjusted.

• Frequency inference if the frequency is missing properties, such as roll.

• Stub date inference if a regular schedule cannot be defined without stubs one can be unambiguously implied.

Rateslib always tries to infer regular schedules ahead of irregular schedules. Failing that, it always tries to infer dates and rolls as close as possible to those given by a user.

Dates given as string tenor - The 1Y1Y problem

When generating schedules implied from tenor effective and termination dates there exist different theoretical ways of deriving these dates. Rateslib offers two practical methods for doing this, configurable by setting the eval_mode argument to either “swaps_align” or “swaptions_align”.

‘swaps_align’‘swaptions_align’

This method aligns dates with those implied by a sub-component of a par tenor swap. E.g. a 1Y1Y schedule is expected to align with the second half of a 2Y par swap. To achieve this, an unadjusted effective date is determined from eval_date and an unadjusted termination date is derived from that effective date.

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

• A 1Y has effective, termination and roll of: Tue 17th Aug ‘23, Mon 19th Aug ‘24, 17.

• A 2Y has effective, termination and roll of: Tue 17th Aug ‘23, Mon 18th Aug ‘25, 17.

• A 1Y1Y has effective, termination and roll of: Mon 19th Aug ‘24, Mon 18th Aug ‘25, 17.

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

In [6]: print(s)
freq: 6M (roll: 17), accrual adjuster: MF, payment adjuster: 2B,
    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

Attributes Summary

accrual_adjuster	The Adjuster object used for accrual date adjustment.
aschedule	A list of the adjusted accrual dates.
calendar	The calendar used for date adjustment by the accrual_adjuster and payment_adjuster.
effective	The adjusted effective date of the schedule.
frequency	Original string representation of the Frequency.
frequency_obj	The Frequency object determining the periods.
modifier	Alias for the accrual_adjuster.
n_periods	The number of periods contained in the schedule.
obj	A wrapped instance of the Rust implemented Schedule.
payment_adjuster	The Adjuster object used for payment date adjustment.
periods_per_annum	Average number of coupons per annum.
pschedule	A list of the cashflow payment dates.
roll	The RollDay object associated with Frequency, if available.
table	A DataFrame of schedule dates and classification.
termination	The adjusted termination date of the schedule.
uback_stub	The unadjusted back stub date of the schedule.
ueffective	The unadjusted effective date of the schedule.
ufront_stub	The unadjusted front stub date of the schedule.
uschedule	A list of the unadjusted schedule dates.
utermination	The unadjusted termination date of the schedule.

Methods Summary

is_regular()	Returns whether the schedule is composed only of regular periods (no stubs).
to_json()	Return a JSON representation of the object.

Attributes Documentation

accrual_adjuster

The Adjuster object used for accrual date adjustment.

aschedule

A list of the adjusted accrual dates.

These are determined by applying the accrual_adjuster to uschedule.

calendar

The calendar used for date adjustment by the accrual_adjuster and payment_adjuster.

effective

The adjusted effective date of the schedule.

frequency

Original string representation of the Frequency.

frequency_obj

The Frequency object determining the periods.

modifier

Alias for the accrual_adjuster.

n_periods

The number of periods contained in the schedule.

obj

A wrapped instance of the Rust implemented Schedule.

payment_adjuster

The Adjuster object used for payment date adjustment.

periods_per_annum

Average number of coupons per annum. See periods_per_annum().

pschedule

A list of the cashflow payment dates.

These are determined by applying the payment_adjuster to aschedule.

roll

The RollDay object associated with Frequency, if available.

table

A DataFrame of schedule dates and classification.

termination

The adjusted termination date of the schedule.

uback_stub

The unadjusted back stub date of the schedule.

ueffective

The unadjusted effective date of the schedule.

ufront_stub

The unadjusted front stub date of the schedule.

uschedule

A list of the unadjusted schedule dates.

utermination

The unadjusted termination date of the schedule.

Methods Documentation

is_regular()

Returns whether the schedule is composed only of regular periods (no stubs).

to_json()

Return a JSON representation of the object.

Return type:

str