Chronological objects which can handle dates and times

Chronological objects which can handle dates and times [R logo]

Help pages for package `chron' version 2.3-10

.Holidays | Find Weekends and Holidays in a Chron or Dates Object
all.equal.dates | Generate Dates and Times Components from Input
as.character.times | Generate Dates and Times Components from Input
as.chron | Create a Chronological Object
as.data.frame.chron | Create a Chronological Object
as.data.frame.dates | Generate Dates and Times Components from Input
as.data.frame.times | Generate Dates and Times Components from Input
axis.times | Generate Dates and Times Components from Input
c.dates | Generate Dates and Times Components from Input
c.times | Generate Dates and Times Components from Input
chron | Create a Chronological Object
cut.dates | Create a Factor from a Chron or Dates Object
dates | Generate Dates and Times Components from Input
day.of.week | Convert between Julian and Calendar Dates
days | Return Various Periods from a Chron or Dates Object
diff.times | Generate Dates and Times Components from Input
floor.dates | Generate Dates and Times Components from Input
format.chron | Create a Chronological Object
format.dates | Generate Dates and Times Components from Input
format.times | Generate Dates and Times Components from Input
hist.times | Generate Dates and Times Components from Input
hours | Return Hours, Minutes, or Seconds from a Times Object
identify.times | Generate Dates and Times Components from Input
is.chron | Create a Chronological Object
is.holiday | Find Weekends and Holidays in a Chron or Dates Object
is.na.times | Generate Dates and Times Components from Input
is.weekend | Find Weekends and Holidays in a Chron or Dates Object
julian.default | Convert between Julian and Calendar Dates
leap.year | Convert between Julian and Calendar Dates
lines.times | Generate Dates and Times Components from Input
Math.dates | Generate Dates and Times Components from Input
Math.times | Generate Dates and Times Components from Input
mean.times | Generate Dates and Times Components from Input
minutes | Return Hours, Minutes, or Seconds from a Times Object
month.day.year | Convert between Julian and Calendar Dates
months.default | Return Various Periods from a Chron or Dates Object
Ops.dates | Generate Dates and Times Components from Input
Ops.times | Generate Dates and Times Components from Input
plot.times | Generate Dates and Times Components from Input
points.times | Generate Dates and Times Components from Input
print.chron | Create a Chronological Object
print.dates | Generate Dates and Times Components from Input
print.times | Generate Dates and Times Components from Input
quantile.times | Generate Dates and Times Components from Input
quarters.default | Return Various Periods from a Chron or Dates Object
seconds | Return Hours, Minutes, or Seconds from a Times Object
seq.dates | Generate Chron or Dates Sequences
Summary.dates | Generate Dates and Times Components from Input
Summary.times | Generate Dates and Times Components from Input
summary.times | Generate Dates and Times Components from Input
times | Generate Dates and Times Components from Input
trunc.dates | Generate Dates and Times Components from Input
trunc.times | Truncate times Objects
weekdays.default | Return Various Periods from a Chron or Dates Object
years | Return Various Periods from a Chron or Dates Object
[.times | Generate Dates and Times Components from Input
[[.times | Generate Dates and Times Components from Input


Create a Chronological Object

Description

Create chrononogical 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.
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-10 Index]


Internal chron objects

Description

Internal chron objects.

Usage

year.expand(y, cut.off = 30, century = c(1900, 2000), ...)
year.strict(...)

Details

These are not to be called by the user.


Create a Factor from a Chron or Dates Object

Description

Divide the range of a chron or dates object x into intervals and code the values in x according to which interval they fall.

Usage

## S3 method for class 'dates':
cut(x, breaks, labels, start.on.monday = TRUE, ...)

Arguments

x | chron or dates object (see chron), character dates such as "10/04/91" or Julian dates).
breaks | either a vector of break points (a dates vector, character dates such as "10/04/91" or Julian dates), a constant specifying number of equally spaced intervals extending from min(x)-1 to max(x)+1, or one of the strings in c("days", "weeks", "months", "year") specifying a time period.
labels | character labels for intervals.
start.on.monday | should weeks be assumed to start on Mondays? Default is TRUE. Set to FALSE if weeks start on Sundays; for other days of the week specify the corresponding number: Sunday == 0, Monday == 1, Tuesday == 2, ..., Saturday == 6.
... | further arguments to be passed to or from methods.

Value

an ordered factor whose levels represent the various time intervals.

See Also

seq.dates

Examples

# days from 07/01/92 thru 07/15/92 fell into 3 Monday-started weeks
cut(dates("07/01/92") + 0:14, "weeks")
# [1] week 1 week 1 week 1 week 1 week 1 week 2 week 2 week 2
# [9] week 2 week 2 week 2 week 2 week 3 week 3 week 3

dts <- dates(c("02/27/92", "02/27/92", "01/14/92",
               "02/28/92", "02/01/92"))
cut(dts, "months")
# [1] Feb 92 Feb 92 Jan 92 Feb 92 Feb 92
boxplot(runif(5) ~ cut(dts, "months"))


Generate Dates and Times Components from Input

Description

Create objects which represent dates or times.

Usage

dates(x, ...)
times(x, ...)

Arguments

x | a chron object, a character vector, or a numeric vector specifying time. If character, it must be in a format recognized by chron(). If numeric, it specifies Julian dates, i.e., number of days since an origin.
... | parameters for chron().

Value

An object of class dates or times, depending of the function called.
These functions return objects inheriting from dates and times, respectively. They call chron() if x does not belong to any of the chronological classes.

See Also

chron, times, seq.dates, cut.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
class(dts)

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


Convert between Julian and Calendar Dates

Description

Utility functions to convert between Julian dates (numbers of days since an origin, by default 1970-01-01) and calendar dates given by year, month, and day within the month.

Usage

## Default S3 method:
julian(x, d, y, origin., ...)
month.day.year(jul, origin.)
leap.year(y)
day.of.week(month, day, year)

Arguments

x, month | vector of month numbers.
d, day | vector of day numbers.
y, year | vector of years.
jul | vector of Julian Dates, i.e., number of days since origin..
origin. | vector specifying the origin as month, day, and year. If missing, it defaults to getOption("chron.origin") if this is non-null, otherwise c(month = 1, day = 1, year = 1970).
... | further arguments to be passed to or from methods.

Value

A vector of Julian dates (number of days since origin.) when julian() is called, or a list with members month, day, year corresponding to the input Julian dates if month.day.year() is called. leap.year() returns a logical vector indicating whether the corresponding year is a leap year. day.of.week() returns a number between 0 and 6 to specify day of the week–0 refers to Sunday.
These functions were taken from Becker, Chambers, and Wilks (1988), and were slightly modified to take chron and dates objects; some also take the extra argument origin..

See Also

chron, dates, times

Examples

julian(1, 1, 1970)
# [1] 0
unlist(month.day.year(0))
# month   day  year
#     1     1  1970


Return Various Periods from a Chron or Dates Object

Description

Given a chron or dates object, extract the year, quarter, month, day (within the month) or weekday (days within the week) of the date it represents.

Usage

days(x)
## Default S3 method:
weekdays(x, abbreviate = TRUE)
## Default S3 method:
months(x, abbreviate = TRUE)
## Default S3 method:
quarters(x, abbreviate = TRUE)
years(x)

Arguments

x | a dates object.
abbreviate | should abbreviated names be returned? Default is TRUE.

Value

an ordered factor corresponding to days, weekdays, months, quarters, or years of x for the respective function.

See Also

is.weekend, is.holiday

Examples

dts <- dates("07/01/78") + trunc(50 * rnorm(30))
plot(weekdays(dts))
plot(months(dts))


Return Hours, Minutes, or Seconds from a Times Object

hours(chron) R Documentation

Return Hours Minutes or Seconds from a Times Object

Description

Given a chron or times object, extract the hours, minutes or seconds of the time it represents.

Usage

hours(x)
minutes(x)
seconds(x)

Arguments

x an object inheriting from class "times".

Value

the corresponding time period as an ordered factor.

See Also

chron, dates, times

Examples

x <- chron(dates = c("02/27/92", "02/27/92", "01/14/92", "02/28/92"),
           times = c("23:03:20", "22:29:56", "01:03:30", "18:21:03"))
h <- hours(x)
y <- runif(4)
boxplot(y ~ h)


Find Weekends and Holidays in a Chron or Dates Object

Description

Determine the date represented by a chron or dates object is a weekend or a holiday.

Usage

is.weekend(x)
is.holiday(x, holidays)
.Holidays

Arguments

x | an object inheriting from "dates", or coercible to "chron".
holidays | optional "chron" or "dates" object listing holidays. If argument holidays is missing, either the value of the object .Holidays (if it exists) or NULL will be used.

Value

a logical object indicating whether the corresponding date is a weekend in the case of is.weekend() or a holiday in the case of is.holiday().

See Also

days, weekdays.default, months.default, quarters.default, years; chron, dates, cut.dates, seq.dates

Examples

dts <- dates("01/01/98") + trunc(365 * runif(50))
table(is.weekend(dts))

.Holidays
# New Year Memorial Indepen. Labor day Thanksgiving Christmas
# 01/01/92 05/25/92 07/04/92  09/07/92     11/26/92  12/25/92
# NOTE:  Only these 6 holidays from 1992 are defined by default!


Generate Chron or Dates Sequences

Description

Generate a regular sequence of dates.

Usage

seq.dates(from, to, by = "days", length., ...)

Arguments

from | starting date; it can be a chron or dates object, a character string, e.g., "05/23/91", or a Julian date.
to | ending date, like from.
by | either a numeric value or one of the valid strings "days", "weeks", "months", or "years".
length. | optional number of elements in the sequence.
... | further arguments to be passed to or from methods.

Value

a sequence with values (form, from + by, from + 2*by, ..., to) of class class(from) and origin origin(from). Note that from must be less than or equal to the argument to.

See Also

chron, dates, cut.dates

Examples

seq.dates("01/01/92", "12/31/92", by = "months")
# [1] 01/01/92 02/01/92 03/01/92 04/01/92 05/01/92 06/01/92
# [7] 07/01/92 08/01/92 09/01/92 10/01/92 11/01/92 12/01/92

end.of.the.month <- seq.dates("02/29/92", by = "month", length = 15)
end.of.the.month
#  [1] 02/29/92 03/31/92 04/30/92 05/31/92 06/30/92 07/31/92
#  [7] 08/31/92 09/30/92 10/31/92 11/30/92 12/31/92 01/31/93
# [13] 02/28/93 03/31/93 04/30/93


Truncate times Objects

Description

Truncate times objects.

Usage

## S3 method for class 'times':
trunc(x, units = "days", eps = 1e-10)

Arguments

x | a "times" object.
units | Can be one of "days", "hours", "minutes", "seconds" or an unambiguous abbreviated version of any of those.
eps | Comparison tolerance. Times are considered equal if their absolute difference is less than eps.

Details

The time is truncated to the second, minute, hour or day or to the value specified.

Value

An object of class "times".

See Also

trunc for the generic function and default methods.

Examples

tt <- times(c("12:13:14", "15:46:17"))
trunc(tt, "minutes")
trunc(tt, "min")
trunc(tt, times("00:01:00"))
trunc(tt, "00:01:00")
trunc(tt, 1/(24*60))

tt2 <- structure(c(3.0, 3.1, 3.5, 3.9), class = "times")
trunc(tt2, "day")
trunc(tt2)