cut.mondate: Convert a mondate Object to a Factor

In chiefmurph/mondate: Keep track of dates in terms of months

Convert a mondate Object to a Factor

Description

Method for cut applied to mondate objects.

Usage

 ## S3 method for class 'mondate'
cut(x, breaks, labels = NULL, 
      include.lowest = FALSE, right = TRUE, 
      start.on.monday = TRUE, startmonth = NULL, startyear = NULL,
      attr.breaks = FALSE, ...)

Arguments

x	a mondate
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 "day", "week", "month", "quarter" or "year", optionally preceded by an integer and a space, or followed by "s" (pluralized).
labels	labels for the levels of the resulting category. By default, labels are constructed from the right-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.
include.lowest	logical, indicating if an 'x[i]' equal to the lowest (or highest, for right = FALSE) 'breaks' value should be included. (Note: Beginning with version 0.11 of mondate, !include.lowest is invalid when breaks is character.)
right	logical, indicating if the intervals should be closed on the right (and open on the left) or vice versa.
start.on.monday	logical. If breaks = "weeks", should the week start on Mondays or Sundays?
startmonth	If not NULL, the number of the month (1 = January, ..., 12 = December) corresponding to the beginning of the year/fiscal-year. If NULL, the resulting intervals begin or end depending on the minimum (!right) or maximum (right) value, respectively, of x. This argument only has an impact when character breaks defines multi-month intervals.
startyear	If not NULL, the year corresponding to the left-most level. If NULL, the resulting intervals begin or end depending on the minimum (!right) or maximum (right) value, respectively, of x. This argument only has an impact when character breaks defines month or multi-month intervals.
attr.breaks	logical. If TRUE the result has a "breaks" attribute which is a mondate whose pairwise values determine a covering of x. Most helpful when breaks = "days", "weeks", "months", "quarters", or "years".
...	optional arguments passed to or from other methods.

Details

This method converts a mondate to a factor corresponding to time intervals as determined by the argument breaks. In the "end-of-business-day" spirit of the mondate package, the intervals (levels) are labeled by the last day in the interval. If right = FALSE the levels are labeled by the left endpoint of the interval, which is the day immediately preceding the beginning of the period. For methods that work in the spirit of Date and POSIXt – i.e., a time interval is better labeled by the first day of the period – see cutmondate.

For numeric breaks – which case also includes mondates – the method calls cut.default and the intervals encoded in the levels are converted to date format using mondate logic. In the spirit of mondate, the default right = TRUE ensures that the intervals are left-open/right-closed. The default include.lowest = TRUE ensures that min(x) is included in the first interval.

For breaks = "days" or "weeks", the method calls cut(as.Date(x)). For breaks = "months", "quarters", and "years", numeric breaks are determined from the range of x.

If breaks is preceded by an integer, call it step, then the period of the first level is determined by min(x) and subsequent "day", "week", "month", "quarter", and "year" periods are determined sequentially per seq(min(x), max(x), by = step).

When attr.breaks = TRUE, the result will have a "breaks" attribute (attr(., "breaks")) which pairwise "cover" x. Such "breaks" are suitable be use by 'hist', for example.

In all cases, the formats of the dates representing the levels are inherited from displayFormat(x). Accordingly, if such resulting potential levels would be non-unique, cut.mondate resorts to the fall-back scheme of cut.default, i.e., "labels such as "Range3" will be used."

Value

A factor is returned, unless labels = FALSE which returns the integer level codes.

Author(s)

Dan Murphy. Many thanks to the R-development team for cut and cut.Date.

See Also

cut, cut.Date, and cutmondate for methods that work better with Dates.

Examples

# days
x <- mondate.ymd(2013, 1, 1:7)
cut(x, breaks = "days", include.lowest = TRUE)
cut(x, breaks = "days", include.lowest = TRUE)

# weeks
x <- mondate.ymd(2013, 1, 1:31)  # days in January 2013
# labeled by the first 5 Sundays of 2013
cut(x, breaks = "weeks", include.lowest = TRUE, right = TRUE) 

x <- mondate.ymd(2015, 1, 5:25)  # days in January 2013
# labeled by the 1st and 3rd Mondays of 2015
cut(x, breaks = "2 weeks", include.lowest = TRUE, right = FALSE) 

# months
x <- mondate.ymd(2013, 1:12, 15) # 15th day of each month in 2013
# labeled by the left endpoint of the interval = last day of the month
cut(x, breaks = "months", include.lowest = TRUE)
# labeled by the right endpoint of the interval = last day of the prior month
cut(x, breaks = "months", right = FALSE, include.lowest = TRUE)
cut(x, breaks = "2 months", include.lowest = TRUE) 

# quarters
x <- mondate.ymd(2013, 1:12, 15)          # 15th day of each month in 2013
cut(x, "quarters", include.lowest = TRUE) # labeled by last day of the quarter
cut(x, "2 quarters", include.lowest = TRUE)

# years
m <- mondate(0:12)
cut(m, "years", include.lowest = TRUE)  # labeled by last day of the year 2000
cut(m, "years", right = FALSE, include.lowest = TRUE) # labeled by first day of 2000
displayFormat(m) <- "%Y"
cut(m, "years", include.lowest = TRUE)  # labeled by just the year of the date

# numeric scalar breaks

# Four intervals starting with 2015-01-15 (exclusive) and ending with
# 2015-12-15 (inclusive)
# First factor value is NA because include.lowest is FALSE (default)
x <- mondate.ymd(2015, 1:12, 15)
cut(x, breaks = 4)
# Now 2015-01-15 will be included in the first left-closed interval.
cut(x, breaks = 4, include.lowest = TRUE)

# specific break boundaries -- month-ends
cut(x, breaks = mondate("2014-12-31") + 0:12) # levels show interval boundaries
# Compare with next, where levels are labeled by interval endpoints
cut(x, breaks = "month", include.lowest = TRUE) 

chiefmurph/mondate documentation built on Aug. 29, 2022, 4:13 p.m.