labeltable: Label Table

The vtable package serves the purpose of outputting automatic variable documentation that can be easily viewed while continuing to work with data.

vtable contains four main functions: vtable() (or vt()), sumtable() (or st()), labeltable(), and dftoHTML()/dftoLaTeX(). This vignette focuses on labeltable().

labeltable() is designed to take a single variable and show the values it is associated with. This can also be used to generate data documentation if desired, or can just be an easy way to look at label values, or learn more about the data you’re working with.

If that variable has value labels from the sjlabelled or haven packages, it will show how the values in the data correspond to the value labels.

Alternately, you can include other variables as well, and labeltable() will show, for each value of the variable you’re interested in, the values that those other variables take. This can be handy, for example, if you used some variables to create a numeric ID and want to remember what original values correspond to each ID. It can also act as sort of a cross-tabulation.

The labeltable() function

vtable() syntax follows the following outline:

labeltable(var,
    ...,
    out=NA,
    count=FALSE,
    percent=FALSE,
    file=NA, 
    desc=NA,
    note=NA,
    note.align=NA,
    anchor=NA)

labeltable() is a function that shows the values that correspond to var. This could be value label values, or it could be the values found in the data for the ... variables.

#Include a single labelled variable to show how the values of that variable correspond to its value labels.
library(vtable)
## Loading required package: kableExtra
library(sjlabelled)
data(efc)
labeltable(efc$e15relat)
e15relat Label
1 spouse/partner
2 child
3 sibling
4 daughter or son -in-law
5 ancle/aunt
6 nephew/niece
7 cousin
8 other, specify 
#Include more than one variable to show, for each value of the first, what values of the others are present in the data.
data(mtcars)
labeltable(mtcars$cyl,mtcars$carb,mtcars$am)
cyl carb am
4 1, 2 1, 0
6 4, 1, 6 1, 0
8 2, 4, 3, 8 0, 1

out

The out option determines what will be done with the resulting label table file. There are several options for out:

Option Result
browser Loads output in web browser.
viewer Loads output in Viewer pane (RStudio only).
htmlreturn Returns HTML code for output file.
return Returns output table in data.frame format.
csv Returns output table in data.frame format and, with a file option, saves that to CSV.
kable Returns a knitr::kable()
latex Returns a LaTeX table.
latexpage Returns an independently-buildable LaTeX document.

By default, vtable will select ‘viewer’ if running in RStudio, and ‘browser’ otherwise. If it’s being built in an RMarkdown document with knitr, it will default to ‘kable’.

count and percent

These options allow labeltable() to act as a sort of table(), where it will also include the counts and/or percentage of the variable that takes each value.

library(vtable)
data(LifeCycleSavings)
labeltable(efc$e15relat, count = TRUE, percent = TRUE)
e15relat Label Count Percent
1 spouse/partner 171 18.98%
2 child 473 52.50%
3 sibling 29 3.22%
4 daughter or son -in-law 85 9.43%
5 ancle/aunt 23 2.55%
6 nephew/niece 22 2.44%
7 cousin 6 0.67%
8 other, specify 92 10.21%

file

The file argument will write the variable documentation file to an HTML file and save it. Will automatically append ‘html’ filetype if the filename does not include a period.

library(vtable)

data(LifeCycleSavings)
labeltable(efc$e15relat,file='lifecycle_variabledocumentation')

desc, note, and anchor.

desc will include a description of the data set (or whatever you like) in the file, which may be useful for documentation purposes.

note will add a table note in the last row.

anchor will add an anchor ID (<a name = in HTML or \label{} in LaTeX) to allow other parts of your document to link to it, if you are including your vtable in a larger document.

desc will only show up in full-page labeltables. That is, you won’t get them with out = 'kable', out = 'return', out = 'csv', or out = 'latex' (although out = 'latexpage' works). note and anchor will only show up in formats that support multi-column cells and anchoring, so they won’t work with out = 'kable', out = 'csv', or out = 'return'.

note.align

This option is used only with LaTeX output (out is ‘latex’ or ‘latexpage’). note.align is a single string used for alignment, specifically for any table notes set with note, which enters as part of a \multicolumn argument. It accepts ‘p{}’ and other LaTeX column types. Be sure to escape special characters, in particular backslashes.