Python Pandas - How to perform ceil operation on the DateTimeIndex with microseconds frequency

To perform ceil operation on the DateTimeIndex with microseconds frequency, use the DateTimeIndex.ceil() method. The ceil operation rounds up datetime values to the next higher boundary. For microseconds frequency, use the freq parameter with value 'us'.

What is the Ceil Operation?

The ceil operation rounds datetime values upward to the nearest specified frequency boundary. When applied with microseconds frequency ('us'), it rounds up to the next microsecond.

Creating a DateTimeIndex

First, let's create a DateTimeIndex with nanosecond precision ?

import pandas as pd

# Create DatetimeIndex with period 5 and frequency as 40 seconds
# timezone is Australia/Adelaide
datetimeindex = pd.date_range('2021-10-18 07:20:32.261811624', periods=5,
                              tz='Australia/Adelaide', freq='40S')

print("DateTimeIndex...")
print(datetimeindex)
print("\nDateTimeIndex frequency...")
print(datetimeindex.freq)

DateTimeIndex...
DatetimeIndex(['2021-10-18 07:20:32.261811624+10:30',
               '2021-10-18 07:21:12.261811624+10:30',
               '2021-10-18 07:21:52.261811624+10:30',
               '2021-10-18 07:22:32.261811624+10:30',
               '2021-10-18 07:23:12.261811624+10:30'],
              dtype='datetime64[ns, Australia/Adelaide]', freq='40S')

DateTimeIndex frequency...
<40 * Seconds>

Performing Ceil Operation with Microseconds Frequency

Apply the ceil operation with microseconds frequency ('us') to round up to the next microsecond ?

import pandas as pd

# Create DatetimeIndex with nanosecond precision
datetimeindex = pd.date_range('2021-10-18 07:20:32.261811624', periods=5,
                              tz='Australia/Adelaide', freq='40S')

# Perform ceil operation with microseconds frequency
ceiled_index = datetimeindex.ceil(freq='us')

print("Original DateTimeIndex...")
print(datetimeindex)
print("\nAfter ceil operation with microseconds frequency...")
print(ceiled_index)

Original DateTimeIndex...
DatetimeIndex(['2021-10-18 07:20:32.261811624+10:30',
               '2021-10-18 07:21:12.261811624+10:30',
               '2021-10-18 07:21:52.261811624+10:30',
               '2021-10-18 07:22:32.261811624+10:30',
               '2021-10-18 07:23:12.261811624+10:30'],
              dtype='datetime64[ns, Australia/Adelaide]', freq='40S')

After ceil operation with microseconds frequency...
DatetimeIndex(['2021-10-18 07:20:32.261812+10:30',
               '2021-10-18 07:21:12.261812+10:30',
               '2021-10-18 07:21:52.261812+10:30',
               '2021-10-18 07:22:32.261812+10:30',
               '2021-10-18 07:23:12.261812+10:30'],
              dtype='datetime64[ns, Australia/Adelaide]', freq=None)

Key Points

• The original timestamps had nanosecond precision (.261811624)
• After ceil operation with 'us' frequency, they were rounded up to the next microsecond (.261812)
• The frequency attribute becomes None after the ceil operation
• Timezone information is preserved during the operation

Conclusion

The DateTimeIndex.ceil(freq='us') method rounds datetime values upward to the nearest microsecond boundary. This is useful when you need to standardize timestamps to microsecond precision while ensuring values are rounded up rather than down.