var_label: Get / Set a variable label

In labelled: Manipulating Labelled Data

Get / Set a variable label

Description

Get / Set a variable label

Usage

var_label(x, ...)

## S3 method for class 'data.frame'
var_label(
  x,
  unlist = FALSE,
  null_action = c("keep", "fill", "skip"),
  recurse = FALSE,
  ...
)

var_label(x) <- value

get_variable_labels(x, ...)

set_variable_labels(.data, ..., .labels = NA, .strict = TRUE)

label_attribute(x)

get_label_attribute(x)

set_label_attribute(x, value)

label_attribute(x) <- value

Arguments

x	a vector or a data.frame
...	name-value pairs of variable labels (see examples)
unlist	for data frames, return a named vector instead of a list
null_action	for data frames, by default NULL will be returned for columns with no variable label. Use "fill" to populate with the column name instead, or "skip" to remove such values from the returned list.
recurse	if TRUE, will apply var_label() on packed columns (see tidyr::pack()) to return the variable labels of each sub-column; otherwise, the label of the group of columns will be returned.
value	a character string or NULL to remove the label For data frames, with var_labels(), it could also be a named list or a character vector of same length as the number of columns in x.
.data	a data frame or a vector
.labels	variable labels to be applied to the data.frame, using the same syntax as value in var_label(df) <- value.
.strict	should an error be returned if some labels doesn't correspond to a column of x?

Details

get_variable_labels() is identical to var_label().

For data frames, if you are using ⁠var_label()<-⁠ and if value is a named list, only elements whose name will match a column of the data frame will be taken into account. If value is a character vector, labels should be in the same order as the columns of the data.frame.

If you are using ⁠label_attribute()<-⁠ or set_label_attribute() on a data frame, the label attribute will be attached to the data frame itself, not to a column of the data frame.

If you are using packed columns (see tidyr::pack()), please read the dedicated vignette.

Value

set_variable_labels() will return an updated copy of .data.

Note

set_variable_labels() could be used with dplyr syntax.

Examples

var_label(iris$Sepal.Length)
var_label(iris$Sepal.Length) <- "Length of the sepal"
## Not run: 
View(iris)

## End(Not run)
# To remove a variable label
var_label(iris$Sepal.Length) <- NULL
# To change several variable labels at once
var_label(iris) <- c(
  "sepal length", "sepal width", "petal length",
  "petal width", "species"
)
var_label(iris)
var_label(iris) <- list(
  Petal.Width = "width of the petal",
  Petal.Length = "length of the petal",
  Sepal.Width = NULL,
  Sepal.Length = NULL
)
var_label(iris)
var_label(iris, null_action = "fill")
var_label(iris, null_action = "skip")
var_label(iris, unlist = TRUE)

#
if (require(dplyr)) {
  # adding some variable labels
  df <- tibble(s1 = c("M", "M", "F"), s2 = c(1, 1, 2)) %>%
    set_variable_labels(s1 = "Sex", s2 = "Yes or No?")
  var_label(df)

  # removing a variable label
  df <- df %>% set_variable_labels(s2 = NULL)
  var_label(df$s2)

  # Set labels from dictionary, e.g. as read from external file
  # One description is missing, one has no match
  description <- tibble(
    name = c(
      "Sepal.Length", "Sepal.Width", "Petal.Length", "Petal.Width",
      "Something"
    ),
    label = c(
      "Sepal length", "Sepal width", "Petal length", "Petal width",
      "something"
    )
  )
  var_labels <- setNames(as.list(description$label), description$name)
  iris_labelled <- iris %>%
    set_variable_labels(.labels = var_labels, .strict = FALSE)
  var_label(iris_labelled)

  # defining variable labels derived from variable names
  if (require(snakecase)) {
    iris <- iris %>%
      set_variable_labels(.labels = to_sentence_case(names(iris)))
    var_label(iris)
  }

  # example with a vector
  v <- 1:5
  v <- v %>% set_variable_labels("a variable label")
  v
  v %>% set_variable_labels(NULL)
}

labelled documentation built on May 29, 2024, 9:34 a.m.