labvar: Label and recode existing variables

In R4VN: Health Data Analysis and Publication-Ready Reporting

Label and recode existing variables

Description

Adds variable labels, value labels, recodes values, and sets reference categories. The function can edit an explicit data frame or the active R4VN data frame.

Usage

labvar(
  ...,
  data = NULL,
  label = NULL,
  values = NULL,
  recode = NULL,
  ref = NULL,
  ordered = FALSE
)

Arguments

...	Variables to process. For backward compatibility, an explicit data frame may be supplied as the first unnamed argument.
data	Optional explicit data frame object. When omitted, active data is used.
label	A character label or one label per selected variable.
values	A named value-label vector such as c("0" = "No", "1" = "Yes").
recode	A named recode vector such as c("min:12" = 1, "13:17" = 2, "18:max" = 3).
ref	Optional reference category.
ordered	Logical; create an ordered factor.

Details

Explicit-data syntax remains valid:

labvar(data, sex, label = "Sex", values = c("1" = "Male", "2" = "Female"))

After usedf(data), active-data syntax is:

labvar(sex, label = "Sex", values = c("1" = "Male", "2" = "Female"))

When active data were selected with usedf(patient), edits update both the active data and the linked patient object. For an unlinked active copy, retrieve the result with data <- usedf().

Value

The edited data frame invisibly.

Examples

d <- data.frame(sex = c(1, 2, 1), age = c(8, 15, 30))
usedf(d, quiet = TRUE)
labvar(sex, label = "Sex",
       values = c("1" = "Male", "2" = "Female"))
labvar(age,
       recode = c("min:12" = 1, "13:17" = 2, "18:max" = 3),
       label = "Age group",
       values = c("1" = "0-12", "2" = "13-17", "3" = "18+"))

# Extended usage examples

# ------------------------------------------------------------------
# 1. Add only a variable label; numeric values remain numeric
d1 <- data.frame(age = c(18, 25, 40))
labvar(d1, age, label = "Age in years")
attr(d1$age, "label")

# 2. Add value labels; the variable becomes a factor
d2 <- data.frame(sex = c(1, 2, 2, 1))
labvar(d2, sex, label = "Sex",
       values = c("1" = "Male", "2" = "Female"))
levels(d2$sex)

# 3. Set the reference category by stored code
d3 <- data.frame(smoke = c(0, 1, 1, 0))
labvar(d3, smoke, label = "Current smoking",
       values = c("0" = "No", "1" = "Yes"), ref = 0)
levels(d3$smoke)

# 4. Set the reference category by displayed label
d4 <- data.frame(treatment = c(1, 2, 3, 1))
labvar(d4, treatment,
       values = c("1" = "Standard", "2" = "Drug A", "3" = "Drug B"),
       ref = "Standard")

# 5. Create an ordered factor
d5 <- data.frame(severity = c(1, 3, 2, 1))
labvar(d5, severity, label = "Disease severity",
       values = c("1" = "Mild", "2" = "Moderate", "3" = "Severe"),
       ordered = TRUE)
is.ordered(d5$severity)

# 6. Recode inclusive numeric ranges and then label the new categories
d6 <- data.frame(age = c(8, 12, 13, 17, 18, 65))
labvar(d6, age,
       recode = c("min:12" = 1, "13:17" = 2, "18:max" = 3),
       label = "Age group",
       values = c("1" = "0-12", "2" = "13-17", "3" = "18+"))

# 7. Collapse several exact values into one category
d7 <- data.frame(answer = c(1, 2, 3, 2, 1))
labvar(d7, answer,
       recode = c("1" = 1, "2 3" = 0),
       values = c("0" = "No/uncertain", "1" = "Yes"))

# 8. Recode without value labels; the result remains numeric
d8 <- data.frame(score = c(2, 6, 9, 15))
labvar(d8, score,
       recode = c("min:4" = 1, "5:9" = 2, "10:max" = 3),
       label = "Score category code")
is.numeric(d8$score)

# 9. Apply common value labels to several binary variables
d9 <- data.frame(smoke = c(0, 1), alcohol = c(1, 0), exercise = c(1, 1))
labvar(d9, smoke, alcohol, exercise,
       label = c("Smoking", "Alcohol use", "Regular exercise"),
       values = c("0" = "No", "1" = "Yes"))

# 10. Supply labels as a named vector
d10 <- data.frame(sbp = c(120, 130), dbp = c(75, 85))
labvar(d10, sbp, dbp,
       label = c(sbp = "Systolic blood pressure",
                 dbp = "Diastolic blood pressure"))

# 11. Select a contiguous range of variables
d11 <- data.frame(q1 = c(0, 1), q2 = c(1, 0), q3 = c(1, 1), age = c(20, 30))
labvar(d11, q1:q3, values = c("0" = "No", "1" = "Yes"))

# 12. Select variables with a wildcard
d12 <- data.frame(symptom_a = c(0, 1), symptom_b = c(1, 1), age = c(20, 30))
labvar(d12, "symptom_*", values = c("0" = "Absent", "1" = "Present"))

# 13. Use explicit-data syntax
d13 <- data.frame(outcome = c(0, 1, 0))
labvar(d13, outcome, label = "Outcome",
       values = c("0" = "No", "1" = "Yes"), ref = "No")

# 14. Use active-data syntax
d14 <- data.frame(outcome = c(0, 1, 0))
usedf(d14, quiet = TRUE)
labvar(outcome, label = "Outcome",
       values = c("0" = "No", "1" = "Yes"), ref = "No")
d14_active <- usedf(quiet = TRUE)

# 15. Use separate calls when variables need different value-label systems
d15 <- data.frame(sex = c(1, 2), outcome = c(0, 1))
labvar(d15, sex, values = c("1" = "Male", "2" = "Female"))
labvar(d15, outcome, values = c("0" = "No", "1" = "Yes"))

R4VN documentation built on Sept. 30, 2026, 5:13 p.m.