Skip to main content
`Ctrl`+`K`

# pandas.DatetimeIndex.round

DatetimeIndex.round(freq, ambiguous='raise', nonexistent='raise')

  Perform round operation on the data to the specified freq.

  This method rounds each datetime value in the Series/Index to the nearest specified frequency using standard rounding rules (round half to even).

  Parameters:
    freq str or Offset

      The frequency level to round 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’

      Only relevant for DatetimeIndex:

      - ‘infer’ will attempt to infer fall dst-transition hours based on order

      - 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, TimedeltaIndex, or Series

      Index of the same type for a DatetimeIndex or TimedeltaIndex, or a Series with the same index for a Series.

  Raises:
    ValueError if the freq cannot be converted.

  See also

  `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, rounding will take place relative to the local (“wall”) time and re-localized to the same timezone. When rounding near daylight savings time, use `nonexistent` and `ambiguous` to control the re-localization behavior.

  Examples

  DatetimeIndex

      >>> 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.round('h')
      DatetimeIndex(['2018-01-01 12:00:00', '2018-01-01 12:00:00',
                     '2018-01-01 12:00:00'],
                    dtype='datetime64[us]', freq=None)

  Series

      >>> pd.Series(rng).dt.round("h")
      0   2018-01-01 12:00:00
      1   2018-01-01 12:00:00
      2   2018-01-01 12:00:00
      dtype: datetime64[us]

  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 03:30:00"], tz="Europe/Amsterdam")

      >>> rng_tz.floor("2h", ambiguous=False)
      DatetimeIndex(['2021-10-31 02:00:00+01:00'],
                    dtype='datetime64[us, Europe/Amsterdam]', freq=None)

      >>> rng_tz.floor("2h", ambiguous=True)
      DatetimeIndex(['2021-10-31 02:00:00+02:00'],
                    dtype='datetime64[us, Europe/Amsterdam]', freq=None)