Create a POSIXct date sequence — dateSequence • MazamaCoreUtils

Create a sequence of local-midnight POSIXct datetimes in a specified timezone.

dateSequence(
  startdate = NULL,
  enddate = NULL,
  timezone = NULL,
  ceilingEnd = FALSE
)

Arguments

startdate: Desired start datetime.
enddate: Desired end datetime.
timezone: Olson timezone used to interpret incoming dates.
ceilingEnd: Logical specifying whether to include the end of the final day.

Value

A vector of POSIXct datetimes at local midnight.

Details

The returned sequence begins at midnight local time on startdate and ends at midnight local time on enddate, i.e. the beginning of enddate.

The ceilingEnd argument addresses ambiguity in date ranges such as "August 1-8". With ceilingEnd = FALSE (default), the sequence ends at the beginning of August 8. With ceilingEnd = TRUE, the sequence includes the entirety of August 8, ending at the midnight that begins August 9.

Input dates are parsed with parseDatetime() using the specified timezone. Any hour-minute-second information is removed after parsing.

Note

This function preserves local clock-time midnight boundaries across daylight savings transitions. This differs from seq.Date(..., by = "day"), which advances by fixed 24-hour intervals and can drift away from midnight local time during daylight savings changes.

POSIXct inputs

When startdate or enddate are already POSIXct values, they are first converted to timezone with lubridate::with_tz() without changing the represented instant in time. They are then floored to local midnight.

Examples

dateSequence(
  "2019-11-01",
  "2019-11-08",
  timezone = "America/Los_Angeles"
)
#> [1] "2019-11-01 PDT" "2019-11-02 PDT" "2019-11-03 PDT" "2019-11-04 PST"
#> [5] "2019-11-05 PST" "2019-11-06 PST" "2019-11-07 PST" "2019-11-08 PST"

dateSequence(
  "2019-11-01",
  "2019-11-07",
  timezone = "America/Los_Angeles",
  ceilingEnd = TRUE
)
#> [1] "2019-11-01 PDT" "2019-11-02 PDT" "2019-11-03 PDT" "2019-11-04 PST"
#> [5] "2019-11-05 PST" "2019-11-06 PST" "2019-11-07 PST" "2019-11-08 PST"

# Observe daylight savings handling
datetime <- dateSequence(
  "2019-11-01",
  "2019-11-08",
  timezone = "America/Los_Angeles"
)

datetime
#> [1] "2019-11-01 PDT" "2019-11-02 PDT" "2019-11-03 PDT" "2019-11-04 PST"
#> [5] "2019-11-05 PST" "2019-11-06 PST" "2019-11-07 PST" "2019-11-08 PST"
lubridate::with_tz(datetime, "UTC")
#> [1] "2019-11-01 07:00:00 UTC" "2019-11-02 07:00:00 UTC"
#> [3] "2019-11-03 07:00:00 UTC" "2019-11-04 08:00:00 UTC"
#> [5] "2019-11-05 08:00:00 UTC" "2019-11-06 08:00:00 UTC"
#> [7] "2019-11-07 08:00:00 UTC" "2019-11-08 08:00:00 UTC"

# POSIXct inputs preserve the represented instant before flooring
jst <- dateSequence(
  20190307,
  20190315,
  timezone = "Asia/Tokyo"
)

jst
#> [1] "2019-03-07 JST" "2019-03-08 JST" "2019-03-09 JST" "2019-03-10 JST"
#> [5] "2019-03-11 JST" "2019-03-12 JST" "2019-03-13 JST" "2019-03-14 JST"
#> [9] "2019-03-15 JST"

dateSequence(
  jst[1],
  jst[7],
  timezone = "UTC"
)
#> [1] "2019-03-06 UTC" "2019-03-07 UTC" "2019-03-08 UTC" "2019-03-09 UTC"
#> [5] "2019-03-10 UTC" "2019-03-11 UTC" "2019-03-12 UTC"