Recode a Variable

Recodes a numeric vector, character vector, or factor according to simple recode specifications. Recode is an alias for recode that avoids name clashes with packages, such as Hmisc, that have a recode function.

Usage

recode(var, recodes, as.factor, as.numeric=TRUE, levels, 
       to.value="=", interval=":", separator=";")

Recode(...)

Arguments

var

numeric vector, character vector, or factor.

recodes

character string of recode specifications: see below.

as.factor

return a factor; default is TRUE if var is a factor, FALSE otherwise.

as.numeric

if TRUE (the default), and as.factor is FALSE, then the result will be coerced to numeric if all values in the result can represent numbers (contain only numerals, minus signs, etc.).

levels

an optional argument specifying the order of the levels in the returned factor; the default is to use the sort order of the level names.

to.value

The operator to separate old from new values, "=" by default; some other possibilities: "->", "~", "~>". Cannot include the interval operator (by default :) or the separator string (by default, ;), so, e.g., by default ":=>" is not allowed. The discussion in Details assumes the default "=". Use a non-default to.value if factor levels contain =.

interval

the operator used to denote numeric intervals, by default ":". The discussion in Details assumes the default ":". Use a non-default interval if factor levels contain :.

separator

the character string used to separate recode specifications, by default ";". The discussion in Details assumes the default ";". Use a non-default separator if factor levels contain ;.

...

arguments to be passed to recode.

Details

Recode specifications appear in a character string, separated by default by semicolons (see the examples below), each of the form input=output (where = may be replaced by a non-default value of the to.value argument, e.g., input -> output). Spaces may be used for clarity. If an input value satisfies more than one specification, then the first (from left to right) applies. If no specification is satisfied, then the input value is carried over to the result. NA is allowed on input and output. Several recode specifications are supported:

single value

For example, 0=NA.

vector of values

For example, c(7, 8, 9) = 'high'.

range of values

For example, 7:9 = 'C'. The special values lo and hi may appear in a range. For example, lo:10=1. Note: : is not the R sequence operator. In addition, you may not use : with the c function within a recode specification, so for example c(1, 3, 5:7) will cause an error. The : is the default value of the recode interval operator; a non-default value may be specified.

else

everything that does not fit a previous specification. For example, else = NA. Note that else matches all otherwise unspecified values on input, including NA, and if present should appear last among the recode specifications.

Character data and factor levels on the left-hand side of a recode specification must be quoted. Thus, e.g., c(a, b, c) = 'low' is not allowed, and should be c('a', 'b', 'c') = 'low'. Similarly, the colon is reserved for numeric data, and, e.g., c('a':'c') = 'low' is not allowed. If the var argument is a character variable with (some) values that are character representations of numbers, or a factor with (some) levels that are numbers (e.g., '12' or '-2'), then these too must be quoted and cannot be used with colons (e.g., '15':'19' = '15 to 19' is not allowed, and could be specified as c('15', '16', '17', '18', '19') = '15 to 19', assuming that all values are the character representation of whole numbers).

If all of the output values are numeric, and if as.factor is FALSE, then a numeric result is returned; if var is a factor, then by default so is the result.

Value

a recoded vector of the same length as var.

Warning

The factor levels may not contain the character strings in to.value (by default "="), interval (by default ":"), or separator (by default ";").

Author

John Fox jfox@mcmaster.ca

References

Fox, J. and Weisberg, S. (2019) An R Companion to Applied Regression, Third Edition, Sage.

See also

cut, factor

Examples

x <- rep(1:3, 3)
x
#> [1] 1 2 3 1 2 3 1 2 3
recode(x, "c(1, 2) = 'A'; 
           else = 'B'")
#> [1] "A" "A" "B" "A" "A" "B" "A" "A" "B"
Recode(x, "1~2 -> ':=1' // 3 -> ';=2'", to.value="->", 
       interval="~", separator="//")
#> [1] ":=1" ":=1" ";=2" ":=1" ":=1" ";=2" ":=1" ":=1" ";=2"