The write2*()
functions were designed as an alternative to SAS’s ODS
procedure for useRs who want to save R Markdown tables to separate Word, HTML, or PDF files without needing separate R Markdown programs.
There are three shortcut functions for the most common output types: HTML, PDF, and Word. Each of these three functions calls write2()
, an S3 function which accepts many file output types (see the help pages for rmarkdown::render()
). Methods have been implemented for tableby()
, modelsum()
, and freqlist()
, but also knitr::kable()
, xtable::xtable()
, and pander::pander_return()
.
The two most important things to recognize with write2()
are the following:
Which function is being used to output the object. Sometimes the write2
functions use summary()
, while other times they will use print()
. The details for each object specifically are described below.
How the ...
arguments are passed. To change the options for the summary-like or print-like function, you can pass named arguments which will in turn get passed to the appropriate function. Details for each object specifically are described below.
arsenal
Objectslibrary(arsenal)
data(mockstudy)
tmpdir <- tempdir()
tableby
For tableby
objects, the output function in write2()
is summary()
. For available arguments, see the help pages for summary.tableby()
. Don’t use the option text = TRUE
with the write2
functions.
mylabels <- list(sex = "SEX", age ="Age, yrs")
tab1 <- tableby(arm ~ sex + age, data=mockstudy)
write2html(tab1, paste0(tmpdir, "/test.tableby.html"), quiet = TRUE,
title = "My test table", # passed to summary.tableby
labelTranslations = mylabels, # passed to summary.tableby
total = FALSE # passed to summary.tableby
)
modelsum
For modelsum
objects, the output function in write2()
is summary()
. For available arguments, see the help pages for summary.modelsum()
. Don’t use the option text = TRUE
with the write2
functions.
tab2 <- modelsum(alk.phos ~ arm + ps + hgb, adjust= ~ age + sex, family = "gaussian", data = mockstudy)
write2pdf(tab2, paste0(tmpdir, "/test.modelsum.pdf"), quiet = TRUE,
title = "My test table", # passed to summary.modelsum
show.intercept = FALSE, # passed to summary.modelsum
digits = 5 # passed to summary.modelsum
)
freqlist
For freqlist
objects, the output function in write2()
is summary()
. For available arguments, see the help pages for summary.freqlist()
.
tab3 <- freqlist(table(mockstudy[, c("arm", "sex", "mdquality.s")], useNA = "ifany"), groupBy = c("arm", "sex"))
write2word(tab3, paste0(tmpdir, "/test.freqlist.doc"), quiet = TRUE,
single = FALSE # passed to summary.freqlist
)
knitr::kable()
For objects resulting from a call to kable()
, the output function in write2()
is print()
. There aren’t any arguments to the print.knitr_kable()
function.
write2html(knitr::kable(head(mockstudy)), paste0(tmpdir, "/test.kable.html"), quiet = TRUE)
xtable::xtable()
For xtable
objects, the output function in write2()
is print()
. For available arguments, see the help pages for print.xtable()
.
write2pdf(xtable::xtable(head(mockstudy), caption = "My xtable"), paste0(tmpdir, "/test.xtable.pdf"), quiet = TRUE,
comment = FALSE, # passed to print.xtable to turn off the default message about xtable version
include.rownames = FALSE, # passed to print.xtable
caption.placement = "top" # passed to print.xtable
)
To make an HTML document, use the print.xtable()
option type = "html"
.
write2html(xtable::xtable(head(mockstudy), caption = "My xtable"), paste0(tmpdir, "/test.xtable.html"), quiet = TRUE,
type = "html", # passed to print.xtable
comment = FALSE, # passed to print.xtable to turn off the default message about xtable version
include.rownames = FALSE, # passed to print.xtable
caption.placement = "top" # passed to print.xtable
)
User beware! xtable()
is not compatible with write2word()
.
pander::pander_return()
Pander is a little bit more tricky. Since pander::pander()
doesn’t return an object, the useR should instead use pander::pander_return()
. For this (and for all character vectors), the the output function in write2()
is cat(sep = '\n')
.
write2word(pander::pander_return(head(mockstudy)), file = paste0(tmpdir, "/test.pander.doc"), quiet = TRUE)
This is easily accomplished by using the argument quiet = TRUE
(passed to the rmarkdown::render()
function).
write2html(knitr::kable(head(mockstudy)), paste0(tmpdir, "/test.kable.quiet.html"),
quiet = TRUE # passed to rmarkdown::render
)
.md
file?This is easily accomplished by using the option keep.md = TRUE
.
write2html(knitr::kable(head(mockstudy)), paste0(tmpdir, "/test.kable.keep.md.html"),
quiet = TRUE, # passed to rmarkdown::render
keep.md = TRUE
)
write2word()
, write2html()
, or write2pdf()
?You can pass arguments to the format functions used behind the scenes.
write2html(knitr::kable(head(mockstudy)), paste0(tmpdir, "/test.kable.theme.html"),
quiet = TRUE, # passed to rmarkdown::render
theme = "yeti" # passed to rmarkdown::html_document
)
See the help pages for rmarkdown::word_document()
, rmarkdown::html_document()
, and rmarkdown::pdf_document()
.
This can be done using the generic write2()
function. The last argument in the function can be another format specification. For details on the acceptable inputs, see the help page for write2()
.
write2(knitr::kable(head(mockstudy[, 1:4])), paste0(tmpdir, "/test.kable.rtf"),
quiet = TRUE, # passed to rmarkdown::render
output_format = rmarkdown::rtf_document
)