13_exporting.Rmd

# Exporting and reporting{#chap13-h1}
\index{exporting@\textbf{exporting}}

> Without data, you are just another person with an opinion.  
> W. Edwards Deming

The results of any data analysis are meaningless if they are not effectively communicated. 

This may be as a journal article or presentation, or perhaps a regular report or webpage. In Chapter \@ref(chap13-h1) we emphasise another of the major strengths of R - the ease with which HTML (a web page), PDF, or Word documents can be generated.

The purpose of this chapter is to focus on the details of how to get your exported tables, plots and documents looking exactly the way you want them. There are many customisations that can be used, and we will only touch on a few of these. 

We will generate a report using data already familiar to you from this book. 
It will contain two tables - a demographics table and a regression table - and a plot. 
We will use the `colon_s` data from the `finalfit` package. 
What follows is for demonstration purposes and is not meant to illustrate model building. 
For the purposes of the demonstration, we will ask, does a particular characteristic of a colon cancer (e.g., cancer differentiation) predict 5-year survival?

## Which format should I use?

The three common formats for exporting reports have different pros and cons: 

* HTML is the least fussy to work with and can resize itself and its content automatically. For rapid exploration and prototyping, we recommend knitting to HTML. HTML documents can be attached to emails and viewed using any browser, even with no internet access (as long as it is a self-contained HTML document, which R Markdown exports usually are).
* PDF looks most professional when printed. This is because R Markdown uses LaTeX to typeset PDF documents. LaTeX PDFs are our preferred method of producing printable reports or dissertations, but they come with their own bag of issues. Mainly that LaTeX figures and tables *float* and may therefore appear much later down the document than the original text describing it was.
* Word is useful when working with non-R people who need to edit your output.

## Working in a `.R` file

We will demonstrate how you might put together a report in two ways. 

First, we will show what you might do if you were working in standard R script file, then exporting certain objects only. 

Second, we will talk about the approach if you were primarily working in a Notebook, which makes things easier. 

We presume that the data have been cleaned carefully and the 'Get the data', 'Check the data', 'Data exploration' and 'Model building' steps have already been completed. 

```{r echo=FALSE, message=FALSE}
library(knitr)
library(kableExtra)
mykable <- function(x, caption = "CAPTION", ...){
  kable(x, row.names = FALSE, align = c("l", "l", "r", "r", "r", "r", "r", "r", "r"), 
        booktabs = TRUE, caption = caption, 
        linesep = c("", "", "\\addlinespace"), ...) %>%
    kable_styling(latex_options = c("scale_down", "hold_position"))
}
```

## Demographics table

First, let's look at associations between our explanatory variable of interest (exposure) and other explanatory variables. 

```{r, eval=FALSE}
library(tidyverse)
library(finalfit)

# Specify explanatory variables of interest
explanatory <- c("age", "sex.factor", 
                "extent.factor", "obstruct.factor", 
                "nodes")

colon_s %>% 
  summary_factorlist("differ.factor", explanatory,
                     p=TRUE, na_include=TRUE)
```

```{r, warning=FALSE, message=FALSE, echo=FALSE}
library(tidyverse)
library(finalfit)

# Specify explanatory variables of interest
explanatory <- c("age", "sex.factor", 
                "extent.factor", "obstruct.factor", 
                "nodes")

colon_s %>% 
  summary_factorlist("differ.factor", explanatory,
                     p=TRUE, na_include=TRUE) %>% 
  mykable(caption = "Exporting 'table 1': Tumour differentiation by patient and disease factors.")
```

Note that we include missing data in this table (see Chapter \@ref(chap11-h1)).

Also note that `nodes` has not been labelled properly. 

In addition, there are small numbers in some variables generating `chisq.test()` warnings (expect fewer than 5 in any cell). 

Now generate a final table.^[The `finalfit` functions used here - `summary_factorlist()` and `finalfit()` were introduced in Part II - Data Analysis. We will therefore not describe the different arguments here, we use them to demonstrate R's powers of exporting to fully formatted output documents.]

```{r, eval=FALSE}
colon_s <- colon_s %>% 
  mutate(
    nodes = ff_label(nodes, "Lymph nodes involved")
    )

table1 <- colon_s %>%  
  summary_factorlist("differ.factor", explanatory, 
                     p=TRUE, na_include=TRUE, 
                     add_dependent_label=TRUE,
                     dependent_label_prefix = "Exposure: "
                     )
table1
```

```{r, warning=FALSE, message=FALSE, echo=FALSE}
colon_s <- colon_s %>% 
  mutate(
    nodes = ff_label(nodes, "Lymph nodes involved")
  )

table1 <- colon_s %>%  
  summary_factorlist("differ.factor", explanatory, 
                     p=TRUE, na_include=TRUE, 
                     add_dependent_label=TRUE,
                     dependent_label_prefix = "Exposure: ")
table1 %>% 
  mykable(caption = "Exporting table 1: Adjusting labels and output.") %>% 
  column_spec(1, width = "3.5cm")
```

## Logistic regression table

After investigating the relationships between our explanatory variables, we will use logistic regression to include the outcome variable.

```{r, eval=FALSE}
explanatory <- c( "differ.factor", "age", "sex.factor", 
                "extent.factor", "obstruct.factor", 
                "nodes")
dependent <- "mort_5yr"
table2 <- colon_s %>% 
  finalfit(dependent, explanatory, 
           dependent_label_prefix = "")
table2
```

```{r, warning=FALSE, message=FALSE, echo=FALSE}
explanatory <- c( "differ.factor", "age", "sex.factor", 
                "extent.factor", "obstruct.factor", 
                "nodes")
dependent <- "mort_5yr"
table2 <- colon_s %>% 
  finalfit(dependent, explanatory, 
           dependent_label_prefix = "")
table2 %>% 
  mykable(caption = "Exporting a regression results table.")
```

## Odds ratio plot
It is often preferable to express the coefficients from a regression model as a forest plot. 
For instance, a plot of odds ratios can be produced using the `or_plot()` function also from the `finalfit` package:

```{r fig.height=3.5, fig.width=7, message=FALSE, warning=FALSE, fig.cap="Odds ratio plot."}
colon_s %>% 
  or_plot(dependent, explanatory, 
          breaks = c(0.5, 1, 5, 10, 20, 30),
          table_text_size = 3.5)
```

## MS Word via knitr/R Markdown
\index{Microsoft Word}
\index{PDF}
\index{knitr}

When moving from a `.R` file to a Markdown (`.Rmd`) file, environment objects such as tables or data frames / tibbles usually require to be saved and loaded to R Markdown document.

```{r, eval=FALSE}
# Save objects for knitr/markdown
save(table1, table2, dependent, explanatory, 
     file = here::here("data", "out.rda"))
```

In RStudio, select:  
File > New File > R Markdown

A useful template file is produced by default. Try hitting knit to Word on the Knit button at the top of the `.Rmd` script window.
If you have difficulties at this stage, refer to Chapter \@ref(chap12-h1).

Now paste this into the file (we'll call it Example 1):

```` markdown
---
title: "Example knitr/R Markdown document"
author: "Your name"
date: "22/5/2020"
output:
  word_document: default
---

`r ''````{r setup, include=FALSE}
# Load data into global environment. 
library(finalfit)
library(dplyr)
library(knitr)
load(here::here("data", "out.rda"))
```

## Table 1 - Demographics
`r ''````{r table1, echo = FALSE}
kable(table1, row.names=FALSE, align=c("l", "l", "r", "r", "r", "r"))
```

## Table 2 - Association between tumour factors and 5 year mortality
`r ''````{r table2, echo = FALSE}
kable(table2, row.names=FALSE, align=c("l", "l", "r", "r", "r", "r"))
```

## Figure 1 - Association between tumour factors and 5 year mortality
`r ''````{r figure1, echo = FALSE}
explanatory = c( "differ.factor", "age", "sex.factor", 
                "extent.factor", "obstruct.factor", 
                "nodes")
dependent = "mort_5yr"
colon_s %>% 
  or_plot(dependent, explanatory)
```
````

```{r chap13-fig-word, echo = FALSE, fig.cap="Knitting to Microsoft Word from R Markdown. Before (A) and after (B) adjustment."}
knitr::include_graphics("images/chapter13/1_word_knit.png", auto_pdf = TRUE)
```

Knitting this into a Word document results in Figure \@ref(fig:chap13-fig-word)A), which looks pretty decent but some of the columns need some formatting and the plot needs resized.
Do not be tempted to do this by hand directly in the Word document.

Yes, before Markdown, we would have to move and format each table and figure directly in Word, and we would repeat this every time something changed.
Turns out some patient records were duplicated and you have to remove them before repeating the analysis over again.
Or your colleague forgot to attach an extra file with 10 more patients.

No problem, you update the dataset, re-run the script that created the tables and hit Knit in the R Markdown document.
No more mindless re-doing for you.
We think this is pretty amazing.

### Figure quality in Word output

If your plots are looking a bit grainy in Word, include this in your setup chunk for high quality:

```{r}
knitr::opts_chunk$set(dpi = 300) 
```

The setup chunk is the one that starts with ```` ```{r setup, include = FALSE} ```` and is generated automatically when you create a new R Markdown document in RStudio.

## Create Word template file

To make sure tables always export with a suitable font size, you may edit your Word file but only to create a new template. 
You will then use this template to Knit the R Markdown document again.

In the Word document the first example outputted, click on a table. 
The style should be `compact`:
Right-click > Modify... > font size = 9

Alter heading and text styles in the same way as desired. 
Save this as `colonTemplate.docx` (avoid underscores in the name of this file). 
Move the file to your project folder and reference it in your `.Rmd` YAML header, as shown below. 
Make sure you get the spacing correct, unlike R code, the YAML header is sensitive to formatting and the number of spaces at the beginning of the argument lines.

Finally, to get the figure printed in a size where the labels don't overlap each other, you will have to specify a width for it.
The Chunk cog introduced in the previous chapter is a convenient way to change the figure size (it is in the top-right corner of each grey code chunk in an R Markdown document).
It usually takes some experimentation to find the best size for each plot/output document; in this case we are going with `fig.width = 10`.

Knitting Example 2 here gives us Figure \@ref(fig:chap13-fig-word)B).
For something that is generated automatically, it looks awesome.

```` markdown
---
title: "Example knitr/R Markdown document"
author: "Your name"
date: "22/5/2020"
output:
  word_document:
    reference_docx: colonTemplate.docx
---
  
`r ''````{r setup, include=FALSE}
# Load data into global environment. 
library(finalfit)
library(dplyr)
library(knitr)
load(here::here("data", "out.rda"))
```

## Table 1 - Demographics
`r ''````{r table1, echo = FALSE}
kable(table1, row.names=FALSE, align=c("l", "l", "r", "r", "r", "r"))
```

## Table 2 - Association between tumour factors and 5 year mortality
`r ''````{r table2, echo = FALSE}
kable(table2, row.names=FALSE, align=c("l", "l", "r", "r", "r", "r"))
```

## Figure 1 - Association between tumour factors and 5 year mortality
`r ''````{r figure1, echo=FALSE, message=FALSE, warning=FALSE, fig.width=10}
explanatory = c( "differ.factor", "age", "sex.factor", 
                "extent.factor", "obstruct.factor", 
                "nodes")
dependent = "mort_5yr"
colon_s %>% 
  or_plot(dependent, explanatory, 
          breaks = c(0.5, 1, 5, 10, 20, 30))
```
````


## PDF via knitr/R Markdown

Without changing anything in Example 1 and Knitting it into a PDF, we get \@ref(fig:chap13-fig-pdf)A.

Again, most of it already looks pretty good, but some parts over-run the page and the plot is not a good size.

We can fix the plot in exactly the same way we did for the Word version (`fig.width`), but the second table that is too wide needs some special handling.
For this we use `kable_styling(font_size=8)` from the `kableExtra` package.
Remember to install it when using for the first time, and include `library(knitExtra)` alongside the other library lines at the setup chunk.

We will also alter the margins of your page using the geometry option in the preamble as the default margins of a PDF document coming out of R Markdown are a bit wide for us.


```{r chap13-fig-pdf, echo = FALSE, fig.cap="Knitting to Microsoft Word from R Markdown. Before (A) and after (B) adjustment.", out.width="70%"}
knitr::include_graphics("images/chapter13/1_pdf_knit.png", auto_pdf = TRUE)
```


```` markdown
---
title: "Example knitr/R Markdown document"
author: "Your name"
date: "22/5/2020"
output:
  pdf_document: default
geometry: margin=0.75in
---

`r ''````{r setup, include=FALSE}
# Load data into global environment. 
library(finalfit)
library(dplyr)
library(knitr)
library(kableExtra)
load(here::here("data", "out.rda"))
```

## Table 1 - Demographics
`r ''````{r table1, echo = FALSE}
kable(table1, row.names=FALSE, align=c("l", "l", "r", "r", "r", "r"),
      booktabs = TRUE)
```

## Table 2 - Association between tumour factors and 5 year mortality
`r ''````{r table2, echo = FALSE}
kable(table2, row.names=FALSE, align=c("l", "l", "r", "r", "r", "r"),
      booktabs=TRUE) %>% 
kable_styling(font_size=8)
```

## Figure 1 - Association between tumour factors and 5 year mortality
`r ''````{r figure1, echo=FALSE, message=FALSE, warning=FALSE, fig.width=10}
explanatory = c( "differ.factor", "age", "sex.factor", 
                "extent.factor", "obstruct.factor", 
                "nodes")
dependent = "mort_5yr"
colon_s %>% 
  or_plot(dependent, explanatory, 
          breaks = c(0.5, 1, 5, 10, 20, 30))
```
````

The result is shown in Figure \@ref(fig:chap13-fig-pdf)B.

## Working in a `.Rmd` file

We now perform almost all our analyses in a Notebook / Markdown file as described in the previous chapter. 
This means running all analyses within the document, without the requirement to save and reload table or plot objects. 

As mentioned earlier, a Notebook document can be rendered as a PDF or a Word document. 
Some refining is usually needed to move from an 'analysis' document to a final 'report' document, but it is often minimal. 

Figure \@ref(fig:chap13-fig-report) demonstrates a report-type document rendered as a PDF.
All the code is run within the document, but not included in the output (`echo=FALSE`). 

```{r chap13-fig-report, echo = FALSE, fig.cap="Writing a final report in a Markdown document."}
knitr::include_graphics("images/chapter13/4_colon_report.png", auto_pdf = TRUE)
```

## Moving between formats

As we have shown, it is relatively straightforward to move between HTML, Word and PDF when documents are simple. 
This becomes more difficult if you have a complicated document which includes lots of formatting. 

For instance, if you use the package `kableExtra()` to customise your tables, you can only export to HTML and PDF.
Knitting to Word will not currently work with advanced `kableExtra` functions in your R Markdown document.
Similarly, `flextable` and `officer` are excellent packages for a love story between R Markdown and Word/MS Office, but they do not work for HTML or PDF.

## Summary

The combination of R, RStudio, and Markdown is a powerful triumvirate which produces beautiful results quickly and will be greatly labour saving. 
We use this combination for all academic work, but also in the production of real-time reports such as webpages and downloadable PDFs for ongoing projects. 
This is a fast-moving area with new applications and features appearing every month. 
We would highly recommend you spend some time getting familiar with this area, as it will become an ever more important skill in the future.