R: Retrieve value labels of labelled data

get_labels {sjlabelled} | R Documentation

## Retrieve value labels of labelled data

### Description

This function returns the value labels of labelled data.

### Usage

    get_labels(x, attr.only = FALSE, include.values = NULL,
      include.non.labelled = FALSE, drop.na = TRUE, drop.unused = FALSE)

### Arguments

`x` | A data frame with variables that have value label attributes (e.g. from an imported SPSS, SAS or STATA data set, via `read_spss`, `read_sas` or `read_stata`); a variable (vector) with value label attributes; or a `list` of variables with values label attributes. If `x` has no label attributes, factor levels are returned. See 'Examples'.
`attr.only` | Logical, if `TRUE`, labels are only searched for in the the vector's `attributes`; else, if `attr.only = FALSE` and `x` has no label attributes, factor levels or string values are returned. See 'Examples'.
`include.values` | String, indicating whether the values associated with the value labels are returned as well. If `include.values = "as.name"` (or `include.values = "n"`), values are set as `names` attribute of the returned object. If `include.values = "as.prefix"` (or `include.values = "p"`), values are included as prefix to each label. See 'Examples'.
`include.non.labelled` | Logical, if `TRUE`, values without labels will also be included in the returned labels (see `fill_labels`).
`drop.na` | Logical, whether labels of tagged NA values (see `tagged_na`) should be included in the return value or not. By default, labelled (tagged) missing values are not returned. See `get_na` for more details on tagged NA values.
`drop.unused` | Logical, if `TRUE`, unused labels will be removed from the return value.

### Details

This package can add (and read) value and variable labels either in foreign package style (attributes are named value.labels and variable.label) or in haven package style (attributes are named labels and label). By default, the haven package style is used.
Working with labelled data is a key feature of the sjPlot package, which accesses these attributes to automatically read label attributes for labelling axis categories and titles or table rows and columns in graphical or tabular outputs.
When working with labelled data, you can, e.g., use `get_label` or `get_labels` to get a vector of value and variable labels, which can then be used with other functions like `barplot` etc. See 'Examples'. Furthermore, value and variable labels are used when saving data, e.g. to SPSS (see `write_spss`), which means that the written SPSS file contains proper labels for each variable.

### Value

Either a list with all value labels from all variables if `x` is a `data.frame` or `list`; a string with the value labels, if `x` is a variable; or `NULL` if no value label attribute was found.

### Note

This function works with vectors that have value and variable label attributes (as provided, for instance, by `labelled` objects). Adding label attributes is automatically done when importing data sets with the `read_spss`, `read_sas` or `read_stata` functions. Labels can also manually be added using the `set_labels` and `set_label` functions. If vectors do not have label attributes, either factor-levels or the numeric values of the vector are returned as labels.
Most functions of the sjPlot package make use of value and variable labels to automatically label axes, legend or title labels in plots (`sjp.`-functions) respectively column or row headers in table outputs (`sjt.`-functions).

### See Also

See vignette Labelled Data and the sjlabelled-Package for more details; `set_labels` to manually set value labels, `get_label` to get variable labels and `get_values` to retrieve the values associated with value labels.

### Examples

    # import SPSS data set
    # mydat <- read_spss("my_spss_data.sav")

    # retrieve variable labels
    # mydat.var <- get_label(mydat)

    # retrieve value labels
    # mydat.val <- get_labels(mydat)

    data(efc)
    get_labels(efc$e42dep)

    # simple barplot
    barplot(table(efc$e42dep))
    # get value labels to annotate barplot
    barplot(table(efc$e42dep),
            names.arg = get_labels(efc$e42dep),
            main = get_label(efc$e42dep))

    # include associated values
    get_labels(efc$e42dep, include.values = "as.name")

    # include associated values
    get_labels(efc$e42dep, include.values = "as.prefix")

    # get labels from multiple variables
    get_labels(list(efc$e42dep, efc$e16sex, efc$e15relat))

    # create a dummy factor
    f1 <- factor(c("hi", "low", "mid"))
    # search for label attributes only
    get_labels(f1, attr.only = TRUE)
    # search for factor levels as well
    get_labels(f1)

    # same for character vectors
    c1 <- c("higher", "lower", "mid")
    # search for label attributes only
    get_labels(c1, attr.only = TRUE)
    # search for string values as well
    get_labels(c1)

    # 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.values = FALSE)
    # get labels for labelled values only
    get_labels(x)
    # get labels for all values
    get_labels(x, include.non.labelled = TRUE)

    # get labels, including tagged NA values
    library(haven)
    x <- labelled(c(1:3, tagged_na("a", "c", "z"), 4:1),
                  c("Agreement" = 1, "Disagreement" = 4, "First" = tagged_na("c"),
                    "Refused" = tagged_na("a"), "Not home" = tagged_na("z")))
    # get current NA values
    x
    get_labels(x, include.values = "n", drop.na = FALSE)

    # create vector with unused labels
    data(efc)
    efc$e42dep <- set_labels(
      efc$e42dep,
      labels = c("independent" = 1, "dependent" = 4, "not used" = 5)
    )
    get_labels(efc$e42dep)
    get_labels(efc$e42dep, drop.unused = TRUE)
    get_labels(efc$e42dep, include.non.labelled = TRUE, drop.unused = TRUE)

[Package sjlabelled version 1.0.10 Index]