Advanced RMarkdown

class: center, middle, inverse, title-slide

.title[
# Advanced RMarkdown
]
.subtitle[
## <br>Module 1: Review and advanced techniques
]
.author[
### 
]
.date[
### <a href="mailto:contact@appliedepi.org">contact@appliedepi.org</a>
]

---

# Thank you for joining us

Brief introductions from the instructors

**Thank you for your service** *to your community in these busy times for public health. We are glad that you are taking the time to learn R with us.*

???
Do a brief round of introductions

---

# What is R Markdown?
### A place for code, notes, and output to live together

**.Rmd scripts** 
  - Write code and narrative interpretation side-by-side
  - Run commands in parts ("chunks"), or all at once
  
**Dynamic outputs** 
  - Variety of output formats - HTML, Word, PDF, PPT, dashboard...
  - Outputs integrate text with plots, tables, and results that update automatically
  
**Collaboration**
  - In public health, R Markdown is often used in a *team context*
  - e.g. periodic surveillance or survey reports, to be run by any team member

---
class: center, middle
# R Markdown essentials

## A review

---
# From script to report

---
# Script components

---
class: center, middle
# The YAML

---
# YAML
This section at the top of the R Markdown script specifies settings of the document
.pull-left[
- Document metadata and output type
  - Title, Subtitle, Date, Author
  - Output format

- Formatting
  - Color theme
  - Table of contents
  
- Iteration  
  - "params" allow production of the report for sub-groups  
  
]

.pull-right[
Settings are written in `key: value` pairs.

``` r
---
title: "Surveillance Report"
author: "Meenakshi Kushwaha"
date: "2022-09-13"
output: 
  html_document:
    toc: true
    theme: united
params:
  district: "Western"
---
```
]

???

---
class: center, middle
# "Markdown" text

---
# Report headings and sections
.panelset[
.panel[.panel-name[To get this]
  
# Big heading  
## Smaller headings
### Smaller headings
#### Even smaller headings

]
.panel[.panel-name[Type this]

`# Big heading`  
`## Smaller headings`  
`### Smaller headings`  
`#### Even smaller headings`

]
]
---
# Formating text

.panelset[
.panel[.panel-name[To get this]
A normal text sentence.  
*Here is some text to be italicized*      
**Here is some text to be written in bold**

* Bullet point 1   
* Bullet point 2

]
.panel[.panel-name[Type this]
A normal text sentence.  
`*Here is some text to be italicized*`  
`**Here is some text to be written in bold**`

`* Bullet point 1`  
`* Bullet point 2`

]
]

.footnote[See more RMarkdown formatting [here](https://rmarkdown.rstudio.com/authoring_basics.html)]

---
class: center, middle
# R code chunks

---
# Creating code chunks

Code "chunks" are like tiny pieces of R script within the document.

Parts of a code chunk:
.pull-left[
* 3 "backticks" and curly brackets {r}
* R code  
* 3 backticks to close the chunk

*Keyboard shortcut: Ctrl + Alt + i*  
*Menu shortcut: Code -> Insert Chunk*

]

.pull-right[
Normal text above the chunk.

````r
```{r}

R code will be here.

```
````
Normal text below the chunk.

]

---
# R code in chunks
.pull-left[
For best script organisation, use a chunk to perform a specific purpose.

This chunk is for loading packages.
]

.pull-right[

````r
```{r}
pacman::p_load(
  rio,      
  here,     
  janitor,  
  tidyverse
)
```
````
]

---
# Comments in chunks
.pull-left[
Like small R scripts, you can write # comments on the lines
]

.pull-right[

````r
```{r}

# Load/import my packages
pacman::p_load(
  rio,      # import/export
  here,     # file paths
  janitor,  # cleaning & simple tables
  tidyverse # data management & viz
)

```
````
]

---
# Chunk names
.pull-left[
Optionally, give your chunk a "name" within the { }

* No spaces  
* No duplicate names  
* Name do **not** appear in the output

]

.pull-right[

````r
```{r packages}

# Load/import my packages
pacman::p_load(
  rio,      # import/export
  here,     # file paths
  janitor,  # cleaning & simple tables
  tidyverse # data management & viz
)

```
````
]

---
# Chunk options
.pull-left[
Adjust the "options" of a chunk inside the { } to determine how it affects the report:

* Run/not run the chunk: `eval =`  
* Show/hide the code: `echo =`  
* Show/hide warnings: `warning =`  
* Show/hide errors: `error =`  
* Show/hide output: `include =`

Note the commas between each option.
]

.pull-right[

````r
```{r packages, echo = FALSE, warning = FALSE}

# Load/import my packages
pacman::p_load(
  rio,      # import/export
  here,     # file paths
  janitor,  # cleaning & simple tables
  tidyverse # data management & viz
)

```
````
]

---
# The "setup" chunk

- Provided in R Markdown templates  
- Uses a {knitr} function to *specify the default "options" for all chunks*

````r
```{r setup, include=FALSE}

# set all chunk defaults: 
# not show code, warning, or error messages in the report

knitr::opts_chunk$set(echo = TRUE, warning = FALSE, error = FALSE)

```
````

Learn more about code chunk options [here](https://rmarkdown.rstudio.com/lesson-3.html)

---
class: center, middle
# Integrating R code and text

---
# Integrating R code and text
.panelset[

.panel[.panel-name[R code into Markdown text]

Often called "inline code":

will render as
<img src="../../images/rmd_1/inline_text.png" width="100%" />

]

.panel[.panel-name[Within an R command]

Use `str_glue()` to combine text and R code inside graphics captions, titles, etc.

.pull-left[

``` r
ggplot(data = linelist,
       mapping = aes(x = date_onset))+
geom_histogram()+
labs(
  title = "Simple epicurve with subtitle"
  subtitle = str_glue(
    "{num_cases} cases as of {current_date}; {n_miss} missing date of onset.",
    num_cases = nrow(linelist),
    current_date = format(Sys.Date(), '%d %b %Y'),
    n_miss = epikit::fmt_count(linelist, is.na(date_onset))))
```
]

.pull-right[

<img src="rmd1_files/figure-html/unnamed-chunk-11-1.png" width="100%" />
]

]

---
## All together
.pull-left[

````md
*---
*title: "Surveillance Report"
*output: html_document
*---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  echo = FALSE,
  warning = FALSE,
  error = FALSE)
```

```{r import, include = FALSE}
# import the dataset
surv <- import(here("data", "clean", "linelist.csv"))
```

## Executive summary
Report as of `r max(surv$report_date)`.  
There are `r nrow(surv)` cases.  
`r fmt_count(surv, outcome == 'Died')` died.

## Epidemic curve
```{r}
surv %>% 
  ggplot(mapping = aes(x = date_onset))+ 
  geom_histogram()
```
````
]

--
.pull-right[
First, the YAML heading.

This script will produce an HTML report.
]

---
## All together
.pull-left[

````md
---
title: "Surveillance Report"
output: html_document
---

*```{r setup, include = FALSE}
*knitr::opts_chunk$set(
*  echo = FALSE,
*  warning = FALSE,
*  error = FALSE)
*```

```{r import, include = FALSE}
# import the dataset
surv <- import(here("data", "clean", "linelist.csv"))
```

## Executive summary
Report as of `r max(surv$report_date)`.  
There are `r nrow(surv)` cases.  
`r fmt_count(surv, outcome == 'Died')` died.

## Epidemic curve
```{r}
surv %>% 
  ggplot(mapping = aes(x = date_onset))+ 
  geom_histogram()
```
````
]

.pull-right[
A "setup" code chunk to set the default options of all chunks.

This chunk says that no code will show in the report, and no warning or error messages produced by the codes.

]

---
## All together

.pull-left[

````md
---
title: "Surveillance Report"
output: html_document
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  echo = FALSE,
  warning = FALSE,
  error = FALSE)
```

*```{r import, include = FALSE}
*# import the dataset
*surv <- import(here("data", "clean", "linelist.csv"))
*```

## Executive summary
Report as of `r max(surv$report_date)`.  
There are `r nrow(surv)` cases.  
`r fmt_count(surv, outcome == 'Died')` died.

## Epidemic curve
```{r}
surv %>% 
  ggplot(mapping = aes(x = date_onset))+ 
  geom_histogram()
```
````
]

.pull-right[
This separate code chunk imports the dataset.

It does it silently, this code nor any output will appear in the report.

]

---
## All together

.pull-left[

````md
---
title: "Surveillance Report"
output: html_document
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  echo = FALSE,
  warning = FALSE,
  error = FALSE)
```

```{r import, include = FALSE}
# import the dataset
surv <- import(here("data", "clean", "linelist.csv"))
```

*## Executive summary
*Report as of `r max(surv$report_date)`.  
*There are `r nrow(surv)` cases.  
*`r fmt_count(surv, outcome == 'Died')` died.

## Epidemic curve
```{r}
surv %>% 
  ggplot(mapping = aes(x = date_onset))+ 
  geom_histogram()
```
````
]

.pull-right[
This is "markdown" text - headings and sentences that will appear in the report.

There is embedded "inline" R code, to make the figures in the text dynamically update (e.g. the dates, case counts, etc).

]

---
## All together

.pull-left[

````md
---
title: "Surveillance Report"
output: html_document
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  echo = FALSE,
  warning = FALSE,
  error = FALSE)
```

```{r import, include = FALSE}
# import the dataset
surv <- import(here("data", "clean", "linelist.csv"))
```

## Executive summary
Report as of `r max(surv$report_date)`.  
There are `r nrow(surv)` cases.  
`r fmt_count(surv, outcome == 'Died')` died.

*## Epidemic curve
*```{r}
*surv %>% 
*  ggplot(mapping = aes(x = date_onset))+ 
*  geom_histogram()
*```
````
]

.pull-right[
This final code chunk produces a simple histogram of cases by date of onset.

The code will not appear in the report, but the output (the epicurve) will display.

]

---
class: center, middle
# Dynamic tables

---

# Datatable
Allow filtering, pagination, and sorting in HTML tables.

.panelset[

.panel[.panel-name[To get this]
<img src="../../images/rmd_1/dt1.png" width="100%" />

]

.panel[.panel-name[Type this]

``` r
linelist %>% 
  head(20) %>% 
* DT::datatable()
```

]

]
---
# Tables for presentation

- Use `{flextable}` or similar to make summary tables publication-ready  
- To be displayed in HTML, Word documents, PPT slides, dashboards

---
# Customizing reports - HTML

For HTML reports, YAML permits advanced customisation, e.g.  
  - Themes (colors and aesthetics of the report)
  - Table of contents (static, floating, etc.)
  - Clickable-buttons to show/hide code display  
  - "params" to produce the report for sub-groups

``` r
---
title: "Surveillance Report"
author: "Meenakshi Kushwaha"
date: "2022-09-13"
output: 
* html_document:
*   theme: flatly
*   toc: TRUE
*   toc_float: TRUE
*   code_folding: hide
---
```

We will cover these in the exercise, in detail.

---

# Customizing reports - Word

In Word outputs, no interactive tables or plots, but you can still use `{flextable}`.

Word outputs have fewer YAML options, but allow use of Word templates:  
* Create a *template file* with custom styles, logos, etc.
* Include the *template file* in the YAML

``` r
---
title: "Surveillance Report"
author: "Meenakshi Kushwaha"
date: "`r Sys.Date()`"
output: 
* word_document:
*   toc: yes
*   refrence_docx: my_template.docx
```

The Word doc created by RMarkdown will have the same formatting as specified in `my_template.docx`

---
# Parametrized reports

This is a very powerful feature, used to re-render the same report with distinct values, for example:

- Producing a report specific to a department or geographic region.

- Producing a report that covers a specific period in time.
  
  - Producing a report with or without certain sections depending on the audience.
  
You set default "parameters" in the YAML, and can adjust them every time you render the report.

---
# Set params within YAML

This YAML sets two params (district and date) with default values.

``` r
---
title: "Surveillance Report"
author: "Meenakshi Kushwaha"
date: "`r Sys.Date()`"
output: 
  html_document
*params:
* district: "Central Hospital"
* date: "2021-04-10"
```

---
## Edit params within `render()`

The `render()` command can be used to run your report from another script.

You can set param values in this command, overriding the defaults in the YAML.

``` r
rmarkdown::render(
  input = "surveillance_report.Rmd",  
  output_file = stringr::str_glue("outputs/Report_{Sys.Date()}.docx"),
* params = list(date = "2021-04-10", hospital  = "Central Hospital"))
```

We will cover this in module 2 of this course.

---

## Edit params using "Knit" and the user interface

RStudio offers an option to "Knit with parameters", which opens an interface like this prior to rendering:

---
class: middle, center

# Demo

.footnote[
Slide formatting tips from [Thomas Mock](https://themockup.blog/posts/2021-08-27-displaying-verbatim-code-chunks-in-xaringan-presentations/#distill-output)
]