var_label: Get / Set a variable label

In dataset: Create Data Frames that are Easier to Exchange and Reuse

Get / Set a variable label

Description

Add a human readable, easier to understand label as a metadata attribute to a variable or vector than the programmatic vector object name, or column name in the data frame.

Usage

## S3 method for class 'defined'
var_label(x, ...)

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

label_attribute(x)

var_label(x) <- value

## S3 replacement method for class 'haven_labelled_defined'
var_label(x) <- value

## S3 replacement method for class 'dataset_df'
var_label(x) <- value

Arguments

x	a vector or a data.frame
...	Further arguments passed to or used by methods.
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, "skip" to remove such values from the returned list, "na" to populate with NA or "empty" to populate with an empty string ("").
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.

Details

See labelled::var_label for details about variable labels.
See vignette("defined", package = "dataset") to use comprehensively with variable labels, namespaces, units of measures, and machine-independent permanent variable identifiers.

Value

var_label() returns the label attribute as a character string. The var_label<- assignment method allows to add, remove, or overwrite this attribute on a vector x. The assignment function returns the x vector invisibly.

See Also

Other defined metadata methods and functions: defined(), var_namespace(), var_unit()

Examples

# Retrieve the label attribute:
var_label(orange_df$circumference)

# To (re)set the label attribute:
`var_label<-`(orange_df$circumference, "circumference (breast height)")

dataset documentation built on June 8, 2025, 10:15 a.m.