recode                package:memisc                R Documentation

_R_e_c_o_d_e _I_t_e_m_s, _F_a_c_t_o_r_s _a_n_d _N_u_m_e_r_i_c _V_e_c_t_o_r_s

_D_e_s_c_r_i_p_t_i_o_n:

     'recode' substitutes old values of a factor or a numeric vector by
     new ones, just like the recoding facilities in some commercial
     statistical packages.

_U_s_a_g_e:

       ## S4 method for signature 'vector':
       recode(x,...,otherwise="NA")
       ## S4 method for signature 'factor':
       recode(x,...,otherwise="NA")
       ## S4 method for signature 'item':
       recode(x,...,otherwise="NA")

_A_r_g_u_m_e_n_t_s:

       x: An object

     ...: One or more assignment expressions, each  of the form
          'new.value <- old.values'. 'new.value' should be a scalar
          numeric value or character string. If one of the 'new.value's
          is a character string, the return value of 'recode' will be a
          factor and each 'new.value' will be coerced to a character
          string that labels a level of the factor.

          Each 'old.value' in an assignment expression may be a
          (numeric or character) vector. If 'x' is numeric such an
          assignment expression may have the form 'new.value <-
          range(lower,upper)' In that case, values between 'lower' and
          'upper' are exchanged by 'new.value'. If one of the arguments
          to 'range' is 'min', it is substituted by the minimum of 'x'.
          If one of the arguments to 'range' is 'max', it is
          substituted by the maximum of 'x'.

          In case of the method for 'labelled' vectors, the _tags_ of
          arguments of the form 'tag = new.value <- old.values' will
          define the labels of the new codes.

          If the 'old.values' of different assignment expressions
          overlap, an error will be raised because the recoding is
          ambigous. 

otherwise: a character string or some other value that the result may
          obtain. If equal to 'NA' or '"NA"', original codes not given
          an explicit new code are recoded into 'NA'. If equal to
          '"copy"', original codes not given an explicit new code are
          copied. 

_D_e_t_a_i_l_s:

     'recode' relies on the lazy evaluation mechanism of _R_: Arguments
     are not evaluated until required by the function they are given
     to. 'recode' does not cause arguments that appear in '...' to be
     evaluated. Instead, 'recode' parses the '...' arguments.
     Therefore, although expressions like '1 <- 1:4' would cause an
     error action, if evaluated at any place elsewhere in _R_, they
     will not cause an error action, if given to 'recode' as an
     argument. However, a call of the form 'recode(x,1=1:4)', would be
     a syntax error.

     If John Fox' package "car" is installed, 'recode' will also be
     callable with the syntax of the 'recode' function of that package.

_V_a_l_u_e:

     A numerical vector, factor or an 'item' object.

_S_e_e _A_l_s_o:

     'recode' of package 'car'.

_E_x_a_m_p_l_e_s:

     x <- as.item(sample(1:6,20,replace=TRUE),
             labels=c( a=1,
                       b=2,
                       c=3,
                       d=4,
                       e=5,
                       f=6))
     print(x)

     # A recoded version of x is returned
     # containing the values 1, 2, 3, which are
     # labelled as "A", "B", "C".
     recode(x,
       A = 1 <- range(min,2),
       B = 2 <- 3:4,
       C = 3 <- range(5,max), # this last comma is ignored
       )

     # This causes an error action: the sets
     # of original values overlap.
     try(recode(x,
       A = 1 <- range(min,2),
       B = 2 <- 2:4,
       C = 3 <- range(5,max)
       ))

     recode(x,
       A = 1 <- range(min,2),
       B = 2 <- 3:4,
       C = 3 <- range(5,6),
       D = 4 <- 7
       )
       
     # This results in an all-missing vector:
     recode(x,
       D = 4 <- 7,
       E = 5 <- 8
       )

     f <- as.factor(x)
     x <- as.integer(x)

     recode(x,
       1 <- range(min,2),
       2 <- 3:4,
       3 <- range(5,max)
       )

     # This causes another error action:
     # the third argument is an invalid
     # expression for a recoding.
     try(recode(x,
       1 <- range(min,2),
       3:4,
       3 <- range(5,max)
       ))

     # The new values are character strings,
     # therefore a factor is returned.
     recode(x,
       "a" <- range(min,2),
       "b" <- 3:4,
       "c" <- range(5,6)
       )
       
     recode(x,
       1 <- 1:3,
       2 <- 4:6
       )
       
     recode(x,
       4 <- 7,
       5 <- 8,
       otherwise = "copy"
       )

     recode(f,
       "A" <- c("a","b"),
       "B" <- c("c","d"),
       otherwise="copy"
       )

     recode(f,
       "A" <- c("a","b"),
       "B" <- c("c","d"),
       otherwise="C"
       )
      
     recode(f,
       "A" <- c("a","b"),
       "B" <- c("c","d")
       )

