round_date {lubridate} | R Documentation |
Rounding to the nearest unit or multiple of a unit are supported. All
meaningfull specifications in English language are supported - secs, min,
mins, 2 minutes, 3 years etc.
round_date
takes a date-time object and rounds it to the nearest value
of the specified time unit. For rounding date-times which is exactly halfway
between two consecutive units, the convention is to round up. Note that this
is in line with the behavior of R's base round.POSIXt function
but does not follow the convention of the base round function
which "rounds to the even digit" per IEC 60559.
floor_date
takes a date-time object and rounds it down to the nearest
boundary of the specified time unit.
ceiling_date
takes a date-time object and rounds it up to the nearest
boundary of the specified time unit.
round_date(x, unit = "second") floor_date(x, unit = "seconds") ceiling_date(x, unit = "seconds", change_on_boundary = NULL)
x |
a vector of date-time objects |
unit |
a character string specifying the time unit or a multiple of a
unit to be rounded to. Valid base units are second, minute, hour, day,
week, month, bimonth, quarter, halfyear, or year. Arbitrary unique English
abbreviations as in |
change_on_boundary |
If NULL (the default) don't change instants on the
boundary ( |
In lubridate
rounding of a date-time objects tries to preserve the
class of the input object whenever it is meaningful. This is done by first
rounding to an instant and then converting to the original class by usual R
conventions.
By default rounding up Date
objects follows 3 steps:
Convert to an instant representing lower bound of the Date:
2000-01-01
–> 2000-01-01 00:00:00
Round up to the next closest rounding unit boundary. For
example, if the rounding unit is month
then next boundary
for 2000-01-01
will be 2000-02-01 00:00:00
.
The motivation for this behavior is that 2000-01-01
is
conceptually an interval (2000-01-01 00:00:00 -- 2000-01-02
00:00:00)
and the day hasn't started clocking yet at the exact
boundary 00:00:00
. Thus, it seems wrong to round up a day to
its lower boundary.
If rounding unit is smaller than a day, return the instant from
step 2 above (POSIXct
), otherwise return the Date
immediately following that instant.
The behavior on the boundary in the second step above can be changed by
setting change_on_boundary
to a non-NULL
value.
x <- as.POSIXct("2009-08-03 12:01:59.23") round_date(x, "second") round_date(x, "minute") round_date(x, "5 mins") round_date(x, "hour") round_date(x, "2 hours") round_date(x, "day") round_date(x, "week") round_date(x, "month") round_date(x, "bimonth") round_date(x, "quarter") == round_date(x, "3 months") round_date(x, "halfyear") round_date(x, "year") x <- as.POSIXct("2009-08-03 12:01:59.23") floor_date(x, "second") floor_date(x, "minute") floor_date(x, "hour") floor_date(x, "day") floor_date(x, "week") floor_date(x, "month") floor_date(x, "bimonth") floor_date(x, "quarter") floor_date(x, "halfyear") floor_date(x, "year") x <- as.POSIXct("2009-08-03 12:01:59.23") ceiling_date(x, "second") ceiling_date(x, "minute") ceiling_date(x, "5 mins") ceiling_date(x, "hour") ceiling_date(x, "day") ceiling_date(x, "week") ceiling_date(x, "month") ceiling_date(x, "bimonth") == ceiling_date(x, "2 months") ceiling_date(x, "quarter") ceiling_date(x, "halfyear") ceiling_date(x, "year") x <- ymd("2000-01-01") ceiling_date(x, "month") ceiling_date(x, "month", change_on_boundary = TRUE)