Change or append a variable translation to an existing lama_dictionary object

The functions lama_mutate() and lama_mutate_() alter a lama_dictionary object. They can be used to alter, delete or append a translations to a lama_dictionary object. The function lama_mutate() uses named arguments to assign the translations to the new names (similar to dplyr::mutate), whereas the function lama_mutate_() is takes a character string key holding the name to which the translation should be assigned and a named character vector translation holding the actual translation mapping.

lama_mutate(.data, ...)

# S3 method for lama_dictionary
lama_mutate(.data, ...)

lama_mutate_(.data, key, translation)

# S3 method for lama_dictionary
lama_mutate_(.data, key, translation)

Arguments

.data	A lama_dictionary object
...	One or more unquoted expressions separated by commas. Use named arguments, e.g. new_transation_name = c(a = "A", b = "B"), to set translations (named character vectors) to new translation names. If you want to delete an existing translation assign the value NULL (e.g. old_translation = NULL). It is also possible use complex expressions as long as the resulting object is a valid translation object (named character vector). Furthermore, it is possible to use translation names that are already existing in the dictionary, in order to modify them (e.g. new_translation = c(v = "V", w = "W", old_translation, z = "Z"), where old_translation = c(x = "X", y = "Y")).
key	The name of the variable translation that should be altered. It can also be variable translation name that does not exist yet.
translation	A named character vector holding the new variable translation that should be assigned to the name given in argument key. The names of the character vector translation correspond to the original variable values that should be replaced by the new labels. The values in the character vector translations are the labels that should be assigned to the original values.

Value

An updated lama_dictionary class object.

See also

lama_translate(), lama_to_factor(), lama_translate_all(), lama_to_factor_all(), new_lama_dictionary(), as.lama_dictionary(), lama_rename(), lama_select(), lama_merge(), lama_read(), lama_write()

Examples

  # initialize lama_dictinoary
  dict <- new_lama_dictionary(
    subject = c(en = "English", ma = "Mathematics"),
    result = c("1" = "Very good", "2" = "Good", "3" = "Not so good")
  )

  ## Example-1: mutate and append with 'lama_mutate'
  # add a few subjects and a few grades
  dict_new <- lama_mutate(
    dict,
    subject = c(bio = "Biology", subject, sp = "Sports"),
    result = c("0" = "Beyond expectations", result, "4" = "Failed", NA_ = "Missed")
  )
  # the subjects "Biology" and "Sports" were added
  # and the results "Beyond expectations", "Failed" and "Missed"
  dict_new
#> 
#> --- lama_dictionary ---
#> Variable 'subject':
#>           bio            en            ma            sp 
#>     "Biology"     "English" "Mathematics"      "Sports" 
#> 
#> Variable 'result':
#>                     0                     1                     2 
#> "Beyond expectations"           "Very good"                "Good" 
#>                     3                     4                   NA_ 
#>         "Not so good"              "Failed"              "Missed" 
#> 

  ## Example-2: delete with 'lama_mutate'
  dict_new <- lama_mutate(
    dict,
    subject = NULL
  )
  dict_new
#> 
#> --- lama_dictionary ---
#> Variable 'result':
#>             1             2             3 
#>   "Very good"        "Good" "Not so good" 
#> 

  ## Example-3: Alter and append with 'lama_mutate_'
  # generate the new translation (character string)
  subj <- c(
    bio = "Biology",
    lama_get(dict, subject),
    sp = "Sports"
  )
  # save the translation under the name "subject"
  dict_new <- lama_mutate_(
    dict,
    key = "subject",
    translation = subj
  )
  # the translation "subject" now also contains
  # the subjects "Biology" and "Sports"
  dict_new
#> 
#> --- lama_dictionary ---
#> Variable 'subject':
#>           bio            en            ma            sp 
#>     "Biology"     "English" "Mathematics"      "Sports" 
#> 
#> Variable 'result':
#>             1             2             3 
#>   "Very good"        "Good" "Not so good" 
#> 

  ## Example-4: Delete with 'lama_mutate_'
  # save the translation under the name "subject"
  dict_new <- lama_mutate_(
    dict,
    key = "subject",
    translation = NULL
  )
  # the translation "subject" was deleted
  dict_new
#> 
#> --- lama_dictionary ---
#> Variable 'result':
#>             1             2             3 
#>   "Very good"        "Good" "Not so good" 
#>