corral: Corral a character vector
In derek-damron/transform: Easy variable transformations in R

Description Usage Arguments Details Value Examples

corral returns a corralled factor vector.

1 2	corral(x, method = c("size", "asis", "name"), groups = NULL, collect = "Other")

`x`	A character vector (or any vector than can be coerced into a character).
`method`	A character string indicating the desired method of corralling with `"size"` being the default. This must be (an abbreviation of) one of the strings `"size"`, `"asis"`, or `"name"`. See Details for more information.
`groups`	Either NULL (all values are kept distinct), a single number with the desired number of groups (floating numbers are truncated), or a vector of values to keep distinct. The default is NULL.
`collect`	Either `NA` or a character string that denotes the name that the "collected" values are given. The default is "Other".

corral returns a corralled vector x. NA values in x are not grouped during the corralling process but are preserved in the output.

corral is designed to be readable from the function call. For example:

corral(x, method="size", groups=5) can be read as "corral x by size into 5 groups".
corral(x, method="asis", groups=c("a","b")) can be read as "corral x as is and keep only a and b distinct".

The output of corral is determined by the arguments method and groups.

corral offers a few different options for method:

size: The default option that corrals x based on the number of occurrences in x.
asis: Corrals x based on the order in which values are observed.
name: Corrals x based on alphanumerical order.

corral accepts either numeric or character values for groups:

numeric: Creates groups groups based on method and combines all other values into the collect category.
character: Creates a group for each value in groups and combines all other values into the collect category.

See the examples for some explicit illustration on how different combinations of method and groups result in different outputs.

The output of corral is a corralled factor vector with the same length as x.

set.seed(1337)
x <- sample(letters, 1e4, replace=TRUE)
summary(x)

#####
# Common use cases
#

# I want to factorize by sample size!
x_all <- corral(x, "size")
summary(x_all)
# All values are kept and ordered by the number of occurrences

# I want to factorize by sample size but only have 5 values!
x_5 <- corral(x, "size", groups=5)
summary(x_5)
# The four most common values are kept and
# everything else is combined into "Other"

# I want to factorize but keep only specific values!
x_bar <- corral(x, "asis", groups=c("b", "a", "r"))
summary(x_bar)
# The values "b", "a", and "r" are explicitly kept and
# leveled based on the order provided (i.e. "b" then "a" then "r")

# I want to change the collected values to NA rather than "Other"!
x_NA <- corral(x, "asis", groups=c("b", "a", "r"), collect=NA)
summary(x_NA)
# The values "b", "a", and "r" are factorized as in the previous example and
# the rest of the values are changed to NA