cut: Group Time Indices into Periods / Convert to a Factor

Description

cut method for objects of tind class allows to map / group time indices into periods. The periods can be determined based on indices provided by the user or by (multiples of) units of time.

Usage

# S3 method for tind
cut(x, breaks, labels = TRUE, right = FALSE, ...)

Value

A factor if labels is TRUE, an integer vector if FALSE, and a 2-element list if NA, see Details.

Arguments

x: an object of tind class.
breaks: a numeric value or a character string determining intervals, or an object of tind class with cut points, see Details.
labels: a logical value controlling the return type, which can be a factor (if TRUE, the default), integer vector, or a 2-element list.
right: a logical value determing whether indices should be matched to the closest left cut point or to the closest right cut point, see Details.
...: (ignored) further arguments passed to or from other methods.

Details

breaks argument controls how indices are grouped. It can be a number or a character string determining resolution (or an object of tdiff class). Alternatively, breaks can be an object of tind class with cut points.

When breaks determines resolution, only selected multiples of units are allowed, similarly to floor_t function. Documentation of admissible units and multiples can be found in Details section of resolution_t method documentation. If selected resolution corresponds to an index of different type (for example grouping dates to 2-month periods), conversion takes place.

This method differs from cut.POSIXt and cut.Date in two aspects. Firstly, the periods are selected differently, they are always aligned to resolution, see Examples. Secondly, as it does not rely on seq but rounding of indices, the levels may be discontinuous. If users want to replicate behaviour of cut from base, they should provide tind constructed via seq.tind method as breaks argument.

When breaks is a tind object, it is expected to be sorted without NAs. By default, indices in x are matched to the closest index to the left (largest index that is not greater than the argument). If right is set to TRUE, indices are matched to the closest index to the right (smallest index that is not smaller than the argument). right cannot be set to TRUE if breaks is not a tind. It is acceptable that breaks is of lower resolution than x provided that x is convertible to it. In such situations, right cannot be set to TRUE.

By default, cut.tind returns a factor with levels created using as.character method. If labels argument is set to FALSE, only the integer vector (of the same length as argument) of mappings to intervals is returned (as in base method). If set to NA, a 2-element list is returned, with integer vector of mappings as the first element and time indices determining intervals (grouping, levels) as the second. labels can only take TRUE/FALSE/NA values.

Examples

Run this code

# basic use
(d <- seq.tind("2023-09-14", "2023-12-16"))
cut(d, "15d")
cut(d, "m")
cut(d, "2m")
# tind given as breaks
cut(d, as.date(c("2023-09-01", "2023-11-16", "2023-12-16")))
cut(d, seq.tind("2023-01", "2023-12"))
# random order with NAs
(d <- sample(c(d, NA)))
cut(d, "15d")
cut(d, "m")
cut(d, "2m")
# different behaviour of cut for tind and Date (alignment to 2 month resolution,
# which means Jan, Mar, May, Jul, Sep, Nov)
(d <- seq.tind("2023-12-16", "2024-03-01"))
cut(d, "2 months")
cut(as.Date(d), "2 months")
# replicate behviour of cut.Date by providing sequence of months
cut(d, seq.tind("2023-12", "2024-03", by = "2m"))
# same
cut(d, seq.tind(as.month(min(d)), as.month(max(d)), by = "2m"))
# check
all.equal(cut(as.Date(d), "2 months", labels = FALSE),
          cut(d, seq.tind("2023-12", "2024-03", by = "2m"), labels = FALSE))