EVOLUTION-MANAGER
Edit File: IDateTime.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: Integer based date class</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 IDateTime {data.table}"><tr><td>IDateTime {data.table}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2> Integer based date class </h2> <h3>Description</h3> <p>Date and time classes with integer storage for fast sorting and grouping. Still experimental! </p> <h3>Usage</h3> <pre> as.IDate(x, ...) ## Default S3 method: as.IDate(x, ..., tz = attr(x, "tzone", exact=TRUE)) ## S3 method for class 'Date' as.IDate(x, ...) ## S3 method for class 'IDate' as.Date(x, ...) ## S3 method for class 'IDate' as.POSIXct(x, tz = "UTC", time = 0, ...) ## S3 method for class 'IDate' round(x, digits = c("weeks", "months", "quarters","years"), ...) as.ITime(x, ...) ## Default S3 method: as.ITime(x, ...) ## S3 method for class 'POSIXlt' as.ITime(x, ms = 'truncate', ...) ## S3 method for class 'ITime' round(x, digits = c("hours", "minutes"), ...) ## S3 method for class 'ITime' trunc(x, units = c("hours", "minutes"), ...) ## S3 method for class 'ITime' as.POSIXct(x, tz = "UTC", date = Sys.Date(), ...) ## S3 method for class 'ITime' as.character(x, ...) ## S3 method for class 'ITime' format(x, ...) IDateTime(x, ...) ## Default S3 method: IDateTime(x, ...) second(x) minute(x) hour(x) yday(x) wday(x) mday(x) week(x) isoweek(x) month(x) quarter(x) year(x) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>x</code></td> <td> <p>an object</p> </td></tr> <tr valign="top"><td><code>...</code></td> <td> <p>arguments to be passed to or from other methods. For <code>as.IDate.default</code>, arguments are passed to <code>as.Date</code>. For <code>as.ITime.default</code>, arguments are passed to <code>as.POSIXlt</code>.</p> </td></tr> <tr valign="top"><td><code>tz</code></td> <td> <p>time zone (see <code>strptime</code>).</p> </td></tr> <tr valign="top"><td><code>date</code></td> <td> <p>date object convertible with <code>as.IDate</code>.</p> </td></tr> <tr valign="top"><td><code>time</code></td> <td> <p>time-of-day object convertible with <code>as.ITime</code>.</p> </td></tr> <tr valign="top"><td><code>digits</code></td> <td> <p>really <code>units</code>; one of the units listed for rounding. May be abbreviated.</p> </td></tr> <tr valign="top"><td><code>units</code></td> <td> <p>one of the units listed for truncating. May be abbreviated.</p> </td></tr> <tr valign="top"><td><code>ms</code></td> <td> <p> For <code>as.ITime</code> methods, what should be done with sub-second fractions of input? Valid values are <code>'truncate'</code> (floor), <code>'nearest'</code> (round), and <code>'ceil'</code> (ceiling). See Details. </p> </td></tr> </table> <h3>Details</h3> <p><code>IDate</code> is a date class derived from <code>Date</code>. It has the same internal representation as the <code>Date</code> class, except the storage mode is integer. <code>IDate</code> is a relatively simple wrapper, and it should work in almost all situations as a replacement for <code>Date</code>. </p> <p>Functions that use <code>Date</code> objects generally work for <code>IDate</code> objects. This package provides specific methods for <code>IDate</code> objects for <code>mean</code>, <code>cut</code>, <code>seq</code>, <code>c</code>, <code>rep</code>, and <code>split</code> to return an <code>IDate</code> object. </p> <p><code>ITime</code> is a time-of-day class stored as the integer number of seconds in the day. <code>as.ITime</code> does not allow days longer than 24 hours. Because <code>ITime</code> is stored in seconds, you can add it to a <code>POSIXct</code> object, but you should not add it to a <code>Date</code> object. </p> <p>Conversions to and from <code>Date</code> and <code>POSIXct</code> formats are provided. </p> <p><code>ITime</code> does not account for time zones. When converting <code>ITime</code> and <code>IDate</code> to POSIXct with <code>as.POSIXct</code>, a time zone may be specified. </p> <p>Inputs like <code>'2018-05-15 12:34:56.789'</code> are ambiguous from the perspective of an <code>ITime</code> object – the method of coercion of the 789 milliseconds is controlled by the <code>ms</code> argument to relevant methods. The default behavior (<code>ms = 'truncate'</code>) is to use <code>as.integer</code>, which has the effect of truncating anything after the decimal. Alternatives are to round to the nearest integer (<code>ms = 'nearest'</code>) or to round up (<code>ms = 'ceil'</code>). </p> <p>In <code>as.POSIXct</code> methods for <code>ITime</code> and <code>IDate</code>, the second argument is required to be <code>tz</code> based on the generic template, but to make converting easier, the second argument is interpreted as a date instead of a time zone if it is of type <code>IDate</code> or <code>ITime</code>. Therefore, you can use either of the following: <code>as.POSIXct(time, date)</code> or <code>as.POSIXct(date, time)</code>. </p> <p><code>IDateTime</code> takes a date-time input and returns a data table with columns <code>date</code> and <code>time</code>. </p> <p>Using integer storage allows dates and/or times to be used as data table keys. With positive integers with a range less than 100,000, grouping and sorting is fast because radix sorting can be used (see <code>sort.list</code>). </p> <p>Several convenience functions like <code>hour</code> and <code>quarter</code> are provided to group or extract by hour, month, and other date-time intervals. <code>as.POSIXlt</code> is also useful. For example, <code>as.POSIXlt(x)$mon</code> is the integer month. The R base convenience functions <code>weekdays</code>, <code>months</code>, and <code>quarters</code> can also be used, but these return character values, so they must be converted to factors for use with data.table. <code>isoweek</code> is ISO 8601-consistent. </p> <p>The <code>round</code> method for IDate's is useful for grouping and plotting. It can round to weeks, months, quarters, and years. Similarly, the <code>round</code> and <code>trunc</code> methods for ITime's are useful for grouping and plotting. They can round or truncate to hours and minutes. Note for ITime's with 30 seconds, rounding is inconsistent due to rounding off a 5. See 'Details' in <code><a href="../../base/html/Round.html">round</a></code> for more information. </p> <h3>Value</h3> <p>For <code>as.IDate</code>, a class of <code>IDate</code> and <code>Date</code> with the date stored as the number of days since some origin. </p> <p>For <code>as.ITime</code>, a class of <code>ITime</code> stored as the number of seconds in the day. </p> <p>For <code>IDateTime</code>, a data table with columns <code>idate</code> and <code>itime</code> in <code>IDate</code> and <code>ITime</code> format. </p> <p><code>second</code>, <code>minute</code>, <code>hour</code>, <code>yday</code>, <code>wday</code>, <code>mday</code>, <code>week</code>, <code>month</code>, <code>quarter</code>, and <code>year</code> return integer values for second, minute, hour, day of year, day of week, day of month, week, month, quarter, and year, respectively. </p> <p>These values are all taken directly from the <code>POSIXlt</code> representation of <code>x</code>, with the notable difference that while <code>yday</code>, <code>wday</code>, and <code>mon</code> are all 0-based, here they are 1-based. </p> <h3>Author(s)</h3> <p> Tom Short, t.short@ieee.org </p> <h3>References</h3> <p>G. Grothendieck and T. Petzoldt, “Date and Time Classes in R,” R News, vol. 4, no. 1, June 2004. </p> <p>H. Wickham, https://gist.github.com/10238. </p> <p>ISO 8601, https://www.iso.org/iso/home/standards/iso8601.htm </p> <h3>See Also</h3> <p><code><a href="../../base/html/as.Date.html">as.Date</a></code>, <code><a href="../../base/html/as.POSIXlt.html">as.POSIXct</a></code>, <code><a href="../../base/html/strptime.html">strptime</a></code>, <code><a href="../../base/html/DateTimeClasses.html">DateTimeClasses</a></code> </p> <h3>Examples</h3> <pre> # create IDate: (d <- as.IDate("2001-01-01")) # S4 coercion also works identical(as.IDate("2001-01-01"), as("2001-01-01", "IDate")) # create ITime: (t <- as.ITime("10:45")) # S4 coercion also works identical(as.ITime("10:45"), as("10:45", "ITime")) (t <- as.ITime("10:45:04")) (t <- as.ITime("10:45:04", format = "%H:%M:%S")) as.POSIXct("2001-01-01") + as.ITime("10:45") datetime <- seq(as.POSIXct("2001-01-01"), as.POSIXct("2001-01-03"), by = "5 hour") (af <- data.table(IDateTime(datetime), a = rep(1:2, 5), key = "a,idate,itime")) af[, mean(a), by = "itime"] af[, mean(a), by = list(hour = hour(itime))] af[, mean(a), by = list(wday = factor(weekdays(idate)))] af[, mean(a), by = list(wday = wday(idate))] as.POSIXct(af$idate) as.POSIXct(af$idate, time = af$itime) as.POSIXct(af$idate, af$itime) as.POSIXct(af$idate, time = af$itime, tz = "GMT") as.POSIXct(af$itime, af$idate) as.POSIXct(af$itime) # uses today's date (seqdates <- seq(as.IDate("2001-01-01"), as.IDate("2001-08-03"), by = "3 weeks")) round(seqdates, "months") (seqtimes <- seq(as.ITime("07:00"), as.ITime("08:00"), by = 20)) round(seqtimes, "hours") trunc(seqtimes, "hours") </pre> <hr /><div style="text-align: center;">[Package <em>data.table</em> version 1.14.4 <a href="00Index.html">Index</a>]</div> </body></html>