--- title: "A Few Notes on Labels" author: "Ethan Heinzen" output: rmarkdown::html_vignette: toc: true vignette: | %\VignetteIndexEntry{A Few Notes on Labels} %\VignetteEncoding{UTF-8} %\VignetteEngine{knitr::rmarkdown} --- ```{r include = FALSE} knitr::opts_chunk$set(message = FALSE, results = 'asis') ``` # Introduction The `arsenal` package relies somewhat heavily on variable labels to make output more "pretty". A `label` here is understood to be a single character string with "pretty" text (i.e., not an "ugly" variable name). Three of the main `arsenal` function use labels in their `summary()` output. There are several ways to set these labels. We'll use the `mockstudy` dataset for all examples here: ```{r} library(arsenal) data(mockstudy) library(magrittr) # for 'freqlist' examples tab.ex <- table(mockstudy[c("arm", "sex", "mdquality.s")], useNA="ifany") ``` # Examples ## Set labels in the function call The `summary()` method for `tableby()`, `modelsum()`, and `freqlist()` objects contains a `labelTranslations = ` argument to specify labels in the function call. Note that the `freqlist()` function matches labels in order, whereas the other two match labels by name. The labels can be input as a list or a character vector. ```{r} summary(freqlist(tab.ex), labelTranslations = c(arm = "Treatment Arm", sex = "Gender", mdquality.s = "LASA QOL")) summary(tableby(arm ~ sex + age, data = mockstudy), labelTranslations = c(sex = "SEX", age = "Age, yrs")) summary(modelsum(bmi ~ age, adjust = ~sex, data = mockstudy), labelTranslations = list(sexFemale = "Female", age = "Age, yrs")) ``` ## Modify labels after the fact Another option is to add labels after you have created the object. To do this, you can use the form `labels(x) <- value` or use the pipe-able version, `set_labels()`. ```{r} # the non-pipe version; somewhat clunky tmp <- freqlist(tab.ex) labels(tmp) <- c(arm = "Treatment Arm", sex = "Gender", mdquality.s = "LASA QOL") summary(tmp) # piped--much cleaner mockstudy %>% tableby(arm ~ sex + age, data = .) %>% set_labels(c(sex = "SEX", age = "Age, yrs")) %>% summary() mockstudy %>% modelsum(bmi ~ age, adjust = ~ sex, data = .) %>% set_labels(list(sexFemale = "Female", age = "Age, yrs")) %>% summary() ``` ## Add labels to a `data.frame` `tableby()` and `modelsum()` also allow you to have label attributes on the data. Note that by default these attributes usually get dropped upon subsetting, but `tableby()` and `modelsum()` use the `keep.labels()` function to retain them. ```{r} mockstudy.lab <- keep.labels(mockstudy) class(mockstudy$age) class(mockstudy.lab$age) ``` To undo this, simply `loosen.labels()`: ```{r} class(loosen.labels(mockstudy.lab)$age) ``` You can set attributes one at a time in two ways: ```{r} attr(mockstudy.lab$sex, "label") <- "Sex" labels(mockstudy.lab$age) <- "Age, yrs" ``` ...or all at once: ```{r} labels(mockstudy.lab) <- list(sex = "Sex", age = "Age, yrs") summary(tableby(arm ~ sex + age, data = mockstudy.lab)) ``` You can pipe this, too. ```{r} mockstudy %>% set_labels(list(sex = "SEX", age = "Age, yrs")) %>% modelsum(bmi ~ age, adjust = ~ sex, data = .) %>% summary() ``` To extract labels from a `data.frame`, simply use the `labels()` function: ```{r results='markdown'} labels(mockstudy.lab) ``` ## When labels get long `tableby()` and `modelsum()` both support the wrapping of long labels. Consider the `width=` argument in the `print()` function: ```{r} mockstudy %>% set_labels(list(age = "This is a really long label for the arm variable")) %>% tableby(sex ~ age, data = .) %>% summary() %>% print(width = 20) ```