var_label: Get or Set a Variable Label

In dataset: Create Data Frames for Exchange and Reuse

Get or Set a Variable Label

Description

Adds or retrieves a human-readable label as a metadata attribute for a variable or vector. This label is useful for making variables easier to understand than their programmatic names (e.g., column names).

label_attribute() is a low-level helper that retrieves the "label" attribute of an object without any fallback or printing logic. It is primarily used internally.

The ⁠var_label<-⁠ assignment method sets or removes the "label" attribute of a vector or data frame column. This allows attaching human-readable descriptions to variables for interpretability and downstream metadata use.

Usage

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

label_attribute(x)

var_label(x) <- value

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

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

Arguments

x	A vector or data frame.
...	Further arguments passed to or used by methods.
value	A character string to assign as the label, or NULL to remove it.
unlist	For data frames, return a named vector instead of a list.
null_action	For data frames, controls how to handle columns without a variable label. Options are: "keep" (default): keep NULL for unlabeled columns "fill": use the column name as a fallback "skip": exclude columns with no label from the result "na": use NA_character_ "empty": use an empty string ""
recurse	If TRUE, applies var_label() recursively on packed columns (as created by tidyr::pack()) to retrieve sub-column labels. If FALSE, only the outer (grouped) column label is returned.

Details

This interface builds on labelled::var_label() and is compatible with the defined() infrastructure for semantic metadata (labels, namespaces, units, and variable identifiers).

See labelled::var_label() for low-level usage. For a comprehensive guide to working with variable labels and semantic metadata, see: vignette("defined", package = "dataset").

Value

• var_label(x) returns the "label" attribute of x as a character string.

• var_label(x) <- value sets, removes, or replaces the label attribute of x, returning the updated object invisibly.

A character string if the "label" attribute exists, or NULL if not present.

The modified object x, returned invisibly with the updated "label" attribute.

See Also

labelled::var_label(), var_labels(), defined()

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

Examples

# Retrieve the label attribute
var_label(orange_df$circumference)

# Set or update the label attribute
var_label(orange_df$circumference) <- "circumference (breast height)"

# Example: Retrieve variable labels from a dataset_df
df <- dataset_df(
  id = defined(1:3, label = "Observation ID"),
  temp = defined(c(22.5, 23.0, 21.8), label = "Temperature (°C)"),
  site = defined(c("A", "B", "A"))
)

# List form (default)
var_label(df)

# Character vector form
var_label(df, unlist = TRUE, null_action = "empty")

# Exclude variables without labels
var_label(df, null_action = "skip")

# Replace missing labels with column names
var_label(df, null_action = "fill")

dataset documentation built on Nov. 16, 2025, 5:06 p.m.