pandas.DatetimeIndex.ceil#

DatetimeIndex.ceil(freq, ambiguous='raise', nonexistent='raise')[source]#

Perform ceil operation on the data to the specified freq.

This method rounds each datetime value in the Series/Index up to the specified frequency (i.e., towards positive infinity).

Parameters:
freqstr or Offset

The frequency level to ceil the index to. Must be a fixed frequency like ‘s’ (second) not ‘ME’ (month end). See frequency aliases for a list of possible freq values.

ambiguous‘infer’, bool-ndarray, ‘NaT’, default ‘raise’

  • ‘infer’ will attempt to infer fall dst-transition hours based on order. Requires that the timestamps are monotonically increasing.

  • bool-ndarray where True signifies a DST time, False designates a non-DST time (note that this flag is only applicable for ambiguous times)

  • ‘NaT’ will return NaT where there are ambiguous times

  • ‘raise’ will raise a ValueError if there are ambiguous times.

nonexistent‘shift_forward’, ‘shift_backward’, ‘NaT’, timedelta, default ‘raise’

A nonexistent time does not exist in a particular timezone where clocks moved forward due to DST.

  • ‘shift_forward’ will shift the nonexistent time forward to the closest existing time

  • ‘shift_backward’ will shift the nonexistent time backward to the closest existing time

  • ‘NaT’ will return NaT where there are nonexistent times

  • timedelta objects will shift nonexistent times by the timedelta

  • ‘raise’ will raise a ValueError if there are nonexistent times.

Returns:
DatetimeIndex

Index with each value ceiled to the specified freq.

Raises:
ValueError if the freq cannot be converted.

See also

DatetimeIndex.round

Perform round operation on the data to the specified freq.

DatetimeIndex.floor

Perform floor operation on the data to the specified freq.

DatetimeIndex.snap

Snap time stamps to nearest occurring frequency.

Notes

If the timestamps have a timezone, ceiling will take place relative to the local (“wall”) time and re-localized to the same timezone. When ceiling near daylight savings time, use nonexistent and ambiguous to control the re-localization behavior.

Examples

>>> rng = pd.date_range("1/1/2018 11:59:00", periods=3, freq="min")
>>> rng
DatetimeIndex(['2018-01-01 11:59:00', '2018-01-01 12:00:00',
               '2018-01-01 12:01:00'],
              dtype='datetime64[us]', freq='min')
>>> rng.ceil("h")
DatetimeIndex(['2018-01-01 12:00:00', '2018-01-01 12:00:00',
               '2018-01-01 13:00:00'],
              dtype='datetime64[us]', freq=None)

When rounding near a daylight savings time transition, use ambiguous or nonexistent to control how the timestamp should be re-localized.

>>> rng_tz = pd.DatetimeIndex(["2021-10-31 01:30:00"], tz="Europe/Amsterdam")
>>> rng_tz.ceil("h", ambiguous=False)
DatetimeIndex(['2021-10-31 02:00:00+01:00'],
              dtype='datetime64[us, Europe/Amsterdam]', freq=None)
>>> rng_tz.ceil("h", ambiguous=True)
DatetimeIndex(['2021-10-31 02:00:00+02:00'],
              dtype='datetime64[us, Europe/Amsterdam]', freq=None)
On this page