The write2 function

Ethan Heinzen

31 January, 2017

Introduction

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:

  1. 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.

  2. 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.

Examples Using arsenal Objects

library(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
           )

Examples Using Other Objects

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)

FAQs

How do I suppress the note about my document getting rendered?

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
           )

How do I look at the temporary .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
           )

How do I tweak the default format from 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().

How do I output to a file format other than word, HTML, and PDF?

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
       )