Skip to content

Truncate datetime

Description

Divide the date/datetime range into buckets. Each date/datetime is mapped to the start of its bucket using the corresponding local datetime. Note that weekly buckets start on Monday. Ambiguous results are localised using the DST offset of the original timestamp - for example, truncating ‘2022-11-06 01:30:00 CST’ by ‘1h’ results in ‘2022-11-06 01:00:00 CST’, whereas truncating ‘2022-11-06 01:30:00 CDT’ by ‘1h’ results in ‘2022-11-06 01:00:00 CDT’.

Usage

<Expr>$dt$truncate(every)

Arguments

every Either an Expr or a string indicating a column name or a duration (see Details).

Details

The every and offset argument are created with the the following string 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
  • 1y \# 1 calendar year These strings can be combined:
    • 3d12h4m25s \# 3 days, 12 hours, 4 minutes, and 25 seconds

Value

A polars expression

Examples

library("polars")

df <- pl$select(
  datetime = pl$datetime_range(
    as.Date("2001-01-01"),
    as.Date("2001-01-02"),
    as.difftime("0:25:0")
  )
)
df$with_columns(truncated = pl$col("datetime")$dt$truncate("1h"))

#> shape: (58, 2)
#> ┌─────────────────────┬─────────────────────┐
#> │ datetime            ┆ truncated           │
#> │ ---                 ┆ ---                 │
#> │ datetime[μs]        ┆ datetime[μs]        │
#> ╞═════════════════════╪═════════════════════╡
#> │ 2001-01-01 00:00:00 ┆ 2001-01-01 00:00:00 │
#> │ 2001-01-01 00:25:00 ┆ 2001-01-01 00:00:00 │
#> │ 2001-01-01 00:50:00 ┆ 2001-01-01 00:00:00 │
#> │ 2001-01-01 01:15:00 ┆ 2001-01-01 01:00:00 │
#> │ 2001-01-01 01:40:00 ┆ 2001-01-01 01:00:00 │
#> │ …                   ┆ …                   │
#> │ 2001-01-01 22:05:00 ┆ 2001-01-01 22:00:00 │
#> │ 2001-01-01 22:30:00 ┆ 2001-01-01 22:00:00 │
#> │ 2001-01-01 22:55:00 ┆ 2001-01-01 22:00:00 │
#> │ 2001-01-01 23:20:00 ┆ 2001-01-01 23:00:00 │
#> │ 2001-01-01 23:45:00 ┆ 2001-01-01 23:00:00 │
#> └─────────────────────┴─────────────────────┘

df <- pl$select(
  datetime = pl$datetime_range(
    as.POSIXct("2001-01-01 00:00"),
    as.POSIXct("2001-01-01 01:00"),
    as.difftime("0:10:0")
  )
)
df$with_columns(truncated = pl$col("datetime")$dt$truncate("30m"))

#> shape: (7, 2)
#> ┌─────────────────────┬─────────────────────┐
#> │ datetime            ┆ truncated           │
#> │ ---                 ┆ ---                 │
#> │ datetime[ms]        ┆ datetime[ms]        │
#> ╞═════════════════════╪═════════════════════╡
#> │ 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:00: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 00:30:00 │
#> │ 2001-01-01 01:00:00 ┆ 2001-01-01 01:00:00 │
#> └─────────────────────┴─────────────────────┘