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

To perform ceil operation on the DateTimeIndex with minutely frequency, use the DateTimeIndex.ceil() method. For minutely frequency, use the freq parameter with value 'T'.

What is ceil() Operation?

The ceil() operation rounds up datetime values to the next higher boundary of the specified frequency. For minute frequency, it rounds up to the next minute ?

Creating DateTimeIndex with Second Frequency

First, let's create a DateTimeIndex with second frequency that we'll round up to minutes ?

import pandas as pd

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

print("DateTimeIndex...")
print(datetimeindex)

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')

Performing Ceil Operation with Minute Frequency

Now let's apply the ceil operation to round up to the next minute boundary ?

import pandas as pd

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

print("Original DateTimeIndex...")
print(datetimeindex)

# Perform ceil operation with minute frequency ('T')
ceiled_index = datetimeindex.ceil(freq='T')
print("\nAfter ceil operation with minute 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 minute frequency...
DatetimeIndex(['2021-10-18 07:21:00+10:30', '2021-10-18 07:22:00+10:30',
               '2021-10-18 07:22:00+10:30', '2021-10-18 07:23:00+10:30',
               '2021-10-18 07:24:00+10:30'],
              dtype='datetime64[ns, Australia/Adelaide]', freq=None)

Complete Example

Here's a comprehensive example showing the original minutes and the ceil operation ?

import pandas as pd

# Create DatetimeIndex with period 5 and frequency as 40 seconds
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)

# Extract minutes from original DateTimeIndex
minutes = datetimeindex.minute
print("\nThe minute from DateTimeIndex...")
print(minutes)

# Perform ceil operation with minute frequency
print("\nPerforming ceil operation with minute frequency...")
print(datetimeindex.ceil(freq='T'))

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>

The minute from DateTimeIndex...
Int64Index([20, 21, 21, 22, 23], dtype='int64')

Performing ceil operation with minute frequency...
DatetimeIndex(['2021-10-18 07:21:00+10:30', '2021-10-18 07:22:00+10:30',
               '2021-10-18 07:22:00+10:30', '2021-10-18 07:23:00+10:30',
               '2021-10-18 07:24:00+10:30'],
              dtype='datetime64[ns, Australia/Adelaide]', freq=None)

Key Points

• Use freq='T' for minute frequency in the ceil operation
• The ceil operation rounds up to the next minute boundary
• Times already at minute boundaries remain unchanged
• The resulting DateTimeIndex loses its original frequency

Conclusion

The ceil() method with freq='T' effectively rounds up DateTimeIndex values to the next minute boundary. This is useful for time-based grouping and data alignment operations in time series analysis.