base (version 3.3)

cut.POSIXt: Convert a Date or Date-Time Object to a Factor

Description

Method for cut applied to date-time objects.

Usage

"cut"(x, breaks, labels = NULL, start.on.monday = TRUE, right = FALSE, ...)
"cut"(x, breaks, labels = NULL, start.on.monday = TRUE, right = FALSE, ...)

Arguments

x

an object inheriting from class "POSIXt" or "Date".

breaks

a vector of cut points or number giving the number of intervals which x is to be cut into or an interval specification, one of "sec", "min", "hour", "day", "DSTday", "week", "month", "quarter" or "year", optionally preceded by an integer and a space, or followed by "s". (For "Date" objects only interval specifications using "day", "week", "month", "quarter" and "year" are allowed.)

labels

labels for the levels of the resulting category. By default, labels are constructed from the left-hand end of the intervals (which are included for the default value of right). If labels = FALSE, simple integer codes are returned instead of a factor.

start.on.monday

logical. If breaks = "weeks", should the week start on Mondays or Sundays?

right, ...

arguments to be passed to or from other methods.

Value

A factor is returned, unless labels = FALSE which returns the integer level codes.Values which fall outside the range of breaks are coded as NA, as are and NA values.

Details

Note that the default for right differs from the default method. Using include.lowest = TRUE will include both ends of the range of dates.

Using breaks = "quarter" will create intervals of 3 calendar months, with the intervals beginning on January 1, April 1, July 1 or October 1 (based upon min(x)) as appropriate.

A vector of breaks will be sorted before use: labels should correspond to the sorted vector.

See Also

seq.POSIXt, seq.Date, cut

Examples

## random dates in a 10-week period
cut(ISOdate(2001, 1, 1) + 70*86400*stats::runif(100), "weeks")
cut(as.Date("2001/1/1") + 70*stats::runif(100), "weeks")

# The standards all have midnight as the start of the day, but some
# people incorrectly interpret it at the end of the previous day ...
tm <- seq(as.POSIXct("2012-06-01 06:00"), by = "6 hours", length.out = 24)
aggregate(1:24, list(day = cut(tm, "days")), mean)
# and a version with midnight included in the previous day:
aggregate(1:24, list(day = cut(tm, "days", right = TRUE)), mean)