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

To perform ceil operation on the DateTimeIndex with hourly frequency, use the DateTimeIndex.ceil() method. The ceil() operation rounds timestamps up to the nearest specified frequency boundary.

What is ceil() Operation?

The ceil() method performs a ceiling operation, which rounds datetime values up to the nearest boundary of the specified frequency. For hourly frequency, use freq='H' parameter.

Creating a DateTimeIndex

First, let's create a DateTimeIndex with timestamps that have minutes and seconds ?

import pandas as pd

# Create DateTimeIndex with period 5 and frequency as 20 minutes
datetimeindex = pd.date_range('2021-09-29 07:20:32.261811624', periods=5,
                            tz='Australia/Adelaide', freq='20min')

print("Original DateTimeIndex:")
print(datetimeindex)
print(f"\nFrequency: {datetimeindex.freq}")

Original DateTimeIndex:
DatetimeIndex(['2021-09-29 07:20:32.261811624+09:30',
               '2021-09-29 07:40:32.261811624+09:30',
               '2021-09-29 08:00:32.261811624+09:30',
               '2021-09-29 08:20:32.261811624+09:30',
               '2021-09-29 08:40:32.261811624+09:30'],
              dtype='datetime64[ns, Australia/Adelaide]', freq='20T')

Frequency: <20 * Minutes>

Performing Ceil Operation with Hourly Frequency

Now let's apply the ceil() operation to round up all timestamps to the nearest hour ?

import pandas as pd

# Create DateTimeIndex
datetimeindex = pd.date_range('2021-09-29 07:20:32.261811624', periods=5,
                            tz='Australia/Adelaide', freq='20min')

# Perform ceil operation with hourly frequency
result = datetimeindex.ceil(freq='H')

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

After ceil operation with hourly frequency:
DatetimeIndex(['2021-09-29 08:00:00+09:30', '2021-09-29 08:00:00+09:30',
               '2021-09-29 08:00:00+09:30', '2021-09-29 09:00:00+09:30',
               '2021-09-29 09:00:00+09:30'],
              dtype='datetime64[ns, Australia/Adelaide]', freq=None)

Complete Example

Here's the complete example showing the before and after comparison ?

import pandas as pd

# Create DateTimeIndex with period 5 and frequency as 20 minutes
datetimeindex = pd.date_range('2021-09-29 07:20:32.261811624', periods=5,
                            tz='Australia/Adelaide', freq='20min')

# Display original DateTimeIndex
print("DateTimeIndex...")
print(datetimeindex)

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

# Perform ceil operation on DateTimeIndex with hourly frequency
print("\nPerforming ceil operation with hourly frequency...")
print(datetimeindex.ceil(freq='H'))

DateTimeIndex...
DatetimeIndex(['2021-09-29 07:20:32.261811624+09:30',
               '2021-09-29 07:40:32.261811624+09:30',
               '2021-09-29 08:00:32.261811624+09:30',
               '2021-09-29 08:20:32.261811624+09:30',
               '2021-09-29 08:40:32.261811624+09:30'],
              dtype='datetime64[ns, Australia/Adelaide]', freq='20T')

DateTimeIndex frequency...
<20 * Minutes>

Performing ceil operation with hourly frequency...
DatetimeIndex(['2021-09-29 08:00:00+09:30', '2021-09-29 08:00:00+09:30',
               '2021-09-29 08:00:00+09:30', '2021-09-29 09:00:00+09:30',
               '2021-09-29 09:00:00+09:30'],
              dtype='datetime64[ns, Australia/Adelaide]', freq=None)

Key Points

• The ceil() method rounds timestamps up to the nearest boundary
• Use freq='H' for hourly frequency boundaries
• All fractional parts (minutes, seconds, microseconds) are removed
• The resulting DateTimeIndex loses its original frequency information

Conclusion

The DateTimeIndex.ceil() method with freq='H' effectively rounds all datetime values up to the nearest hour boundary. This is useful for grouping timestamps into hourly intervals for time-series analysis.