cut.integer: Create Bins for Numeric vectors
In jonmcalder/refactor: Better factor handling for R

Description Usage Arguments Details Value Examples

View source: R/cut.integer.R

cut divides the range of x into intervals and codes the values in x according to the interval they fall into.

## S3 method for class 'integer'
cut(x, breaks, labels = NULL, include.lowest = TRUE,
  right = TRUE, ordered_result = FALSE, breaks_mode = "default",
  label_sep = "-", ...)

`x`	A numeric vector which is to be converted to a factor by cutting.
`breaks`	Either an integer vector of two or more unique cut points or a single integer (greater than or equal to 2) giving the number of intervals into which `x` is to be cut. Please note, however, that the resulting number of intervals is not guaranteed to be `breaks` in the case of `breaks_mode = 'pretty'`.
`labels`	Labels for the levels of the resulting category. By default, labels are constructed using "a-b c-d" interval notation. 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 that unlike `cut.default`, here `include.lowest` defaults to `TRUE`, since this is more intuitive for integer intervals.
`right`	Logical, indicating how to create the bins. This is utilized in different ways based on the type of breaks argument. In the conventional case, where a breaks vector is supplied, `right = TRUE` indicates that bins should be closed on the right (and open on the left) or vice versa (i.e. as in `cut.default`). If a single integer breaks value is provided, then the appropriate breakpoints are determined based on the value of `breaks_mode`, and the value for `right` is not utilized if `breaks_mode = 'pretty'` - see below for details.
`ordered_result`	Logical: should the result be an ordered factor?
`breaks_mode`	A parameter indicating how to determine the intervals when breaks is specified as a scalar (note that this argument has no effect if breaks is specified as a vector). Can be 'default', 'spread' or 'pretty'. See 'Details' below.
`label_sep`	A single or short character string used to generate labels for the intervals e.g. the default value of "-" will result in labels like 1-10 11-20 21-30 etc.
`...`	Further arguments to be passed to or from other methods, in particular to `cut.default`.

In deviation from cut.default, cut.integer does not have an argument dig.lab, but instead has two arguments that do not exist for cut.default: breaks_mode and label_sep.
Note that unlike cut.default, here include.lowest defaults to TRUE, since this is more intuitive for the class integer.
If breaks is supplied as a scalar, the value of breaks_mode determines how the breaks are constructed:

'default' will produce intervals which are the (integer) equivalent to those produced by cut.default i.e. the bins/groupings will be the same - but the labels will be of the form int-int/2-4 instead of (numeric, numeric]/(1.5,4.2].
'spread' will result in intervals spread as evenly as possible over the exact range of x. If the intervals cannot all be equal, then right determines whether the rightmost (TRUE) or leftmost (FALSE) intervals are made slightly wider.
'pretty' will generate rounded breakpoints for the intervals based on pretty. Note that breaks here is treated as the 'desired' number of intervals and is not guaranteed. Note also that the range of x can be exceeded slightly by the intervals in some cases.

A factor is returned, unless labels = FALSE which results in an integer vector of level codes.

 random <- sample(11)
  # nice labels compared to default
 cut(random, breaks = seq(0, 100, by = 10))[1:10]
 cut.default(random, breaks = seq(0, 100, by = 10))[1:10]
 
 cut(random, breaks = 2) # create two bins
 cut(sample(10), breaks = c(1, 6, 8, 9, 10)) # nice labels if binwidth is one
 cut(random, breaks = 2, label_sep = " to ") # other label separator
 cut(random, breaks = c(1, 8, 11), right = FALSE) # bins closed on right
 # if uneven, make right bin slightly larger
 cut(random, breaks = 2, breaks_mode = "spread", right = TRUE) 
 ## Not run: 
 # warnings
 cut(sample(10), breaks = c(0, 3, 5)) # missing values
 cut(sample(10), breaks = c(10, 0, 3)) # unordered breaks
 cut(sample(10), breaks = c(1, 2.6, 5.1, 10)) # non-integer breakpoints
 
## End(Not run)