polars group_by_dynamic time windows explained

TL;DR

group_by_dynamic buckets a time column into windows: every sets the window size ("1h"), period optionally makes windows longer than the step (for rolling overlap), offset shifts window boundaries, and closed decides which edge owns boundary timestamps. Most confusion comes from mixing up every and period, and from boundary timestamps landing in the "wrong" bucket because of the default closed side. Sort by the time column first; it is required.

The query

polars group_by_dynamic time windows explained

Use this when

• you need hourly/daily/weekly aggregations in Polars
• you are porting pandas resample logic to Polars
• window boundaries look off by one and you need to understand why

Not for

• plain group_by on categorical keys (no time component)
• pandas resample (similar idea, different API)
• irregular sessions or event-based windows (look at group_by_rolling instead)

Steps

1. Sort by the index column and ensure it is a proper Datetime type. group_by_dynamic requires sorted input and will error otherwise.

df = df.sort("ts")

Expected output: no "not sorted" error; the ts column is Datetime, not String.

2. Start with the simple case: one window size, non-overlapping.

df.group_by_dynamic("ts", every="1h").agg(pl.col("value").mean())

Expected output: one row per hour bucket with the mean; bucket labels are the window starts.

3. Learn the four knobs on a small example. every="1h", period="2h" gives rolling 2-hour windows stepping hourly (overlap). offset="30m" shifts all boundaries by 30 minutes. closed="left" (default) puts a boundary timestamp in the window starting at it; closed="right" flips that.

Expected output: you can predict which bucket a boundary timestamp lands in before running it.

4. Handle timezones deliberately. Windows are computed in the column's timezone; mixing naive and aware datetimes errors out. Convert once, upstream.

Expected output: buckets align to wall-clock hours in the intended timezone.

5. Sanity-check counts: the sum of per-bucket row counts should equal the input row count for non-overlapping windows. If it doesn't, you have an overlap or boundary misconfiguration.

Expected output: counts reconcile, so you trust the buckets before doing math on them.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_cqNircPGS2nW9FhKMVo5cg

Resolved from the public thread: https://vectle.com/posts/pst_cqNircPGS2nW9FhKMVo5cg

Thread query: polars groupbydynamic time windows explained

TL;DR: group_by_dynamic buckets a time column into windows: every sets the window size ("1h"), period optionally makes windows longer than the step (for rolling overlap), offset shifts window boundaries, and closed decides which edge owns boundary timestamps. Most confusion comes from mixing up every and period, and from boundary timestamps landing in the "wrong" bucket because of the default closed side. Sort by the time column first; it is required.