R: Rounding: date-time

posixt-rounding {clock} | R Documentation

## Rounding: date-time

### Description

These are POSIXct/POSIXlt methods for the rounding generics.

- `date_floor()` rounds a date-time down to a multiple of the specified `precision`.

- `date_ceiling()` rounds a date-time up to a multiple of the specified `precision`.

- `date_round()` rounds up or down depending on what is closer, rounding up on ties.

You can group by irregular periods such as `"month"` or `"year"` by using `date_group()`.

### Usage

    ## S3 method for class 'POSIXt'
    date_floor(
      x,
      precision,
      ...,
      n = 1L,
      origin = NULL,
      nonexistent = NULL,
      ambiguous = x
    )

    ## S3 method for class 'POSIXt'
    date_ceiling(
      x,
      precision,
      ...,
      n = 1L,
      origin = NULL,
      nonexistent = NULL,
      ambiguous = x
    )

    ## S3 method for class 'POSIXt'
    date_round(
      x,
      precision,
      ...,
      n = 1L,
      origin = NULL,
      nonexistent = NULL,
      ambiguous = x
    )

### Arguments

`x` | `[POSIXct / POSIXlt]` A date-time vector.
`precision` | `[character(1)]` One of: `"week"` `"day"` `"hour"` `"minute"` `"second"` `"week"` is an alias for `"day"` with `n * 7`.
`...` | These dots are for future extensions and must be empty.
`n` | `[positive integer(1)]` A single positive integer specifying a multiple of `precision` to use.
`origin` | `[POSIXct(1) / POSIXlt(1) / NULL]` An origin to start counting from. `origin` must have exactly the same time zone as `x`. `origin` will be floored to `precision`. If information is lost when flooring, a warning will be thrown. If `NULL`, defaults to midnight on 1970-01-01 in the time zone of `x`.
`nonexistent` | `[character / NULL]` One of the following nonexistent time resolution strategies, allowed to be either length 1, or the same length as the input: `"roll-forward"`: The next valid instant in time. `"roll-backward"`: The previous valid instant in time. `"shift-forward"`: Shift the nonexistent time forward by the size of the daylight saving time gap. `"shift-backward`: Shift the nonexistent time backward by the size of the daylight saving time gap. `"NA"`: Replace nonexistent times with `NA`. `"error"`: Error on nonexistent times. Using either `"roll-forward"` or `"roll-backward"` is generally recommended over shifting, as these two strategies maintain the relative ordering between elements of the input. If `NULL`, defaults to `"error"`. If `getOption("clock.strict")` is `TRUE`, `nonexistent` must be supplied and cannot be `NULL`. This is a convenient way to make production code robust to nonexistent times.
`ambiguous` | `[character / zoned_time / POSIXct / list(2) / NULL]` One of the following ambiguous time resolution strategies, allowed to be either length 1, or the same length as the input: `"earliest"`: Of the two possible times, choose the earliest one. `"latest"`: Of the two possible times, choose the latest one. `"NA"`: Replace ambiguous times with `NA`. `"error"`: Error on ambiguous times. Alternatively, `ambiguous` is allowed to be a zoned_time (or POSIXct) that is either length 1, or the same length as the input. If an ambiguous time is encountered, the zoned_time is consulted. If the zoned_time corresponds to a naive_time that is also ambiguous and uses the same daylight saving time transition point as the original ambiguous time, then the offset of the zoned_time is used to resolve the ambiguity. If the ambiguity cannot be resolved by consulting the zoned_time, then this method falls back to `NULL`. Finally, `ambiguous` is allowed to be a list of size 2, where the first element of the list is a zoned_time (as described above), and the second element of the list is an ambiguous time resolution strategy to use when the ambiguous time cannot be resolved by consulting the zoned_time. Specifying a zoned_time on its own is identical to `list(<zoned_time>, NULL)`. If `NULL`, defaults to `"error"`. If `getOption("clock.strict")` is `TRUE`, `ambiguous` must be supplied and cannot be `NULL`. Additionally, `ambiguous` cannot be specified as a zoned_time on its own, as this implies `NULL` for ambiguous times that the zoned_time cannot resolve. Instead, it must be specified as a list alongside an ambiguous time resolution strategy as described above. This is a convenient way to make production code robust to ambiguous times.

### Details

When rounding by `"week"`, remember that the `origin` determines the "week start". By default, 1970-01-01 is the implicit origin, which is a Thursday. If you would like to round by weeks with a different week start, just supply an origin on the weekday you are interested in.

### Value

`x` rounded to the specified `precision`.

### Examples

    x <- as.POSIXct("2019-03-31", "America/New_York")
    x <- add_days(x, 0:5)

    # Flooring by 2 days, note that this is not tied to the current month,
    # and instead counts from the specified `origin`, so groups can cross
    # the month boundary
    date_floor(x, "day", n = 2)

    # Compare to `date_group()`, which groups by the day of the month
    date_group(x, "day", n = 2)

    # Note that daylight saving time gaps can throw off rounding
    x <- as.POSIXct("1970-04-26 01:59:59", "America/New_York") + c(0, 1)
    x

    # Rounding is done in naive-time, which means that rounding by 2 hours
    # will attempt to generate a time of 1970-04-26 02:00:00, which doesn't
    # exist in this time zone
    try(date_floor(x, "hour", n = 2))

    # You can handle this by specifying a nonexistent time resolution strategy
    date_floor(x, "hour", n = 2, nonexistent = "roll-forward")

[Package clock version 0.4.1 Index]