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

To perform ceil operation on the DateTimeIndex with specified frequency, use the DateTimeIndex.ceil() method. The freq parameter specifies the frequency to which each timestamp should be rounded up.

What is Ceil Operation?

The ceil() method rounds timestamps up to the nearest specified frequency unit. For example, if you ceil to microseconds ('us'), any nanosecond precision will be rounded up to the next microsecond.

Syntax

DateTimeIndex.ceil(freq)

Parameters

• freq: String representing the frequency to ceil to (e.g., 'S' for seconds, 'us' for microseconds, 'H' for hours)

Example

Let's create a DateTimeIndex and perform ceil operation ?

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

# Display DateTimeIndex
print("DateTimeIndex...\n", datetimeindex)

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

# Ceil operation on DateTimeIndex with microsecond frequency
print("\nPerforming ceil operation...\n",
      datetimeindex.ceil(freq='us'))

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

Common Frequency Aliases

Here are commonly used frequency aliases for the ceil() method ?

import pandas as pd

# Create a timestamp with high precision
timestamp = pd.Timestamp('2021-10-18 07:20:32.123456789')
dt_index = pd.DatetimeIndex([timestamp])

print("Original timestamp:", timestamp)
print("Ceil to seconds:", dt_index.ceil('S')[0])
print("Ceil to minutes:", dt_index.ceil('T')[0])
print("Ceil to hours:", dt_index.ceil('H')[0])
print("Ceil to days:", dt_index.ceil('D')[0])

Original timestamp: 2021-10-18 07:20:32.123456789
Ceil to seconds: 2021-10-18 07:20:33
Ceil to minutes: 2021-10-18 07:21:00
Ceil to hours: 2021-10-18 08:00:00
Ceil to days: 2021-10-19 00:00:00

Key Points

• The ceil() method always rounds up to the next unit
• After ceiling, the original frequency information is lost (freq=None)
• Timezone information is preserved in the result
• Use frequency aliases like 'S', 'T', 'H', 'D' for different time units

Conclusion

The DateTimeIndex.ceil() method provides an efficient way to round timestamps up to a specified frequency. This is useful for time series analysis when you need to align data to specific time boundaries.