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 dftoHTML()/dftoLaTeX().
dftoHTML() and dftoLaTeX are helper functions used by vtable(), sumtable(), and labeltable(). They takes any data frame or matrix with column names and outputs HTML or LaTeX table code for that data.
Note that none of the vignettes in this example are set to run because dftoHTML and dftoLaTeX output is intended to go to places other than Markdown (although both can certainly be used with ‘asis’ chunks to produce results in Markdown).
dftoHTML() functiondftoHTML() syntax follows the following outline:
dftoHTML(data,
out=NA,
file=NA,
note=NA,
anchor=NA,
col.width=NA,
col.align=NA,
row.names=FALSE,
no.escape=NA)dftoHTML() largely exists to serve vtable(), sumtable(), and labeltable(). What it does is takes a data set data and returns an HTML table with the contents of that data.
Outside of its use with other vtable functions, dftoHTML() can also be used to keep a view of the data file open while working on the data, avoiding repeated calls to head() or similar, or switching back and forth between code tabs and data view tabs.
datadftoHTML() will accept any data set with a colnames() attribute.
library(vtable)
data(LifeCycleSavings)
dftoHTML(LifeCycleSavings)The out option determines what will be done with the resulting variable documentation file. There are several options for out:
| Option | Result |
|---|---|
| browser | Loads HTML version of data in web browser. |
| viewer | Loads HTML version of data in Viewer pane (RStudio only). |
| htmlreturn | Returns HTML code for data. |
By default, vtable will select ‘viewer’ if running in RStudio, and ‘browser’ otherwise.
library(vtable)
data(LifeCycleSavings)
dftoHTML(LifeCycleSavings)
dftoHTML(LifeCycleSavings,out='browser')
dftoHTML(LifeCycleSavings,out='viewer')
htmlcode <- dftoHTML(LifeCycleSavings,out='htmlreturn')fileThe file argument will write the HTML version of data to an HTML file and save it. Will automatically append ‘html’ filetype if the filename does not include a period.
data(LifeCycleSavings)
dftoHTML(LifeCycleSavings,file='lifecycledata_htmlversion.html')notenote will add a table note in the last row.
dftoHTML(LifeCycleSavings,note='Data from Belsley, Kuh, and Welsch 1980').anchoranchor will add an anchor ID (<a name =) to allow other parts of your document to link to it, if you are including your table in a larger document.
col.widthdftoHTML() will select, by default, equal column widths for all columns in data. col.width, as a vector of percentage column widths on the 0-100 scale, will override these defaults.
#Let's make sr much bigger for some reason
dftoHTML(LifeCycleSavings,col.width=c(60,10,10,10,10))col.aligncol.align can be used to adjust text alignment in HTML output. Set to ‘left’, ‘right’, or ‘center’ to align all columns, or give a vector of column alignments to do each column separately.
While this is not intended usage, you can add additional CSS arguments (i.e. 'left; padding:5px') and it will apply that CSS to every cell in the column.
row.namesThe row.names flag determines whether the row names of the data are included as the first column in the output table.
dftoHTML(LifeCycleSavings,row.names=TRUE)no.escapeIf the data passed to dftoHTML() contains special HTML characters like ‘<’, dftoHTML() will escape them. This could cause you some sort of existential crisis if you wanted to put HTML formatting in your data to be displayed. So set no.escape to a vector of column indices to skip the character-escaping process for those columns.
#Don't escape columns 1 or 2
dftoHTML(LifeCycleSavings,no.escape=1:2)dftoLaTeX() functiondftoLaTeX() syntax follows the following outline:
dftoLaTeX(data,
file=NA,
frag=TRUE,
title=NA,
note=NA,
anchor=NA,
align=NA,
row.names=FALSE,
no.escape=NA)dftoLaTeX() largely exists to serve vtable(), sumtable(), and labeltable(). What it does is takes a data set data and returns an LaTeX table with the contents of that data. You could also use it on its own to write any data frame to LaTeX table format.
datadftoLaTeX() will accept any data set with a colnames() attribute.
library(vtable)
data(LifeCycleSavings)
dftoLaTeX(LifeCycleSavings)fileThe file argument will write the TeX version of data to a .tex file and save it. Will automatically append ‘tex’ filetype if the filename does not include a period.
data(LifeCycleSavings)
dftoLaTeX(LifeCycleSavings,file='lifecycledata_latexversion.tex')notenote will add a table note in the last row.
dftoLaTeX(LifeCycleSavings,note='Data from Belsley, Kuh, and Welsch 1980').anchoranchor will add an anchor ID (\label{}) to allow other parts of your document to link to it, if you are including your output in a larger document.
dftoLaTeX(LifeCycleSavings,anchor='tab:LCS')alignThis is a single string, which will be used as column alignment in standard LaTeX syntax, for example ‘lccc’ for the left column left-aligned and the other three centered. Accepts ‘p{}’ and other LaTeX column types. Don’t forget to escape backslashes!
Defaults to all left-aligned.
dftoLaTeX(LifeCycleSavings,row.names=TRUE,align='p{.25\\textwidth}ccccc')row.namesThe row.names flag determines whether the row names of the data are included as the first column in the output table.
dftoLaTeX(LifeCycleSavings,row.names=TRUE)no.escapeIf the data passed to dftoLaTeX() contains special HTML characters like ‘~’ or ‘^’, dftoLaTeX() will escape them. This could cause you some sort of existential crisis if you wanted to put LaTeX formatting in your data to be displayed. So set no.escape to a vector of column indices to skip the character-escaping process for those columns.
#Don't escape columns 1 or 2
dftoLaTeX(LifeCycleSavings,no.escape=1:2)