Python Pandas - Perform ceil operation on the TimeDeltaIndex object with hourly frequency

The TimeDeltaIndex.ceil() method performs a ceiling operation on TimeDelta values, rounding them up to the nearest specified frequency. For hourly frequency, use the freq='H' parameter.

Syntax

TimeDeltaIndex.ceil(freq)

Parameters

freq: The frequency level to round up to. Use 'H' for hourly frequency.

Creating a TimeDeltaIndex Object

First, let's create a TimeDeltaIndex object with various time delta values ?

import pandas as pd

# Create a TimeDeltaIndex object with timedelta-like data
td_index = pd.TimedeltaIndex(data=[
    '4 day 8h 20min 35us 45ns', 
    '+17:42:19.999999',
    '9 day 3h 08:16:02.000055', 
    '+22:35:25.000075'
])

print("Original TimedeltaIndex:")
print(td_index)

Original TimedeltaIndex:
TimedeltaIndex(['4 days 08:20:00.000035045', '0 days 17:42:19.999999',
                '9 days 11:16:02.000055', '0 days 22:35:25.000075'],
               dtype='timedelta64[ns]', freq=None)

Performing Ceil Operation with Hourly Frequency

The ceil operation rounds up each TimeDelta to the nearest hour boundary ?

import pandas as pd

td_index = pd.TimedeltaIndex(data=[
    '4 day 8h 20min 35us 45ns', 
    '+17:42:19.999999',
    '9 day 3h 08:16:02.000055', 
    '+22:35:25.000075'
])

# Perform ceil operation with hourly frequency
ceil_result = td_index.ceil(freq='H')

print("After ceil operation with hourly frequency:")
print(ceil_result)

After ceil operation with hourly frequency:
TimedeltaIndex(['4 days 09:00:00', '0 days 18:00:00', '9 days 12:00:00',
                '0 days 23:00:00'],
               dtype='timedelta64[ns]', freq=None)

How It Works

The ceil operation rounds up to the next hour boundary:

• '4 days 08:20:00' ? '4 days 09:00:00' (rounded up to next hour)
• '17:42:19' ? '18:00:00' (rounded up to next hour)
• '9 days 11:16:02' ? '9 days 12:00:00' (rounded up to next hour)
• '22:35:25' ? '23:00:00' (rounded up to next hour)

Complete Example with Components Display

import pandas as pd

# Create TimeDeltaIndex
td_index = pd.TimedeltaIndex(data=[
    '4 day 8h 20min 35us 45ns', 
    '+17:42:19.999999',
    '9 day 3h 08:16:02.000055', 
    '+22:35:25.000075'
])

print("Original TimedeltaIndex:")
print(td_index)

print("\nComponents breakdown:")
print(td_index.components)

print("\nAfter ceil operation with hourly frequency:")
print(td_index.ceil(freq='H'))

Original TimedeltaIndex:
TimedeltaIndex(['4 days 08:20:00.000035045', '0 days 17:42:19.999999',
                '9 days 11:16:02.000055', '0 days 22:35:25.000075'],
               dtype='timedelta64[ns]', freq=None)

Components breakdown:
   days  hours  minutes  seconds  milliseconds  microseconds  nanoseconds
0     4      8       20        0             0            35           45
1     0     17       42       19           999           999            0
2     9     11       16        2             0            55            0
3     0     22       35       25             0            75            0

After ceil operation with hourly frequency:
TimedeltaIndex(['4 days 09:00:00', '0 days 18:00:00', '9 days 12:00:00',
                '0 days 23:00:00'],
               dtype='timedelta64[ns]', freq=None)

Conclusion

Use TimeDeltaIndex.ceil(freq='H') to round TimeDelta values up to the nearest hour boundary. This is useful for data aggregation and time-based analysis where you need consistent hourly intervals.