Sling Academy
Home/Pandas/Pandas Time Series: How to specify custom holidays

Pandas Time Series: How to specify custom holidays

Last updated: February 19, 2024

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.

Next Article: Understanding Business Hours in Pandas Time Series

Previous Article: Pandas Time Series: Handle Daylights Saving Time (DST) Transitions

Series: Pandas Series: From Basic to Advanced

Pandas

You May Also Like

  • How to Use Pandas Profiling for Data Analysis (4 examples)
  • How to Handle Large Datasets with Pandas and Dask (4 examples)
  • Pandas – Using DataFrame.pivot() method (3 examples)
  • Pandas: How to ‘FULL JOIN’ 2 DataFrames (3 examples)
  • Pandas: Select columns whose names start/end with a specific string (4 examples)
  • 3 ways to turn off future warnings in Pandas
  • How to Integrate Pandas with Apache Spark
  • How to Use Pandas for Web Scraping and Saving Data (2 examples)
  • How to Clean and Preprocess Text Data with Pandas (3 examples)
  • Pandas – Using Series.replace() method (3 examples)
  • Pandas json_normalize() function: Explained with examples
  • Pandas: Reading CSV and Excel files from AWS S3 (4 examples)
  • Using pandas.Series.rank() method (4 examples)
  • Pandas: Dropping columns whose names contain a specific string (4 examples)
  • Pandas: How to print a DataFrame without index (3 ways)
  • Fixing Pandas NameError: name ‘df’ is not defined
  • Pandas – Using DataFrame idxmax() and idxmin() methods (4 examples)
  • Pandas FutureWarning: ‘M’ is deprecated and will be removed in a future version, please use ‘ME’ instead
  • Pandas: Checking equality of 2 DataFrames (element-wise)