How to make a UK holiday calendar in pandas

Do you want to make custom holiday calendar with pandas?

By default, you can import pandas US Federal Holidays by using this command from pandas.tseries.holiday import USFederalHoildayCalendar but if you live outside of the US you need to make your own type of calendar class. Which is probably why you are checking out this blog post.

If you are using these calendars in a business setting you may want to calculate business days. To work out how long a project may go on for. Or working out an employee’s working days. Etc. You see below how pandas business days are used using the holiday calendar.

Holiday Calendar Class

A Holiday Calendar class is made up of rules where you will define the dates of the holidays. For fixed dates like Christmas and New year’s an observance rule used to determine where the holiday falls.

Source: https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html?highlight=holiday#holidays-holiday-calendars

For non-fixed days, which is the majority of UK holidays. You will need to use a DateOffset function. A DateOffset object increments the time of your chosen date. While keeping in calendar rules, unlike timedelta. Calendar rule like starting a new day at midnight. Or moving the date by business days.

UK Hoilday Calendar Code

The code is from this website. (The page is archived as a live version is not available. If it is, please message me.)

I will explain an example to see how a holiday is made.

Holiday(‘Early May Bank Holiday’, month=5, day=1, offset=DateOffset(weekday=MO(1)))

Month=5 defines the month of May. And day=1 defines the first day. The offset variable using the DateOffset object mentioned earlier. weekday=MO(1) defines the first Monday. As MO is shorthand for Monday. This is used in the context of setting up the Early May Bank Holiday as this holiday falls on the first Monday in May.

Weekday instances are explained below:

weekday:

One of the weekday instances (MO, TU, etc) available in the relativedelta module. These instances may receive a parameter N, specifying the Nth weekday, which could be positive or negative (like MO(+1) or MO(-2)). Not specifying it is the same as specifying +1. You can also use an integer, where 0=MO. This argument is always relative e.g. if the calculated date is already Monday, using MO(1) or MO(-1) won’t change the day. To effectively make it absolute, use it in combination with the day argument (e.g. day=1, MO(1) for first Monday of the month).

— https://dateutil.readthedocs.io/en/latest/relativedelta.html#dateutil.relativedelta.relativedelta

Another example of one of the rules added to the class:

Holiday(‘Christmas Day’, month=12, day=25, observance=next_monday),

Observance variable is used as Christmas is on a fixed date. In tradition, if Christmas day falls on a Sunday or Saturday the following Monday is set up as a bank holiday.

If you will like find sources on how holidays are picked, then check the links below:

Bank holiday

Public holidays in the United Kingdom

Holidays and observances in United Kingdom in 2020

Business Days

Now after creating the holiday calendar from above you can calculate business days. To do so you will need to create a custom business day. This is done by using the CDay dateOffeset function:

custom_buiness_days = CDay(calendar=Hoildays_England_and_Wales())

After that you now multiple dates using the calendar from above.

from datetime import date
from pandas.tseries.offsets import CDay, Week
print(date.today())
>>> 2020-06-18
One_week_later = date.today() + Week()
print(One_week_later)
>>> 2020-06-25 00:00:00
Three_buisness_days_later = date.today() + (custom_buiness_days * 3)
print(Three_buisness_days_later)
>>> 2020-06-23 00:00:00

If you want to pick a specific date or time, you can use pandas datetime or timestamp.

certain_date = datetime(2020, 4, 25, 10, 0)
One_month_later = certain_date + MonthEnd() + Day()
print(One_month_later)
>>> 2020-05-01 10:00:00
tz_bus_day = pd.offsets.CustomBusinessDay(calendar=Hoildays_England_and_Wales())
ts = pd.Timestamp('2016-10-30 00:00:00', tz='Europe/Helsinki')
two_business_days = 2 * pd.offsets.CustomBusinessDay()
print(two_business_days.apply(ts))
>>> 2016-11-01 00:00:00+02:00

Read more dateOffsets and ranges to use check the pandas docs.

Conclusion

Now you know the basics of using creating custom calendars and business dates. Feel free to use the code examples above and share any examples of you using this code for your projects.

Like the content your reading?

Published on my website:

https://www.tobiolabode.com/blog/2019/1/1/pandas-for-uk-hoildays