Skip to content

Replace time zone

Source code

Description

Cast time zone for a Series of type Datetime. This is different from $convert_time_zone() as it will also modify the underlying timestamp. Use to correct a wrong time zone annotation. This will change the corresponding global timepoint.

Usage

<Expr>$dt$replace_time_zone(
  time_zone,
  ...,
  ambiguous = "raise",
  non_existent = "raise"
)

Arguments

time_zone NULL or string time zone from base::OlsonNames()
… Ignored.
ambiguous Determine how to deal with ambiguous datetimes:
  • “raise” (default): throw an error
  • “earliest”: use the earliest datetime
  • “latest”: use the latest datetime
  • “null”: return a null value
non_existent Determine how to deal with non-existent datetimes:
  • “raise” (default): throw an error
  • “null”: return a null value

Value

Expr of i64

Examples

library("polars")

df1 = pl$DataFrame(
  london_timezone = pl$datetime_range(
    as.POSIXct("2020-03-01", tz = "UTC"),
    as.POSIXct("2020-07-01", tz = "UTC"),
    "1mo1s"
  )$dt$convert_time_zone("Europe/London")
)

df1$select(
  "london_timezone",
  London_to_Amsterdam = pl$col("london_timezone")$dt$replace_time_zone("Europe/Amsterdam")
)

#> shape: (4, 2)
#> ┌─────────────────────────────┬────────────────────────────────┐
#> │ london_timezone             ┆ London_to_Amsterdam            │
#> │ ---                         ┆ ---                            │
#> │ datetime[ms, Europe/London] ┆ datetime[ms, Europe/Amsterdam] │
#> ╞═════════════════════════════╪════════════════════════════════╡
#> │ 2020-03-01 00:00:00 GMT     ┆ 2020-03-01 00:00:00 CET        │
#> │ 2020-04-01 01:00:01 BST     ┆ 2020-04-01 01:00:01 CEST       │
#> │ 2020-05-01 01:00:02 BST     ┆ 2020-05-01 01:00:02 CEST       │
#> │ 2020-06-01 01:00:03 BST     ┆ 2020-06-01 01:00:03 CEST       │
#> └─────────────────────────────┴────────────────────────────────┘

# You can use `ambiguous` to deal with ambiguous datetimes:
dates = c(
  "2018-10-28 01:30",
  "2018-10-28 02:00",
  "2018-10-28 02:30",
  "2018-10-28 02:00"
)
df2 = pl$DataFrame(
  ts = as_polars_series(dates)$str$strptime(pl$Datetime("us")),
  ambiguous = c("earliest", "earliest", "latest", "latest")
)

df2$with_columns(
  ts_localized = pl$col("ts")$dt$replace_time_zone(
    "Europe/Brussels",
    ambiguous = pl$col("ambiguous")
  )
)

#> shape: (4, 3)
#> ┌─────────────────────┬───────────┬───────────────────────────────┐
#> │ ts                  ┆ ambiguous ┆ ts_localized                  │
#> │ ---                 ┆ ---       ┆ ---                           │
#> │ datetime[μs]        ┆ str       ┆ datetime[μs, Europe/Brussels] │
#> ╞═════════════════════╪═══════════╪═══════════════════════════════╡
#> │ 2018-10-28 01:30:00 ┆ earliest  ┆ 2018-10-28 01:30:00 CEST      │
#> │ 2018-10-28 02:00:00 ┆ earliest  ┆ 2018-10-28 02:00:00 CEST      │
#> │ 2018-10-28 02:30:00 ┆ latest    ┆ 2018-10-28 02:30:00 CET       │
#> │ 2018-10-28 02:00:00 ┆ latest    ┆ 2018-10-28 02:00:00 CET       │
#> └─────────────────────┴───────────┴───────────────────────────────┘