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.

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