R: Create a Chronological Object

chron {chron} | R Documentation

## Create a Chronological Object

### Description

Create chronological objects which represent dates and times of day.

### Usage

    chron(dates., times., format = c(dates = "m/d/y", times = "h:m:s"),
          out.format, origin.)

### Arguments

`dates.` | character or numeric vector specifying dates. If character, `dates.` are assumed to be in one of the date formats below; if numeric, `dates.` are assumed to be Julian dates, i.e., number of days since `origin.`.
`times.` | optional character or numeric vector specifying times of day. If character, `times.` are assumed to be in one of the time formats below; if numeric, `times.` are assumed to be fractions of a day.
`format` | vector or list specifying the input format of the input. The format can be either strings specifying one of the recognized formats below or a list of user-supplied functions to convert dates from character into Julian dates and vice versa. The dates format can be any permutation of the characters `"d"`, `"m"`, or `"y"` delimited by a separator (possibly null), e.g., `"m/d/y"`, `"d-m-y"`, `"ymd"`, are all valid; the format can also be permutations of the words `"day"`, `"month"` and `"year"` (with non-null separator), which produces the month name, e.g., `"month day year"` produces `"April 20 1992"`, `"day mon year"` produces `"20 Apr 1992"`. The times format can be any permutation of `"h"`, `"m"`, and `"s"` separated by any one non-special character. The default is `"h:m:s"`.
`out.format` | vector or list specifying date and time format for printing and output. Default is same as `format`.
`origin.` | a vector specifying the date with respect to which Julian dates are computed. Default is `c(month = 1, day = 1, year = 1970)`; you may set the option `chron.origin` to specify your own default, e.g., `options(chron.origin = c(month=1, day=1, year=1990))`.

### Value

An object of class `"times"` if only `times.` were specified, `"dates"` if only `dates.`, or `"chron"` if both `dates.` and `times.` were supplied. All these inherit from class `"times"`.

These objects represent dates and times of day, and allow the following arithmetic and summaries: subtraction `d1-d2`, constant addition `d1+constants`, all logical comparisons, summaries `min()`, `max()`, and `range()` (which drop NAs by default); constants specify days (fractions are converted to time-of-day, e.g., 2.5 represents 2 days and 12 hours). Operations such as sorting, differencing, etc., are automatically handled.

There are methods for `as.character()`, `as.numeric()`, `cut()`, `is.na()`, `print()`, `summary()`, `plot()`, `lines()`, `lag()`, and the usual subsetting functions `[`, `[<-`. The functions `days()`, `months()`, `quarters()`, `years()`, `weeks()`, `weekdays()`, `hours()`, `minutes()`, and `seconds()` take any `chron` object as input and extract the corresponding time interval. `cut()` is used to create ordered factors from `chron` objects. Chronological objects may be used with the modeling software.

If `x` is `character` then it will be converted using `as.POSIXct` (with the `format` argument, if any, passed to `as.POSIXct`) and `tz = "GMT"` and then converted to `chron`. If `x` is `numeric` and `format` is not specified then it will be converted to `chron` using `chron(x)`. If `x` is `numeric` and `format` is `specified` then `x` will be converted to character and then processed using `as.POSIXct` as discussed above. If the format is specified as `NULL` it will be treated the same as if it were `missing`.

The current implementation of `chron` objects does not handle time zones nor daylight savings time.

### See Also

`dates`, `times`, `julian.default`, `cut.dates`, `seq.dates`.

### Examples

    dts <- dates(c("02/27/92", "02/27/92", "01/14/92",
                   "02/28/92", "02/01/92"))
    dts
    # [1] 02/27/92 02/27/92 01/14/92 02/28/92 02/01/92
    tms <- times(c("23:03:20", "22:29:56", "01:03:30",
                   "18:21:03", "16:56:26"))
    tms
    # [1] 23:03:20 22:29:56 01:03:30 18:21:03 16:56:26
    x <- chron(dates = dts, times = tms)
    x
    # [1] (02/27/92 23:03:19) (02/27/92 22:29:56) (01/14/92 01:03:30)
    # [4] (02/28/92 18:21:03) (02/01/92 16:56:26)

    # We can add or subtract scalars (representing days) to dates or
    # chron objects:
    c(dts[1], dts[1] + 10)
    # [1] 02/27/92 03/08/92
    dts[1] - 31
    # [1] 01/27/92

    # We can substract dates which results in a times object that
    # represents days between the operands:
    dts[1] - dts[3]
    # Time in days:
    # [1] 44

    # Logical comparisons work as expected:
    dts[dts > "01/25/92"]
    # [1] 02/27/92 02/27/92 02/28/92 02/01/92
    dts > dts[3]
    # [1]  TRUE  TRUE FALSE  TRUE  TRUE

    # Summary operations which are sensible are permitted and work as
    # expected:
    range(dts)
    # [1] 01/14/92 02/28/92
    diff(x)
    # Time in days:
    # [1]  -0.02319444 -44.89335648  45.72052083 -27.05876157
    sort(dts)[1:3]
    # [1] 01/14/92 02/01/92 02/27/92

[Package chron version 2.3-53 Index]