Skip to contents

Get or Set Value Labels

Source: R/label_management.R
val_labels.Rd

Retrieves or assigns value labels (the "labels" attribute) on labelled vectors or data frame columns. Value labels map numeric codes to descriptive text (e.g., 1 = "Male", 2 = "Female").

The function operates in two modes:

  • GET mode: Called with bare variable names, returns existing value labels.

  • SET mode: Called with name = c(...) pairs, assigns value labels to variables.

Usage

val_labels(data, ..., .add = FALSE, drop.na = TRUE)

Arguments

data

A data frame, tibble, or a single vector.

...

In GET mode: unquoted variable names (tidyselect supported). In SET mode: named pairs where the name is a variable and the value is a named vector of labels (e.g., c("Male" = 1, "Female" = 2)). Use NULL to remove all value labels from a variable.

.add

If TRUE, adds labels to any existing ones instead of replacing them. Default: FALSE.

drop.na

If TRUE (default), tagged NA labels are excluded from GET results.

Value

  • GET mode (vector input): A named numeric vector of value labels, or NULL.

  • GET mode (data frame, single variable): A named numeric vector of value labels.

  • GET mode (data frame, multiple variables): A named list of label vectors.

  • SET mode: The modified data frame (invisibly).

Details

Value labels are stored as the "labels" attribute in haven's format: a named numeric vector where names are the label text and values are the numeric codes. This is the standard used by read_spss(), read_stata(), and read_sas().

Adding vs. Replacing Labels

By default, SET mode replaces all existing value labels. Use .add = TRUE to keep existing labels and only add new ones. If a value already has a label, the new label overwrites it.

See also

var_label() for variable labels, to_label() for converting labelled vectors to factors, drop_labels() for removing unused labels

Other labels: copy_labels(), drop_labels(), find_var(), set_na(), to_character(), to_label(), to_labelled(), to_numeric(), unlabel(), var_label()

Examples

# GET: retrieve value labels from a vector
val_labels(survey_data$gender)
#> NULL

# GET: from specific variables (returns list)
val_labels(survey_data, gender, region)
#> $gender
#> NULL
#> 
#> $region
#> NULL
#> 

# SET: assign value labels
data <- val_labels(survey_data,
  gender = c("Male" = 1, "Female" = 2, "Non-binary" = 3)
)

# ADD: add labels without removing existing ones
data <- val_labels(data,
  gender = c("Prefer not to say" = 4),
  .add = TRUE
)

# REMOVE: set to NULL
data <- val_labels(data, gender = NULL)