factor2: Combine values to factor levels

View source: R/utils.R

factor2R Documentation

Combine values to factor levels

Description

Convenience function to combine level(s) of a vector into a new or existing factor level(s) by unique value and/or regular expression.

Requires R >= 3.5.0 for duplicated labels in factors. For R < 3.5.0, see combine_levels.

Usage

factor2(
  x = character(0L),
  levels = NULL,
  exclude = NA,
  ordered = is.ordered(x),
  regex = FALSE,
  keep.na = TRUE,
  ...
)

Arguments

x

a vector of data, usually taking a small number of distinct values

levels

a named list of unique values or regular expressions to group elements of x

a NULL group will collapse all non matches to a single category; however, if there is no NULL group, non matches will be unchanged

if regex = TRUE or flagged with (?r), matching elements of x will be combined

exclude, ordered

passed to factor

regex

logical; if TRUE, levels is treated as a list of regular expressions or otherwise matched exactly (unless levels is flagged with (?r))

keep.na

logical; if TRUE, NA values in x will be kept, useful for levels = list(label = NULL) situations where NA should be unchanged (or changed if keep.na = FALSE)

...

additional arguments passed to grep when using regular expressions

See Also

combine_levels; combine_regex

Examples

## combine numeric, character, or factor
x <- rep(1:5, each = 2)
factor2(x, list('1' = 1:2))
factor2(x, list(a = 1:2, b = 3))    ## all non matches unchanged
factor2(x, list(a = 1:2, b = NULL)) ## all non matches grouped to b

## levels may be swapped without losing original distinction
factor2(x, list('3' = 1:2, '1' = 3))
factor2(x, list('1' = 3, '3' = 1:2))

## combine by regular expression
x <- letters[1:5]
factor2(x, list(a = c('a', 'b')), regex = TRUE)
factor2(x, list(a = c('a|b')), regex = TRUE) ## same
factor2(x, list(a = 'a', b = 'b|c|e'), regex = TRUE)

## use regex only when flagged with (?r)
## note: must use regex = FALSE, otherwise all are treated as regex
x <- c('a', 'aaa', 'abc', 'def')
factor2(x, list(a = 'a', b = '(?r)a.', d = '(?r)d'))
factor2(x, list(a = 'a', b = '(?r)a.', d = 'd'))

## working with NAs
x <- c(1:5, NA)
# factor(x, x, c(1:5, 5), exclude = NA) ## default for factor - error
factor(x, x, c(1:5, 5), exclude = FALSE) ## converts NA
factor2(x, list(x = NULL), exclude = FALSE, keep.na = FALSE) ## converts NA
factor2(x, list(x = NULL), keep.na = TRUE) ## keeps NA


raredd/rawr documentation built on May 19, 2024, 1:02 p.m.