EVOLUTION-MANAGER
Edit File: round_date.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Round, floor and ceiling methods for date-time objects</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for round_date {lubridate}"><tr><td>round_date {lubridate}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Round, floor and ceiling methods for date-time objects</h2> <h3>Description</h3> <p><code>round_date()</code> takes a date-time object and time unit, and rounds it to the nearest value of the specified time unit. For rounding date-times which are exactly halfway between two consecutive units, the convention is to round up. Note that this is in line with the behavior of R's <code><a href="../../base/html/round.POSIXt.html">base::round.POSIXt()</a></code> function but does not follow the convention of the base <code><a href="../../base/html/round.html">base::round()</a></code> function which "rounds to the even digit", as per IEC 60559. </p> <p>Rounding to the nearest unit or multiple of a unit is supported. All meaningful specifications in the English language are supported - secs, min, mins, 2 minutes, 3 years etc. </p> <p>Rounding to fractional seconds is also supported. Please note that rounding to fractions smaller than 1 second can lead to large precision errors due to the floating point representation of the POSIXct objects. See examples. </p> <p><code>floor_date()</code> takes a date-time object and rounds it down to the nearest boundary of the specified time unit. </p> <p><code>ceiling_date()</code> takes a date-time object and rounds it up to the nearest boundary of the specified time unit. </p> <h3>Usage</h3> <pre> round_date( x, unit = "second", week_start = getOption("lubridate.week.start", 7) ) floor_date( x, unit = "seconds", week_start = getOption("lubridate.week.start", 7) ) ceiling_date( x, unit = "seconds", change_on_boundary = NULL, week_start = getOption("lubridate.week.start", 7) ) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>x</code></td> <td> <p>a vector of date-time objects</p> </td></tr> <tr valign="top"><td><code>unit</code></td> <td> <p>a character string specifying a time unit or a multiple of a unit to be rounded to. Valid base units are <code>second</code>, <code>minute</code>, <code>hour</code>, <code>day</code>, <code>week</code>, <code>month</code>, <code>bimonth</code>, <code>quarter</code>, <code>season</code>, <code>halfyear</code> and <code>year</code>. Arbitrary unique English abbreviations as in the <code><a href="period.html">period()</a></code> constructor are allowed. Rounding to multiples of units (except weeks) is supported.</p> </td></tr> <tr valign="top"><td><code>week_start</code></td> <td> <p>when unit is <code>weeks</code>, specify the reference day. 7 represents Sunday and 1 represents Monday.</p> </td></tr> <tr valign="top"><td><code>change_on_boundary</code></td> <td> <p>if this is <code>NULL</code> (the default), instants on the boundary remain unchanged, but <code>Date</code> objects are rounded up to the next boundary. If this is <code>TRUE</code>, instants on the boundary are rounded up to the next boundary. If this is <code>FALSE</code>, nothing on the boundary is rounded up at all. This was the default for <span class="pkg">lubridate</span> prior to <code>v1.6.0</code>. See section <code style="white-space: pre;">Rounding Up Date Objects</code> below for more details.</p> </td></tr> </table> <h3>Details</h3> <p>In <span class="pkg">lubridate</span>, functions that round date-time objects try to preserve the class of the input object whenever possible. This is done by first rounding to an instant, and then converting to the original class as per usual R conventions. </p> <h3>Rounding Up Date Objects</h3> <p>By default, rounding up <code>Date</code> objects follows 3 steps: </p> <ol> <li><p> Convert to an instant representing lower bound of the Date: <code>2000-01-01</code> –> <code style="white-space: pre;">2000-01-01 00:00:00</code> </p> </li> <li><p> Round up to the <strong>next</strong> closest rounding unit boundary. For example, if the rounding unit is <code>month</code> then next closest boundary of <code>2000-01-01</code> is <code style="white-space: pre;">2000-02-01 00:00:00</code>. </p> <p>The motivation for this is that the "partial" <code>2000-01-01</code> is conceptually an interval (<code style="white-space: pre;">2000-01-01 00:00:00</code> – <code style="white-space: pre;">2000-01-02 00:00:00</code>) and the day hasn't started clocking yet at the exact boundary <code>00:00:00</code>. Thus, it seems wrong to round a day to its lower boundary. </p> <p>Behavior on the boundary can be changed by setting <code>change_on_boundary</code> to <code>TRUE</code> or <code>FALSE</code>. </p> </li> <li><p> If the rounding unit is smaller than a day, return the instant from step 2 (<code>POSIXct</code>), otherwise convert to and return a <code>Date</code> object. </p> </li></ol> <h3>See Also</h3> <p><code><a href="../../base/html/round.html">base::round()</a></code> </p> <h3>Examples</h3> <pre> ## print fractional seconds options(digits.secs=6) x <- ymd_hms("2009-08-03 12:01:59.23") round_date(x, ".5s") round_date(x, "sec") 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 <- ymd_hms("2009-08-03 12:01:59.23") floor_date(x, ".1s") 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, "season") floor_date(x, "halfyear") floor_date(x, "year") x <- ymd_hms("2009-08-03 12:01:59.23") ceiling_date(x, ".1 sec") # imprecise representation at 0.1 sec !!! 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, "season") ceiling_date(x, "halfyear") ceiling_date(x, "year") ## As of R 3.4.2 POSIXct printing of fractional numbers is wrong as.POSIXct("2009-08-03 12:01:59.3") ## -> "2009-08-03 12:01:59.2 CEST" ceiling_date(x, ".1 sec") ## -> "2009-08-03 12:01:59.2 CEST" ## behaviour of `change_on_boundary` ## As per default behaviour `NULL`, instants on the boundary remain the ## same but dates are rounded up ceiling_date(ymd_hms("2000-01-01 00:00:00"), "month") ceiling_date(ymd("2000-01-01"), "month") ## If `TRUE`, both instants and dates on the boundary are rounded up ceiling_date(ymd_hms("2000-01-01 00:00:00"), "month", change_on_boundary = TRUE) ceiling_date(ymd("2000-01-01"), "month") ## If `FALSE`, both instants and dates on the boundary remain the same ceiling_date(ymd_hms("2000-01-01 00:00:00"), "month", change_on_boundary = FALSE) ceiling_date(ymd("2000-01-01"), "month") x <- ymd_hms("2000-01-01 00:00:00") ceiling_date(x, "month") ceiling_date(x, "month", change_on_boundary = TRUE) ## For Date objects first day of the month is not on the ## "boundary". change_on_boundary applies to instants only. x <- ymd("2000-01-01") ceiling_date(x, "month") ceiling_date(x, "month", change_on_boundary = TRUE) </pre> <hr /><div style="text-align: center;">[Package <em>lubridate</em> version 1.7.9 <a href="00Index.html">Index</a>]</div> </body></html>