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.

Parameters

freq : str

Frequency string indicating the rounding resolution.

ambiguous : bool 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 an AmbiguousTimeError 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 an NonExistentTimeError if there are nonexistent times.

Raises

ValueError if the freq cannot be converted

Returns

a new Timestamp rounded to the given resolution of `freq`

Round the Timestamp to the specified resolution.

Examples

Create a timestamp object:

This example is valid syntax, but we were not able to check execution

>>> ts = pd.Timestamp('2020-03-14T15:32:52.192548651')

A timestamp can be rounded using multiple frequency units:

This example is valid syntax, but we were not able to check execution

>>> ts.round(freq='H') # hour
Timestamp('2020-03-14 16:00:00')

This example is valid syntax, but we were not able to check execution

>>> ts.round(freq='T') # minute
Timestamp('2020-03-14 15:33:00')

This example is valid syntax, but we were not able to check execution

>>> ts.round(freq='S') # seconds
Timestamp('2020-03-14 15:32:52')

This example is valid syntax, but we were not able to check execution

>>> ts.round(freq='L') # milliseconds
Timestamp('2020-03-14 15:32:52.193000')

freq can also be a multiple of a single unit, like '5T' (i.e. 5 minutes):

This example is valid syntax, but we were not able to check execution

>>> ts.round(freq='5T')
Timestamp('2020-03-14 15:35:00')

or a combination of multiple units, like '1H30T' (i.e. 1 hour and 30 minutes):

This example is valid syntax, but we were not able to check execution

>>> ts.round(freq='1H30T')
Timestamp('2020-03-14 15:00:00')

Analogous for pd.NaT :

This example is valid syntax, but we were not able to check execution

>>> pd.NaT.round()
NaT

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

This example is valid syntax, but we were not able to check execution

>>> ts_tz = pd.Timestamp("2021-10-31 01:30:00").tz_localize("Europe/Amsterdam")

This example is valid syntax, but we were not able to check execution

>>> ts_tz.round("H", ambiguous=False)
Timestamp('2021-10-31 02:00:00+0100', tz='Europe/Amsterdam')

This example is valid syntax, but we were not able to check execution

>>> ts_tz.round("H", ambiguous=True)
Timestamp('2021-10-31 02:00:00+0200', tz='Europe/Amsterdam')

See :

Local connectivity graph

Hover to see nodes names; edges to Self not shown, Caped at 50 nodes.

Using a canvas is more power efficient and can get hundred of nodes ; but does not allow hyperlinks; , arrows or text (beyond on hover)

SVG is more flexible but power hungry; and does not scale well to 50 + nodes.

All aboves nodes referred to, (or are referred from) current nodes; Edges from Self to other have been omitted (or all nodes would be connected to the central node "self" which is not useful). Nodes are colored by the library they belong to, and scaled with the number of references pointing them

---

File: None#None
type: <class 'cython_function_or_method'>
Commit: