polars.Expr.dt.round

Expr.dt.round(every: str | timedelta, offset: str | timedelta | None = None) → Expr

Divide the date/datetime range into buckets.

Each date/datetime in the first half of the interval is mapped to the start of its bucket. Each date/datetime in the second half of the interval is mapped to the end of its bucket.

Parameters:

every

Every interval start and period length

offset

Offset the window

Returns:

Date/Datetime series

Warning

This functionality is currently experimental and may change without it being considered a breaking change.

Notes

The every and offset argument are created with the the following small string formatting language:

1ns # 1 nanosecond 1us # 1 microsecond 1ms # 1 millisecond 1s # 1 second 1m # 1 minute 1h # 1 hour 1d # 1 day 1w # 1 calendar week 1mo # 1 calendar month 1q # 1 calendar quarter 1y # 1 calendar year

eg: 3d12h4m25s # 3 days, 12 hours, 4 minutes, and 25 seconds

Suffix with “_saturating” to indicate that dates too large for their month should saturate at the largest date (e.g. 2022-02-29 -> 2022-02-28) instead of erroring.

Examples

>>> from datetime import timedelta, datetime
>>> start = datetime(2001, 1, 1)
>>> stop = datetime(2001, 1, 2)
>>> df = pl.date_range(
...     start, stop, timedelta(minutes=225), eager=True
... ).to_frame()
>>> df
shape: (7, 1)
┌─────────────────────┐
│ date                │
│ ---                 │
│ datetime[μs]        │
╞═════════════════════╡
│ 2001-01-01 00:00:00 │
│ 2001-01-01 03:45:00 │
│ 2001-01-01 07:30:00 │
│ 2001-01-01 11:15:00 │
│ 2001-01-01 15:00:00 │
│ 2001-01-01 18:45:00 │
│ 2001-01-01 22:30:00 │
└─────────────────────┘
>>> df.select(pl.col("date").dt.round("1h"))
shape: (7, 1)
┌─────────────────────┐
│ date                │
│ ---                 │
│ datetime[μs]        │
╞═════════════════════╡
│ 2001-01-01 00:00:00 │
│ 2001-01-01 04:00:00 │
│ 2001-01-01 08:00:00 │
│ 2001-01-01 11:00:00 │
│ 2001-01-01 15:00:00 │
│ 2001-01-01 19:00:00 │
│ 2001-01-01 23:00:00 │
└─────────────────────┘
>>> df.select(pl.col("date").dt.round("1h")).frame_equal(
...     df.select(pl.col("date").dt.round(timedelta(hours=1)))
... )
True

>>> start = datetime(2001, 1, 1)
>>> stop = datetime(2001, 1, 1, 1)
>>> df = pl.date_range(start, stop, "10m", eager=True).to_frame()
>>> df.select(["date", pl.col("date").dt.round("30m").alias("round")])
shape: (7, 2)
┌─────────────────────┬─────────────────────┐
│ date                ┆ round               │
│ ---                 ┆ ---                 │
│ datetime[μs]        ┆ datetime[μs]        │
╞═════════════════════╪═════════════════════╡
│ 2001-01-01 00:00:00 ┆ 2001-01-01 00:00:00 │
│ 2001-01-01 00:10:00 ┆ 2001-01-01 00:00:00 │
│ 2001-01-01 00:20:00 ┆ 2001-01-01 00:30:00 │
│ 2001-01-01 00:30:00 ┆ 2001-01-01 00:30:00 │
│ 2001-01-01 00:40:00 ┆ 2001-01-01 00:30:00 │
│ 2001-01-01 00:50:00 ┆ 2001-01-01 01:00:00 │
│ 2001-01-01 01:00:00 ┆ 2001-01-01 01:00:00 │
└─────────────────────┴─────────────────────┘