The write2 function

Ethan Heinzen

02 February, 2018

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.

A note on piping

arsenal is piping-compatible!

The write2*() functions are probably the most useful place to take advantage of the magrittr package’s piping framework, since commands are often nested several functions deep in the context of write2*(). Piping also allows the arsenal package to become a part of more standard analysis pipelines; instead of needing to write separate R Markdown programs, intermediate analysis tables and output can be easily incorporated into piped statements.

This vignette will sprinkle the foward pipe (%>%) throughout as a hint at the power and flexibility of arsenal and piping.

Examples Using arsenal Objects

library(arsenal)
library(magrittr)
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().

mockstudy[, c("arm", "sex", "mdquality.s")] %>% 
  table(useNA = "ifany") %>% 
  freqlist(groupBy = c("arm", "sex")) %>% 
  write2word(paste0(tmpdir, "/test.freqlist.doc"), quiet = TRUE,
             single = FALSE,         # passed to summary.freqlist
             title = "My cool title" # passed to summary.freqlist
             )

compare

For compare.data.frame objects, the output function in write2() is summary(). For summary.compare.data.frame objects, the output function is print().

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.

mockstudy %>% 
  head() %>% 
  knitr::kable() %>% 
  write2html(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().

mockstudy %>% 
  head() %>% 
  xtable::xtable(caption = "My xtable") %>% 
  write2pdf(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".

mockstudy %>% 
  head() %>% 
  xtable::xtable(caption = "My xtable") %>% 
  write2html(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)

Output Multiple Tables to One Document

To output multiple tables into a document, simply make a list of them and call the same function as before.

mylist <- list(tableby(sex ~ age, data = mockstudy),
               freqlist(table(mockstudy[, c("sex", "arm")])),
               knitr::kable(head(mockstudy)))

write2pdf(mylist, paste0(tmpdir, "/test.mylist.pdf"), quiet = TRUE)

One neat side-effect of this function is that you can output text and headers, etc. The possibilities are endless!

mylist2 <- list("# Header 1",
                "This is a small paragraph introducing tableby.",
                tableby(sex ~ age, data = mockstudy),
                "<hr>",
                "# Header 2",
                "<font color='red'>I can change color of my text!</font>")
write2html(mylist2, paste0(tmpdir, "/test.mylist2.html"), quiet = TRUE)

In fact, you can even recurse on the lists!

write2pdf(list(mylist2, mylist), paste0(tmpdir, "/test.mylists.pdf"), quiet = TRUE)

Output Other Objects Monospaced (as if in a terminal)

It may be useful at times to write output that would normally be copied from the terminal. The default method for write2() does this automatically. To output the results of summary.lm(), for example:

lm(age ~ sex, data = mockstudy) %>% 
  summary() %>% 
  write2pdf(paste0(tmpdir, "/test.lm.pdf"), quiet = TRUE)

The verbatim() function is another option to explicitly alert write2() to do this. This becomes particularly helpful to overrule existing S3 methods.

For example, suppose you wanted to just print a tableby object (as if it were to print in the terminal):

tab4 <- tableby(arm ~ sex + age, data=mockstudy)
write2html(verbatim(tab4), paste0(tmpdir, "/test.print.tableby.html"), quiet = TRUE)

Or suppose you wanted to print a character vector (as if it were to print in the terminal):

chr <- paste0("MyVector", 1:10)
write2pdf(verbatim(chr), paste0(tmpdir, "/test.character.pdf"), quiet = TRUE)

Add a YAML Header to the Output

You can add a YAML header to write2() output using the yaml() function.

mylist3 <- list(
  yaml(title = "Test YAML Title", author = "My cool author name"),
  "# Header 1",
  "This is a small paragraph introducing tableby.",
  tableby(sex ~ age, data = mockstudy)
)
write2html(mylist3, paste0(tmpdir, "/test.yaml.html"), quiet = TRUE)

In fact, all detected YAML pieces will be moved as the first output, so that the above code chunk gives the same output as this one:

mylist4 <- list(
  "# Header 1",
  "This is a small paragraph introducing tableby.",
  yaml(title = "Test YAML Title"),
  tableby(sex ~ age, data = mockstudy),
  yaml(author = "My cool author name")
)
write2html(mylist3, paste0(tmpdir, "/test.yaml2.html"), 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 prevent my document from being rendered?

This is easily accomplished by using the option render. = FALSE. Note that this will then default to keep.md = TRUE.

write2html(knitr::kable(head(mockstudy)), paste0(tmpdir, "/test.kable.dont.render.html"),
           render. = FALSE
           )

How do I output headers, raw HTML/LaTeX, paragraphs, etc.?

One can simply abuse the list S3 method for write2()!

mylist2 <- list("# Header 1",
                "This is a small paragraph introducing tableby.",
                tableby(sex ~ age, data = mockstudy),
                "<hr>",
                "# Header 2",
                "<font color='red'>I can change color of my text!</font>")
write2html(mylist2, paste0(tmpdir, "/test.mylist2.html"), quiet = 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
       )

How do I avoid prefixes on my table captions in PDF?

You can do this pretty easily with the yaml() function:

mylist5 <- list(
  yaml("header-includes" = list("\\usepackage[labelformat=empty]{caption}")),
  "# Header 1",
  "This is a small paragraph introducing tableby.",
  tableby(sex ~ age, data = mockstudy)
)
write2pdf(mylist5, paste0(tmpdir, "/test.noprefixes.pdf"), title = "My tableby")