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

The TimeDeltaIndex.ceil() method rounds up time delta values to the nearest specified frequency. To perform ceil operation with seconds frequency, use freq='S' parameter.

Syntax

TimeDeltaIndex.ceil(freq)

Parameters

freq: A string representing the frequency to ceil to. Use 'S' for seconds 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
tdIndex = 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("TimedeltaIndex...")
print(tdIndex)

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)

Examining Components

Let's examine the components to see the sub-second precision ?

import pandas as pd

tdIndex = 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("Components of TimeDeltas:")
print(tdIndex.components)

Components of TimeDeltas:
   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

Performing Ceil Operation with Seconds Frequency

Now, let's perform the ceil operation with seconds frequency using freq='S' ?

import pandas as pd

tdIndex = 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(tdIndex)

print("\nAfter ceil operation with seconds frequency:")
result = tdIndex.ceil(freq='S')
print(result)

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)

After ceil operation with seconds frequency:
TimedeltaIndex(['4 days 08:20:01', '0 days 17:42:20', '9 days 11:16:03',
                '0 days 22:35:26'],
               dtype='timedelta64[ns]', freq=None)

How It Works

The ceil operation rounds up any sub-second values to the next full second:

• 4 days 08:20:00.000035045 ? 4 days 08:20:01 (rounded up due to microseconds and nanoseconds)
• 0 days 17:42:19.999999 ? 0 days 17:42:20 (rounded up due to microseconds)
• 9 days 11:16:02.000055 ? 9 days 11:16:03 (rounded up due to microseconds)
• 0 days 22:35:25.000075 ? 0 days 22:35:26 (rounded up due to microseconds)

Conclusion

The TimeDeltaIndex.ceil() method with freq='S' efficiently rounds up time delta values to the nearest second. Any sub-second precision (microseconds, nanoseconds) will cause the value to be rounded up to the next full second.