pandas.Timestamp.round — pandas 3.0.0.dev0+2100.gf496acffcc documentation (original) (raw)
Timestamp.round(freq, ambiguous='raise', nonexistent='raise')#
Round the Timestamp to the specified resolution.
This method rounds the given Timestamp down to a specified frequency level. It is particularly useful in data analysis to normalize timestamps to regular frequency intervals. For instance, rounding to the nearest minute, hour, or day can help in time series comparisons or resampling operations.
Parameters:
freqstr
Frequency string indicating the rounding resolution.
ambiguousbool or {‘raise’, ‘NaT’}, default ‘raise’
The behavior is as follows:
- bool contains flags to determine if time is dst or not (note that this flag is only applicable for ambiguous fall dst dates).
- ‘NaT’ will return NaT for an ambiguous time.
- ‘raise’ will raise a ValueError for an ambiguous time.
nonexistent{‘raise’, ‘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:
a new Timestamp rounded to the given resolution of freq
Raises:
ValueError if the freq cannot be converted
See also
datetime.round
Similar behavior in native Python datetime module.
Round the Timestamp downward to the nearest multiple of the specified frequency.
Round the Timestamp upward to the nearest multiple of the specified frequency.
Notes
If the Timestamp has 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
Create a timestamp object:
ts = pd.Timestamp('2020-03-14T15:32:52.192548651')
A timestamp can be rounded using multiple frequency units:
ts.round(freq='h') # hour Timestamp('2020-03-14 16:00:00')
ts.round(freq='min') # minute Timestamp('2020-03-14 15:33:00')
ts.round(freq='s') # seconds Timestamp('2020-03-14 15:32:52')
ts.round(freq='ms') # milliseconds Timestamp('2020-03-14 15:32:52.193000')
freq can also be a multiple of a single unit, like ‘5min’ (i.e. 5 minutes):
ts.round(freq='5min') Timestamp('2020-03-14 15:35:00')
or a combination of multiple units, like ‘1h30min’ (i.e. 1 hour and 30 minutes):
ts.round(freq='1h30min') Timestamp('2020-03-14 15:00:00')
Analogous for pd.NaT:
When rounding near a daylight savings time transition, use ambiguous ornonexistent to control how the timestamp should be re-localized.
ts_tz = pd.Timestamp("2021-10-31 01:30:00").tz_localize("Europe/Amsterdam")
ts_tz.round("h", ambiguous=False) Timestamp('2021-10-31 02:00:00+0100', tz='Europe/Amsterdam')
ts_tz.round("h", ambiguous=True) Timestamp('2021-10-31 02:00:00+0200', tz='Europe/Amsterdam')