Get / Set a variable label

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)

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

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

Arguments

x

a vector or a data.frame

...

Further potential parameters reserved for inherited classes.

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.

Value

var_label() returns 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.

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.

See also

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

Examples

# Retrieve the label attribute:
var_label(orange_df$circumference)
#> [1] "circumference at breast height"

# To (re)set the label attribute:
`var_label<-`(orange_df$circumference, "circumference (breast height)")
#> Defined as https://www.wikidata.org/wiki/Property:P2043, measured in milimeter 
#>  [1]  30  58  87 115 120 142 145  33  69 111 156 172 203 203  30  51  75 108 115
#> [20] 139 140  32  62 112 167 179 209 214  30  49  81 125 142 174 177