R: Integer based date class

IDateTime {data.table} | R Documentation

## Integer based date class

### Description

Date and time classes with integer storage for fast sorting and grouping. Still experimental!

### Usage

    as.IDate(x, ...)
    ## Default S3 method:
    as.IDate(x, ..., tz = attr(x, "tzone"))
    ## 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'
    as.POSIXct(x, tz = "UTC", date = as.Date(Sys.time()), ...)
    ## 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)

### Arguments

`x` | an object
`...` | arguments to be passed to or from other methods. For `as.IDate.default`, arguments are passed to `as.Date`. For `as.ITime.default`, arguments are passed to `as.POSIXlt`.
`tz` | time zone (see `strptime`).
`date` | date object convertable with `as.IDate`.
`time` | time-of-day object convertable with `as.ITime`.
`digits` | really `units`; one of the units listed for rounding. May be abbreviated.
`ms` | For `as.ITime` methods, what should be done with sub-second fractions of input? Valid values are `'truncate'` (floor), `'nearest'` (round), and `'ceil'` (ceiling). See Details.

### Details

`IDate` is a date class derived from `Date`. It has the same internal representation as the `Date` class, except the storage mode is integer. `IDate` is a relatively simple wrapper, and it should work in almost all situations as a replacement for `Date`.

Functions that use `Date` objects generally work for `IDate` objects. This package provides specific methods for `IDate` objects for `mean`, `cut`, `seq`, `c`, `rep`, and `split` to return an `IDate` object.

`ITime` is a time-of-day class stored as the integer number of seconds in the day. `as.ITime` does not allow days longer than 24 hours. Because `ITime` is stored in seconds, you can add it to a `POSIXct` object, but you should not add it to a `Date` object.

Conversions to and from `Date` and `POSIXct` formats are provided.

`ITime` does not account for time zones. When converting `ITime` and `IDate` to POSIXct with `as.POSIXct`, a time zone may be specified.

Inputs like `'2018-05-15 12:34:56.789'` are ambiguous from the perspective of an `ITime` object – the method of coercion of the 789 milliseconds is controlled by the `ms` argument to relevant methods. The default behavior (`ms = 'truncate'`) is to use `as.integer`, which has the effect of truncating anything after the decimal. Alternatives are to round to the nearest integer (`ms = 'nearest'`) or to round up (`ms = 'ceil'`).

In `as.POSIXct` methods for `ITime` and `IDate`, the second argument is required to be `tz` 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 `IDate` or `ITime`. Therefore, you can use either of the following: `as.POSIXct(time, date)` or `as.POSIXct(date, time)`.

`IDateTime` takes a date-time input and returns a data table with columns `date` and `time`.

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 `sort.list`).

Several convenience functions like `hour` and `quarter` are provided to group or extract by hour, month, and other date-time intervals. `as.POSIXlt` is also useful. For example, `as.POSIXlt(x)$mon` is the integer month. The R base convenience functions `weekdays`, `months`, and `quarters` can also be used, but these return character values, so they must be converted to factors for use with data.table. `isoweek` is ISO 8601-consistent.

The `round` method for IDate's is useful for grouping and plotting. It can round to weeks, months, quarters, and years.

### Value

For `as.IDate`, a class of `IDate` and `Date` with the date stored as the number of days since some origin.

For `as.ITime`, a class of `ITime` stored as the number of seconds in the day.

For `IDateTime`, a data table with columns `idate` and `itime` in `IDate` and `ITime` format.

`second`, `minute`, `hour`, `yday`, `wday`, `mday`, `week`, `month`, `quarter`, and `year` return integer values for second, minute, hour, day of year, day of week, day of month, week, month, quarter, and year, respectively.

These values are all taken directly from the `POSIXlt` representation of `x`, with the notable difference that while `yday`, `wday`, and `mon` are all 0-based, here they are 1-based.

### Author(s)

Tom Short, t.short@ieee.org

### References

G. Grothendieck and T. Petzoldt, “Date and Time Classes in R,” R News, vol. 4, no. 1, June 2004.

H. Wickham, http://gist.github.com/10238.

ISO 8601, http://www.iso.org/iso/home/standards/iso8601.htm

### See Also

`as.Date`, `as.POSIXct`, `strptime`, `DateTimeClasses`

### Examples

    # 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")

[Package data.table version 1.11.8 Index]