Python Pandas CustomBusinessHour - Check if the given timestamp is on offset or not

To check if a given timestamp is on offset or not, use the CustomBusinessHour.is_on_offset() method in Pandas. This method returns True if the timestamp falls within the custom business hours, and False otherwise.

What is CustomBusinessHour?

CustomBusinessHour is a DateOffset subclass that allows you to define custom business hours with specific start and end times. The is_on_offset() method checks whether a given timestamp falls within these defined business hours.

Syntax

CustomBusinessHour.is_on_offset(timestamp)

Example

Let's create a CustomBusinessHour offset and check if different timestamps are within the business hours ?

import pandas as pd

# Set the timestamp object in Pandas
timestamp = pd.Timestamp('2021-11-14 05:20:30')

# Display the Timestamp
print("Timestamp...\n", timestamp)

# Create the CustomBusinessHour Offset
# CustomBusinessHour is the DateOffset subclass
# Here, "start" is the start time of your custom business hour in 24h format.
# The "end" is the end time of your custom business hour in 24h format.
cbhOffset = pd.tseries.offsets.CustomBusinessHour(start="09:30", end="18:30")

# Display the CustomBusinessHour Offset
print("\nCustomBusinessHour Offset...\n", cbhOffset)

# Add the offset to the Timestamp and display the Updated Timestamp
print("\nUpdated Timestamp...\n", timestamp + cbhOffset)

# Check if the given timestamp is on offset or not
offset = cbhOffset.is_on_offset(pd.Timestamp('2021-11-20 05:20:30'))

# Display the result
print("\nCheck if the given timestamp is on offset or not...\n", offset)

Timestamp...
 2021-11-14 05:20:30

CustomBusinessHour Offset...
 <CustomBusinessHour: CBH=09:30-18:30>

Updated Timestamp...
 2021-11-15 10:30:00

Check if the given timestamp is on offset or not...
 False

Testing Different Timestamps

Let's test multiple timestamps to better understand how is_on_offset() works ?

import pandas as pd

# Create CustomBusinessHour offset (9:30 AM to 6:30 PM)
cbh = pd.tseries.offsets.CustomBusinessHour(start="09:30", end="18:30")

# Test different timestamps
timestamps = [
    pd.Timestamp('2021-11-15 10:00:00'),  # Monday 10:00 AM
    pd.Timestamp('2021-11-15 08:00:00'),  # Monday 8:00 AM (before hours)
    pd.Timestamp('2021-11-15 19:00:00'),  # Monday 7:00 PM (after hours)
    pd.Timestamp('2021-11-13 12:00:00'),  # Saturday 12:00 PM (weekend)
]

for ts in timestamps:
    result = cbh.is_on_offset(ts)
    print(f"{ts.strftime('%A %Y-%m-%d %H:%M:%S')}: {result}")

Monday 2021-11-15 10:00:00: True
Monday 2021-11-15 08:00:00: False
Monday 2021-11-15 19:00:00: False
Saturday 2021-11-13 12:00:00: False

Key Points

• is_on_offset() returns True only if the timestamp is within business hours on a business day
• Weekend dates always return False regardless of time
• Times before start time or after end time return False
• The method considers both the day of week and the time of day

Conclusion

The CustomBusinessHour.is_on_offset() method is useful for validating whether timestamps fall within custom business hours. It returns True only when the timestamp is both on a business day and within the specified time range.