Python Pandas CustomBusinessHour - Roll provided date forward to next offset only if not on offset

The rollforward() method in Pandas CustomBusinessHour moves a date forward to the next valid business hour only if the date is not already on a valid offset. If the date is already aligned with the custom business hour schedule, it remains unchanged.

Understanding CustomBusinessHour

CustomBusinessHour allows you to define custom business days and hours. It's useful when your business operates on non-standard schedules ?

import pandas as pd

# Create a CustomBusinessHour offset
# n=5 means 5 business hours, weekmask defines valid days
cbh_offset = pd.tseries.offsets.CustomBusinessHour(n=5, weekmask='Mon Tue Wed Fri')
print("CustomBusinessHour Offset:")
print(cbh_offset)

CustomBusinessHour Offset:
<5 * CustomBusinessHours: CBH=09:00-17:00>

Using rollforward() Method

The rollforward() method moves a timestamp to the next valid business hour if it's not already on one ?

import pandas as pd

# Create CustomBusinessHour offset (Mon, Tue, Wed, Fri only)
cbh_offset = pd.tseries.offsets.CustomBusinessHour(n=5, weekmask='Mon Tue Wed Fri')

# Test with a timestamp on Thursday (not a business day)
timestamp1 = pd.Timestamp('2021-12-30 08:35:10')  # Thursday
rolled1 = cbh_offset.rollforward(timestamp1)

print("Original timestamp (Thursday):", timestamp1)
print("Rolled forward:", rolled1)
print()

# Test with a timestamp already on a business day during business hours
timestamp2 = pd.Timestamp('2021-12-20 10:00:00')  # Monday at 10 AM
rolled2 = cbh_offset.rollforward(timestamp2)

print("Original timestamp (Monday 10 AM):", timestamp2)
print("Rolled forward:", rolled2)

Original timestamp (Thursday): 2021-12-30 08:35:10
Rolled forward: 2021-12-31 09:00:00

Original timestamp (Monday 10 AM): 2021-12-20 10:00:00
Rolled forward: 2021-12-20 10:00:00

Complete Example

Here's a comprehensive example showing different scenarios ?

import pandas as pd

# Set the timestamp object
timestamp = pd.Timestamp('2021-12-20 08:35:10')
print("Original Timestamp:", timestamp)

# Create CustomBusinessHour Offset (Mon, Tue, Wed, Fri - skips Thursday)
cbh_offset = pd.tseries.offsets.CustomBusinessHour(n=5, weekmask='Mon Tue Wed Fri')
print("CustomBusinessHour Offset:", cbh_offset)

# Add the offset to the timestamp
updated_timestamp = timestamp + cbh_offset
print("Updated Timestamp (original + 5 business hours):", updated_timestamp)

# Roll forward a Thursday timestamp (not a business day)
thursday_timestamp = pd.Timestamp('2021-12-30 08:35:10')
roll_result = cbh_offset.rollforward(thursday_timestamp)
print("Roll forward from Thursday:", roll_result)

Original Timestamp: 2021-12-20 08:35:10
CustomBusinessHour Offset: <5 * CustomBusinessHours: CBH=09:00-17:00>
Updated Timestamp (original + 5 business hours): 2021-12-20 14:00:00
Roll forward from Thursday: 2021-12-31 09:00:00

Key Points

• rollforward() only moves dates that are not on valid business hours
• Dates already on valid business hours remain unchanged
• The default business hours are 9:00 AM to 5:00 PM
• You can customize both business days and business hours

Conclusion

The rollforward() method is essential for ensuring timestamps align with custom business schedules. It only moves timestamps forward when they fall outside defined business hours, making it perfect for financial and business applications.