--- title: "The write2 function" author: "Ethan Heinzen" output: rmarkdown::html_vignette: toc: yes toc_depth: 3 vignette: | %\VignetteIndexEntry{The write2 function} %\VignetteEncoding{UTF-8} %\VignetteEngine{knitr::rmarkdown} --- ```{r include = FALSE} knitr::opts_chunk$set(eval = FALSE, message = FALSE) ``` # 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 ```{r} library(arsenal) library(magrittr) data(mockstudy) tmpdir <- tempdir() ``` ## `tableby` For `tableby` objects, the output function in `write2()` is `summary()`. For `summary.tableby` objects, the output function is `print()`. For available arguments, see the help pages for `summary.tableby()`. Don't use the option `text = TRUE` with the `write2` functions. ```{r} 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 `summary.modelsum` objects, the output function is `print()`. For available arguments, see the help pages for `summary.modelsum()`. Don't use the option `text = TRUE` with the `write2` functions. ```{r} 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 `summary.freqlist` objects, the output function is `print()`. For available arguments, see the help pages for `summary.freqlist()`. ```{r} 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 ) ``` ## `comparedf` For `comparedf` objects, the output function in `write2()` is `summary()`. For `summary.comparedf` 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. ```{r} 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()`. ```{r} 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"`. ```{r} 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')`. ```{r} 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. ```{r} 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! ```{r} mylist2 <- list( "# Header 1", "This is a small paragraph introducing tableby.", tableby(sex ~ age, data = mockstudy), "