R: Convert variable into character vector and replace values...

to_character {sjmisc} | R Documentation

## Convert variable into character vector and replace values with associated value labels

### Description

This function converts (replaces) variable values (also of factors or character vectors) with their associated value labels and returns them as character vector. This is just a convenient wrapper for `as.character(to_label(x))`.

### Usage

    to_character(x, ..., add.non.labelled = FALSE, prefix = FALSE,
      var.label = NULL, drop.na = TRUE, drop.levels = FALSE)

### Arguments

`x` | A vector or data frame.
`...` | Optional, unquoted names of variables that should be selected for further processing. Required, if `x` is a data frame (and no vector) and only selected variables from `x` should be processed. You may also use functions like `:` or tidyselect's `select_helpers`. See 'Examples' or package-vignette.
`add.non.labelled` | Logical, if `TRUE`, values without associated value label will also be converted to labels (as is). See 'Examples'.
`prefix` | Logical, if `TRUE`, the value labels used as factor levels or character values will be prefixed with their associated values. See 'Examples'.
`var.label` | Optional string, to set variable label attribute for the returned variable (see vignette Labelled Data and the sjlabelled-Package). If `NULL` (default), variable label attribute of `x` will be used (if present). If empty, variable label attributes will be removed.
`drop.na` | Logical, if `TRUE`, tagged `NA` values with value labels will be converted to regular NA's. Else, tagged `NA` values will be replaced with their value labels. See 'Examples' and `get_na`.
`drop.levels` | Logical, if `TRUE`, unused factor levels will be dropped (i.e. `droplevels` will be applied before returning the result).

### Value

A character vector with the associated value labels as values. If `x` is a data frame, the complete data frame `x` will be returned, where variables specified in `...` are coerced to character variables; if `...` is not specified, applies to all variables in the data frame.

### Note

Value labels will be removed when converting variables to factors, variable labels, however, are preserved.
This function is kept for backwards-compatibility. It is preferred to use `as_character`.

### Examples

    library(sjlabelled)
    data(efc)
    print(get_labels(efc)['c161sex'])
    head(efc$c161sex)
    head(to_character(efc$c161sex))

    print(get_labels(efc)['e42dep'])
    table(efc$e42dep)
    table(to_character(efc$e42dep))

    head(efc$e42dep)
    head(to_character(efc$e42dep))

    # numeric values w/o value labels will also be converted into character
    str(efc$e17age)
    str(to_character(efc$e17age))

    # factor with non-numeric levels, non-prefixed and prefixed
    x <- factor(c("a", "b", "c"))
    x <- set_labels(x, labels = c("ape", "bear", "cat"))

    to_character(x, prefix = FALSE)
    to_character(x, prefix = TRUE)

    # create vector
    x <- c(1, 2, 3, 2, 4, NA)
    # add less labels than values
    x <- set_labels(x,
                    labels = c("yes", "maybe", "no"),
                    force.labels = FALSE,
                    force.values = FALSE)
    # convert to character w/o non-labelled values
    to_character(x)
    # convert to character, including non-labelled values
    to_character(x, add.non.labelled = TRUE)

    # create labelled integer, with missing flag
    library(haven)
    x <- labelled(c(1:3, tagged_na("a", "c", "z"), 4:1, 2:3),
                  c("Agreement" = 1, "Disagreement" = 4, "First" = tagged_na("c"),
                    "Refused" = tagged_na("a"), "Not home" = tagged_na("z")))
    # to character, with missing labels
    to_character(x, drop.na = FALSE)
    # to character, missings removed
    to_character(x, drop.na = TRUE)
    # keep missings, and use non-labelled values as well
    to_character(x, add.non.labelled = TRUE, drop.na = FALSE)

    # easily coerce specific variables in a data frame to character
    # and keep other variables, with their class preserved
    to_character(efc, e42dep, e16sex, c172code)

[Package sjmisc version 2.7.5 Index]