bin: Bin series
In descstat: Tools for Descriptive Statistics

Description Usage Arguments Details Value Author(s) Examples

A new class called bin is provided, along with different functions which enable to deal easily with bins, ie creating bin objects (as_bin) coercing bins to numerical values (as_numeric), merging bins (cut) and checking than an object is a bin (is_bin).

as_bin(x)

is_bin(x)

as_numeric(x, pos = 0, xfirst = NULL, xlast = NULL, wlast = NULL)

## S3 method for class 'bin'
cut(x, breaks = NULL, ...)

## S3 method for class 'character'
cut(x, breaks = NULL, ...)

## S3 method for class 'factor'
cut(x, breaks = NULL, ...)

## S3 method for class 'character'
extract(data, ..., .name_repair = "check_unique")

## S3 method for class 'factor'
extract(data, ..., .name_repair = "check_unique")

`x`	a character or a factor: the first and last characters should be any of `[`, `(`, `]`, `)` and the other characters should be interpreted as two numerical values separated by a comma,
`pos`	a numeric between 0 and 1, 0 for the lower bond, 1 for the upper bond, 0.5 for the center of the class (or any other value between 0 and 1), which indicates to `as_numeric` how the bins should be coerced to numerical values,
`xfirst, xlast`	the center of the first (last) class, if one wants to specify something different from the average of the lower and the upper bonds,
`wlast`	in the case where the upper bond is infinite and `xlast` is not provided, the width of the last class is set to the one of the before last class. If `wlast` is provided, it is set to the width of the before last class times `wlast`,
`breaks`	a numerical vector of breaks which should be a subset of the initial set of breaks. If only one break is provided, all the bins with greater values are merged,
`...`	see `base::cut()` for the `cut` method and `tidyr::extract()` for the `extract` method,
`data`	a character or a factor containing bins,
`.name_repair`	see `tidyr::extract()`.

extract methods for characters and factors are provided which split the character strings in a four tibble columns: the open bracket, the lower bound, the upper bound and the closing bracket.
as_bin takes as argument a character or a factor that represents a bin, check the consistency of the string and return a bin object with levels in the correct order and NAs when the strings are malformed,
the default cut method takes a numerical series as argument and returns a factor containing bins according to a break vector; for the bin's method, the break should be a subset of the original set of breaks and a bin with fewer levels results,
as_numeric converts a bin to a value of the underlying variable defined by its relative position (from 0 lower bound to 1 upper bound in the bin),
is_bin check if the argument is a bin.

as_bin returns a bin object, is_bin a logical, the extract method a tibble, as_numeric a numeric and the cut method a bin object with fewer levels.

Yves Croissant

# create a factor containing bins using cut on a numeric
z <- c(1, 5, 10, 12, 4, 9, 8)
bin1 <- cut(z, breaks = c(1, 8, 12, Inf), right = FALSE)
# extract the elements of the levels in a tibble
extract(bin1)
# coerce to a bin object
bin2 <- as_bin(bin1)
# coerce to a numeric using the center of the bins
as_numeric(bin2, pos = 0.5)
# special values for the center of the first and of the last bin
as_numeric(bin2, pos = 0.5, xfirst = 5, xlast = 16)
# same, but indicating that the width of the last class should be
# twice the one of the before last
as_numeric(bin2, pos = 0.5, xfirst = 5, wlast = 2)
# merge in order to get only two bins
cut(bin2, breaks = c(1, 12))
# if length of breaks is 1, this is the value for which all the bins
# containing greater values are merged
cut(bin2, breaks = 8)
# check that bin1 and bin2 are objects of class bin
is_bin(bin1)
is_bin(bin2)