Tools

Date Tools

Period

class rivapy.tools.Period(years: int = 0, months: int = 0, days: int = 0)

Time Period expressed in years, months and days.

Parameters:

• years (int, optional) – Number of years in time period. Defaults to 0.

• months (int, optional) – Number of months in time period. Defaults to 0.

• days (int, optional) – Number of days in time period. Defaults to 0.

property days: int

Getter for number of days in time period.

Returns:

Number of days for specified time period.

Return type:

int

static from_string(period: str)

Creates a Period from a string

Parameters:

period (str) – The string defining the period. The string must be defined by the number of days/months/years followed by one of the letters ‘Y’/’M’/’D’, i.e. ‘6M’ means 6 months.

Returns:

The resulting period

Return type:

Period

Examples

>>> p = Period('6M')  # period of 6 months
>>> p = Period('1Y') #period of 1 year

property months: int

Getter for months of period.

Returns:

Number of months for specified time period.

Return type:

int

property years: int

Getter for years of period.

Returns:

Number of years for specified time period.

Return type:

int

Schedules

class rivapy.tools.Schedule(start_day: date | datetime, end_day: date | datetime, time_period: Period | str, backwards: bool = True, stub: bool = False, business_day_convention: RollConvention | str = RollConvention.MODIFIED_FOLLOWING, calendar: HolidayBase | str = None)

A schedule is a list of dates, e.g. of coupon payments, fixings, etc., which is defined by its fist (= start day) and last (= end day) day, by its distance between two consecutive dates (= time period) and by the procedure for rolling out the schedule, more precisely by the direction (backwards/forwards) and the dealing with incomplete periods (stubs). Moreover, the schedule ensures to comply to business day conventions with respect to a specified holiday calendar.

Parameters:

• start_day (_Union[date, datetime]) – Schedule’s first day - beginning of the schedule.

• end_day (_Union[date, datetime]) – Schedule’s last day - end of the schedule.

• time_period (_Union[Period, str]) – Time distance between two consecutive dates.

• backwards (bool, optional) – Defines direction for rolling out the schedule. True means the schedule will be rolled out (backwards) from end day to start day. Defaults to True.

• stub (bool, optional) – Defines if the first/last period is accepted (True), even though it is shorter than the others, or if it remaining days are added to the neighbouring period (False). Defaults to True.

• business_day_convention (_Union[RollConvention, str], optional) – Set of rules defining the adjustment of days to ensure each date being a business day with respect to a given holiday calendar. Defaults to RollConvention.MODIFIED_FOLLOWING

• calendar (_Union[_HolidayBase, str], optional) – Holiday calendar defining the bank holidays of a country or province (but not all non-business days as for example Saturdays and Sundays). Defaults (through constructor) to holidays.ECB (= Target2 calendar) between start_day and end_day.

Examples

>>> from datetime import date
>>> from rivapy.tools import schedule
>>> schedule = Schedule(date(2020, 8, 21), date(2021, 8, 21), Period(0, 3, 0), True, False, RollConvention.UNADJUSTED, holidays_de).generate_dates(False),
       [date(2020, 8, 21), date(2020, 11, 21), date(2021, 2, 21), date(2021, 5, 21), date(2021, 8, 21)])

property backwards

Getter for schedule’s roll out direction.

Returns:

True, if rolled out from end day to start day. False, if rolled out from start day to end day.

property business_day_convention

Getter for schedule’s business day convention.

Returns:

Business day convention of specified schedule.

property calendar

Getter for schedule’s holiday calendar.

Returns:

Holiday calendar of specified schedule.

property end_day

Getter for schedule’s end date.

Returns:

End date of specified schedule.

generate_dates(ends_only: bool) → List[date]

Generate list of schedule days according to the schedule specification, in particular with regards to business day convention and calendar given.

Parameters:

ends_only (bool) – Flag to indicate if period beginnings shall be included, e.g. for defining accrual periods: True, if only period ends shall be included, e.g. for defining payment dates.

Returns:

List of schedule dates (including start and end date) adjusted to rolling convention.

Return type:

List[date]

property start_day

Getter for schedule’s start date.

Returns:

Start date of specified schedule.

property stub

Getter for potential existence of short periods (stubs).

Returns:

True, if a shorter period is allowed. False, if only a longer period is allowed.

property time_period

Getter for schedule’s time period.

Returns:

Time period of specified schedule.

class rivapy.tools.SimpleSchedule(start: datetime, end: datetime, freq: str = 'h', weekdays: Set[int] = None, hours: Set[int] = None, ignore_hours_for_weekdays: Set[int] = None, tz: str = None)

Bases: FactoryObject

Simple schedule of fixed datetime points.

Parameters:

• start (dt.datetime) – Start of schedule (including this timepoint).

• end (dt.datetime) – End of schedule (excluding this timepoint).

• freq (str, optional) – Frequency of timepoints. Defaults to ‘h’. See documentation for pandas.date_range for further details on freq.

• weekdays (Set[int], optional) – List of integers representing the weekdays where the schedule is defined. Integers according to datetime weekdays (0->Monay, 1->Tuesday,…,6->Sunday). If None, all weekdays are used. Defaults to None.

• hours (Set[int], optional) – List of hours where schedule is defined. If None, all hours are included. Defaults to None.

• ignor_hours_for_weekdays (Set[int], optional) – List of days for which the hours setting is ignored and each hour is considered where the schedule is defined. Defaults to None.

• tz (str or tzinfo) – Time zone name for returning localized datetime points, for example ‘Asia/Hong_Kong’. By default, the resulting datetime points are timezone-naive. See documentation for pandas.date_range for further details on tz.

Examples:

>>> simple_schedule = SimpleSchedule(dt.datetime(2023,1,1), dt.datetime(2023,1,1,4,0,0), freq='h')
>>> simple_schedule.get_schedule()
[datetime(2023,1,1,0,0,0), datetime(2023,1,1,1,0,0), datetime(2023,1,1,2,0,0), datetime(2023,1,1,3,0,0)]

# We include only hours 2 and 3 into schedule
>>> simple_schedule = SimpleSchedule(dt.datetime(2023,1,1), dt.datetime(2023,1,1,4,0,0), freq='h', hours=[2,3])
>>> simple_schedule.get_schedule()
[datetime.datetime(2023, 1, 1, 2, 0), datetime.datetime(2023, 1, 1, 3, 0)]

# We restrict further to only mondays as weekdays included
>>> simple_schedule = SimpleSchedule(dt.datetime(2023,1,1), dt.datetime(2023,1,2,4,0,0), freq='h', hours=[2,3], weekdays=[0])
>>> simple_schedule.get_schedule()
[datetime.datetime(2023, 1, 2, 2, 0), datetime.datetime(2023, 1, 2, 3, 0)]

class rivapy.tools.PeakSchedule(start: datetime, end: datetime, tz: str = None)

Bases: SimpleSchedule

Scheduler, which returns the peak time grid between the start and end date times.

Parameters:

• start (dt.datetime) – Start of schedule (including this timepoint).

• end (dt.datetime) – End of schedule (excluding this timepoint).

• tz (str or tzinfo) – Time zone name for returning localized datetime points, for example ‘Asia/Hong_Kong’. By default, the resulting datetime points are timezone-naive. See documentation for pandas.date_range for further details on tz.

Examples:

>>> peak_schedule = PeakSchedule(dt.datetime(2023,1,5), dt.datetime(2023,1,6))
>>> peak_schedule.get_schedule()
[datetime.datetime(2023, 1, 5, 8, 0),
 datetime.datetime(2023, 1, 5, 9, 0),
 datetime.datetime(2023, 1, 5, 10, 0),
 datetime.datetime(2023, 1, 5, 11, 0),
 datetime.datetime(2023, 1, 5, 12, 0),
 datetime.datetime(2023, 1, 5, 13, 0),
 datetime.datetime(2023, 1, 5, 14, 0),
 datetime.datetime(2023, 1, 5, 15, 0),
 datetime.datetime(2023, 1, 5, 16, 0),
 datetime.datetime(2023, 1, 5, 17, 0),
 datetime.datetime(2023, 1, 5, 18, 0),
 datetime.datetime(2023, 1, 5, 19, 0)]

class rivapy.tools.OffPeakSchedule(start: datetime, end: datetime, tz: str = None)

Bases: SimpleSchedule

Scheduler, which returns the offpeak time grid between the start and end date times.

Parameters:

• start (dt.datetime) – Start of schedule (including this timepoint).

• end (dt.datetime) – End of schedule (excluding this timepoint).

• tz (str or tzinfo) – Time zone name for returning localized datetime points, for example ‘Asia/Hong_Kong’. By default, the resulting datetime points are timezone-naive. See documentation for pandas.date_range for further details on tz.

Examples:

>>> offpeak_schedule = OffPeakSchedule(dt.datetime(2023,1,5), dt.datetime(2023,1,6))
>>> offpeak_schedule.get_schedule()
[datetime.datetime(2023, 1, 5, 0, 0),
 datetime.datetime(2023, 1, 5, 1, 0),
 datetime.datetime(2023, 1, 5, 2, 0),
 datetime.datetime(2023, 1, 5, 3, 0),
 datetime.datetime(2023, 1, 5, 4, 0),
 datetime.datetime(2023, 1, 5, 5, 0),
 datetime.datetime(2023, 1, 5, 6, 0),
 datetime.datetime(2023, 1, 5, 7, 0),
 datetime.datetime(2023, 1, 5, 20, 0),
 datetime.datetime(2023, 1, 5, 21, 0),
 datetime.datetime(2023, 1, 5, 22, 0),
 datetime.datetime(2023, 1, 5, 23, 0)]

class rivapy.tools.GasSchedule(start: datetime, end: datetime, tz: str = None)

Bases: SimpleSchedule

Scheduler, which returns the gas day time grid (from 6 am to 6 am) between the start and end date times.

Parameters:

• start (dt.datetime) – Start of schedule (including this timepoint).

• end (dt.datetime) – End of schedule (excluding this timepoint).

• tz (str or tzinfo) – Time zone name for returning localized datetime points, for example ‘Asia/Hong_Kong’. By default, the resulting datetime points are timezone-naive. See documentation for pandas.date_range for further details on tz.

Examples:

>>> gas_schedule = GasSchedule(dt.datetime(2023,1,5), dt.datetime(2023,1,7))
>>> gas_schedule.get_schedule()
[datetime.datetime(2023, 1, 5, 6, 0), datetime.datetime(2023, 1, 6, 6, 0)]

DateTimeGrid

class rivapy.tools.DateTimeGrid(datetime_grid: DatetimeIndex = None, start: datetime | Timestamp = None, end: datetime | Timestamp = None, freq: str = '1H', daycounter: str | DayCounterType = DayCounterType.Act365Fixed, tz=None, inclusive='left')

Object to handle datetimes together with their respective timegridpoints (according to a given daycount convention)

Parameters:

• datetime_grid (pd.DatetimeIndex, optional) – A grid of datetime values that is then transformed to datapoints. Defaults to None. Note that either this or a start and end date together with a frequency must be given. If a start date and a datetimegrid are specified at the same time, an exception will be thrown.

• start (Union[dt.datetime, pd.Timestamp], optional) – Start date of the datetime grid. Defaults to None.

• end (Union[dt.datetime, pd.Timestamp], optional) – Enddate of the datetimegrid. The parameter inclusive specifies whether the end date will be included into the grid or not.. Defaults to None.

• freq (str, optional) – A frequency string. Defaults to ‘1H’. See the documentation for the pandas function pandas.date_range() for more details of this string.

• daycounter (Union[str, DayCounterType], optional) – String or daycounterType used to compute the timepoints internally. Defaults to DayCounterType.Act365Fixed.

• tz (str, optional) – Time zone name for returning localized DatetimeIndex, see the pandas function pandas.date_range() for more details. Defaults to None.

• inclusive (str, optional) – Defines which boundary is included into the grid, see the pandas function :pandas.date_range(). Defaults to ‘left’.

Raises:

ValueError – If both, datetime_grid and start, are either None or not None.

get_daily_subgrid() → DateTimeGrid

Return a new datetime grid that is a subgrid of the current grid consisting of just daily values.

Returns:

Reulting grid.

Return type:

DateTimeGrid

get_day_of_week()

get_day_of_year()

get_hour_of_day()

get_minute_of_day()

Enums

class rivapy.tools.enums.InterpolationType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

CONSTANT = 'CONSTANT'

CONSTRAINED_SPLINE = 'CONSTRAINED_SPLINE'

HAGAN = 'HAGAN'

HAGAN_DF = 'HAGAN_DF'

LINEAR = 'LINEAR'

LINEAR_LOG = 'LINEARLOG'

class rivapy.tools.enums.ExtrapolationType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

CONSTANT = 'CONSTANT'

LINEAR = 'LINEAR'

LINEAR_LOG = 'LINEARLOG'

NONE = 'NONE'

class rivapy.tools.enums.SecuritizationLevel(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

COLLATERALIZED = 'COLLATERALIZED'

EQUITY = 'EQUITY'

MEZZANINE = 'MEZZANINE'

NONE = 'NONE'

NON_PREFERRED_SENIOR = 'NON_PREFERRED_SENIOR'

PREFERRED_SENIOR = 'PREFERRED_SENIOR'

SENIOR_SECURED = 'SENIOR_SECURED'

SENIOR_UNSECURED = 'SENIOR_UNSECURED'

SUBORDINATED = 'SUBORDINATED'

class rivapy.tools.enums.RollConvention(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

FOLLOWING = 'Following'

MODIFIED_FOLLOWING = 'ModifiedFollowing'

MODIFIED_FOLLOWING_BIMONTHLY = 'ModifiedFollowingBimonthly'

MODIFIED_FOLLOWING_EOM = 'ModifiedFollowingEOM'

MODIFIED_PRECEDING = 'ModifiedPreceding'

NEAREST = 'Nearest'

PRECEDING = 'Preceding'

UNADJUSTED = 'Unadjusted'

class rivapy.tools.enums.DayCounterType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

ACT252 = 'Act252'

ACT360 = 'Act360'

ACT_ACT = 'ActAct'

Act365Fixed = 'Act365Fixed'

ThirtyE360 = '30E360'

ThirtyU360 = '30U360'

class rivapy.tools.enums.InflationInterpolation(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

CONSTANT = 'CONSTANT'

GERMAN = 'GERMAN'

JAPAN = 'JAPAN'

UNDEFINED = 'UNDEFINED'

class rivapy.tools.enums.VolatilityStickyness(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

NONE = 'NONE'

StickyFwdMoneyness = 'StickyFwdMoneyness'

StickyStrike = 'StickyStrike'

StickyXStrike = 'StickyXStrike'