Pandas Time Series: How to specify custom holidays

Introduction

Pandas is a powerful data manipulation library in Python, especially revered when dealing with time series data. Its flexibility allows for easy handling of dates, times, and intervals—crucial for time-series analysis. A common task in financial and analytics applications is to consider business days, explicitly accounting for weekends and holidays. This article will dive into how to specify custom holidays using Pandas, ensuring your time series data accurately reflects the working calendar.

Getting Started

First, ensure you have Pandas and NumPy installed in your environment:

pip install pandas numpy

Also, install the pandas_market_calendars package:

pip install pandas_market_calendars

Basic Usage of Custom Holidays

Initially, let’s explore how to create a simple custom holiday calendar. Here, we’ll use the CustomBusinessDay object from Pandas:

import pandas as pd
from pandas.tseries.holiday import AbstractHolidayCalendar, nearest_workday, Holiday

class MyHolidays(AbstractHolidayCalendar):
    rules = [
        Holiday('New Year', month=1, day=1, observance=nearest_workday),
        Holiday('Christmas', month=12, day=25)
    ]

my_calendar = MyHolidays()

# Create a custom business day offset
bday = pd.offsets.CustomBusinessDay(calendar=my_calendar)

# Range of dates accounting for custom holidays
start_date = '2023-01-01'
end_date = '2023-12-31'
date_range = pd.date_range(start=start_date, end=end_date, freq=bday)

print(date_range)

This code snippet defines a simple holiday calendar including New Year’s Day and Christmas. Note the observance parameter allows for shifting holidays that fall on weekends to the nearest workday.

Incorporating International Holidays

Dealing with international data might require incorporating holidays from multiple countries. Pandas can handle this complexity via Holiday objects:

class GlobalHolidays(AbstractHolidayCalendar):
    rules = [
        Holiday('New Year', month=1, day=1, observance=nearest_workday),
        # Add international holidays
        Holiday('Canada Day', month=7, day=1, observance=nearest_workday, start_date=pd.Timestamp('2023-01-01')),
        Holiday('Bastille Day', month=7, day=14),
    ]

# Apply similar steps as before
bday = pd.offsets.CustomBusinessDay(calendar=GlobalHolidays())
date_range = pd.date_range(start='2023-01-01', end='2023-12-31', freq=bday)
print(date_range)

By extending our holiday calendar, this code sample illustrates handling holidays from different countries, reflecting a more global perspective.

Advanced Customization: Defining Work Weeks and Exceptions

More sophisticated scenarios might require defining custom work weeks or additional exceptions (e.g., half-days). The CustomBusinessDay object is flexible enough to accommodate such requirements:

from pandas.tseries.offsets import CustomBusinessDay

# Custom work week (Monday through Thursday)
custom_week = CustomBusinessDay(weekmask='Mon Tue Wed Thu')

# Add exceptions for specific dates
exceptions = pd.to_datetime(['2023-07-03', '2023-11-23'])
weekmask = 'Mon Tue Wed Thu Fri'

# Include the exceptions in the business day offset
bday = CustomBusinessDay(holidays=exceptions, weekmask=weekmask)

# Generate the date range
date_range = pd.date_range(start='2023-01-01', end='2023-12-31', freq=bday)
print(date_range)

This snippet details defining a work week excluding Fridays and accounting for specific exceptions, showcasing Pandas’ versatility in dealing with complex calendars.

Working with Financial Calendars

In financial applications, using the pandas_market_calendars library extends Pandas’ capabilities to incorporate exchange-specific holidays and hours:

import pandas_market_calendars as mcal

# Load the NYSE calendar
nyse = mcal.get_calendar('NYSE')

# Generate trading days range
trading_days = nyse.valid_days(start_date='2023-01-01', end_date='2023-12-31')
print(trading_days)

This approach simplifies integrating trading holidays and times directly into Pandas, facilitating precise time series modeling for financial datasets.

Conclusion

Specifying custom holidays with Pandas is crucial for accurate time series analysis, especially in domains like finance where business calendars vary significantly. By leveraging the CustomBusinessDay and pandas_market_calendars, among other Pandas features, one can tailor date ranges to match specific holiday schedules, ensuring datasets accurately reflect real-world working calendars.