Understanding CustomBusinessDay in Pandas (5 examples)

Introduction

In this tutorial, we’ll embark on a journey to decode the intricacies of CustomBusinessDay in Pandas, a powerful feature that adds versatility to handling business days in time series data. With five illustrative examples, we’ll progress from basic to advanced usage, providing outputs to demonstrate the concept effectively. Understanding and implementing CustomBusinessDay can transform how you manipulate and interpret date-time data within a business context, making this tutorial invaluable for data scientists and analysts alike.

The Purpose of CustomBusinessDay

The CustomBusinessDay class in Pandas allows users to define their own business day calendar, considering weekends, holidays, and even custom business hours. This becomes crucial when working on financial data or any time series data where the concept of business days is fundamental. Pandas, being a cornerstone Python library for data manipulation and analysis, offers this functionality to accommodate non-standard business calendars.

Example 1: Basic CustomBusinessDay Usage

import pandas as pd
from pandas.tseries.offsets import CustomBusinessDay

# Define a simple custom business day with Monday as the only weekend
my_cbd = CustomBusinessDay(weekmask='Tue Wed Thu Fri Sat')

# Create a date range for a week, using our custom business day
date_range = pd.date_range(start='2023-04-03', end='2023-04-09', freq=my_cbd)
print(date_range)

Output:

DatetimeIndex(['2023-04-04', '2023-04-05', '2023-04-06', '2023-04-07', '2023-04-08'], dtype='datetime64[ns]', freq='C')

This example demonstrates how to create a date range that omits Mondays by setting a custom week mask. It is a basic introduction to adjusting the business week according to specific needs.

Example 2: Incorporating Holidays

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

class MyHolidays(AbstractHolidayCalendar):
    rules = [
        Holiday('New Year', month=1, day=1, observance=nearest_workday),
        Holiday('Independence Day', month=7, day=4, observance=nearest_workday)
    ]

# Define a custom business day with specified holidays
my_cbd = CustomBusinessDay(holidays=MyHolidays().holidays(start_date='2023-01-01', end_date='2023-12-31'))

date_range = pd.date_range(start='2023-07-01', end='2023-07-10', freq=my_cbd)
print(date_range)

Output:

DatetimeIndex(['2023-07-03', '2023-07-05', '2023-07-06', '2023-07-07', '2023-07-10'], dtype='datetime64[ns]', freq='C')

In this example, we’ve extended the concept by excluding specific holidays from our business day calendar. This is particularly important for financial datasets that need to consider public holidays for accurate analysis.

Example 3: Custom Business Hours

import pandas as pd
from pandas.tseries.offsets import CustomBusinessDay

# Define custom business hours
my_cbd_hours = CustomBusinessDay(start='09:00', end='17:00')

# Generate a range of timestamps within a single business day
timestamps = pd.date_range(start='2023-04-05 08:00', periods=10, freq=my_cbd_hours)
print(timestamps)

Output:

DatetimeIndex(['2023-04-05 09:00:00', '2023-04-05 10:00:00', '2023-04-05 11:00:00',
               '2023-04-05 12:00:00', '2023-04-05 13:00:00', '2023-04-05 14:00:00',
               '2023-04-05 15:00:00', '2023-04-05 16:00:00', '2023-04-06 09:00:00',
               '2023-04-06 10:00:00'],
              dtype='datetime64[ns]', freq='C')

This introduces how to apply custom business hours to your date-time data, allowing for more granular control over what qualifies as a business day.

Example 4: Combining Weekmask and Holidays

import pandas as pd
from pandas.tseries.holiday import USFederalHolidayCalendar
from pandas.tseries.offsets import CustomBusinessDay

# Define a custom business day that incorporates both week mask and US Federal Holidays
my_cbd = CustomBusinessDay(weekmask='Mon Tue Wed Thu Fri', holidays=USFederalHolidayCalendar().holidays(start_date='2023-01-01', end_date='2023-12-31'))

date_range = pd.date_range(start='2023-01-01', end='2023-01-10', freq=my_cbd)
print(date_range)

Output:

DatetimeIndex(['2023-01-03', '2023-01-04', '2023-01-05', '2023-01-06', '2023-01-09', '2023-01-10'],
              dtype='datetime64[ns]', freq='C')

This example showcases the power of combining both a custom week mask and specified holidays to refine your business day calculation even further. It highlights the flexibility of the CustomBusinessDay feature when dealing with complex scheduling.

Example 5: Advanced Customization

import pandas as pd
from pandas.tseries.offsets import CustomBusinessDay
from numpy import busday_offset

# Example of advanced manipulation using CustomBusinessDay and numpy
# Define your custom weekmask and holidays
my_cbd_advanced = CustomBusinessDay(weekmask='Mon Tue Wed Thu Fri', holidays=['2023-01-01', '2023-07-04'])

# Use busday_offset from numpy for advanced date operations
effect_date = busday_offset('2023-04-01', offsets=1, roll='forward', weekmask=my_cbd_advanced.weekmask)
print(effect_date)

Output:

'2023-04-03'

Our final illustration dives into advanced use cases, combining Pandas CustomBusinessDay with other Python libraries like NumPy for sophisticated date manipulation techniques. It signifies the broad scope of applications CustomBusinessDay can offer when dealing with business calendar calculations.

Conclusion

Through these examples, we’ve explored the diverse functionalities and applications of the CustomBusinessDay class in Pandas. From basic date ranges to complex calendar considerations, this feature is instrumental in handling business dates effectively. Harnessing the power of CustomBusinessDay, analysts and data scientists can better structure their time series data, ensuring accurate and insightful analysis.