Resources

Workshop materials: on Github

Slides: jthomasmock.github.io/rmd-nhs/

Some content adapted from superstar Dr. Alison Hill CDC & R4Pharma: CC-BY

What is R Markdown?

1. "An authoring framework for data science." (✔️)

2. A document format (.Rmd). (✔️)

3. An R package named rmarkdown. (✔️)

4. "A file format for making dynamic documents with R." (✔️)

5. "A tool for integrating text, code, and results." (✔️)

6. "A computational document." (✔️)

7. Magic (🧙️)

Why RMarkdown?

1. Reproducibility

2. Re-usability

3. Extensibility

4. "Lazy" ability

Change your mental model

R Markdown

R Markdown documents are fully reproducible. Use a productive notebook interface to weave together narrative text and code to produce elegantly formatted output. Use multiple languages including R, Python, and SQL.

No more copy-paste, no more manually rebuilding analyses from disparate components, no more dread when the data is updated and you need to run an analysis.

Pouring milk

A straight-forward task - pour the boxed milk into the glass.

Anatomy of RMarkdown

• Metadata (YAML)

---
output: html_document
---

• Code

```{r basicExample, echo = TRUE}
library(dplyr)
mtcars %>% 
  group_by(cyl) %>% 
  summarize(n = n(), mean = mean(mpg))
```

• Text

# Heading 1
This is a sentence with some **bold text**, some *italic text* and an [image](image.png).

Metadata: YAML

The YAML metadata or header is:

processed in many stages of the rendering process and can influence the final document in many different ways. It is placed at the very beginning of the document and is read by each of Pandoc, rmarkdown, and knitr. Along the way, the information that it contains can affect the code, content, and the rendering process. - RMarkdown Cookbook

A generic YAML follows a pattern like the below:

---
key: value
---

Valid YAML requires 3 dashes --- on either end, creating the YAML block, with key + value pairs assigned throughout.

Metadata: YAML

Specific metadata about the document and rendering options are included in this YAML header.

Note that if you want to find out what type of options are available, you can run ?rmarkdown::html_document() or ?rmarkdown::pdf_document(), etc, to show the specific rendering options for that specific output format. There is also a rmarkdown pkgdown site, so you can explore specific options there as well.

Output options

---
output: html_document
---

Specify output options in YAML

---
title: My First RMarkdown Report
author: Tom Mock
output: html_document
---

Specify output options in YAML

---
title: My First RMarkdown Report
author: Tom Mock
output: html_document
---

---
title: My First RMarkdown Report
author: Tom Mock
output:
  html_document:
    toc: true
    toc_float: true
    theme: united
    code_download: true
---

---
title: My PDF RMarkdown Report
author: Tom Mock
output: pdf_document
---

Specify output options in YAML

---
title: My First RMarkdown Report
author: Tom Mock
output: html_document
---

---
title: My First RMarkdown Report
author: Tom Mock
output:
  html_document:
    toc: true
    toc_float: true
    theme: united
    code_download: true
---

---
title: My PDF RMarkdown Report
author: Tom Mock
output: pdf_document
---

---
title: "My Presentation"
subtitle: "made with xaringan"
author: "Yihui Xie"
date: "2021-10-30"
output:
  xaringan
---

Text and Markdown text

• Text is human language

• Markdown is markup language

* _Text_ is **human language**  
* _Markdown_ is **markup language**

You can read all about Markdown via the Markdown guide or use the rmarkdown cheat sheet!

Headings for splitting up your document

# Header 1
## Header 2
### Header 3
#### Header 4

Headings for splitting up your document

More than just text

You can inline R code, so that you can programatically generate specific components of the document.

IE I can report that there are r nrow(mtcars)

Which returns 32.

These inline texts can be as complex or simple as you like, and can also return R objects.

car_rows <- glue::glue("There are {nrow(mtcars)} rows in the `mtcars` dataset.")

r car_rows

There are 32 rows in the mtcars dataset.

Images

![RMarkdown hex logo](https://raw.githubusercontent.com/rstudio/rmarkdown/main/man/figures/logo.png)
![Alt text](path-to-local-file.png)

knitr::include_graphics("https://user-images.githubusercontent.com/163582/45438104-ea200600-b67b-11e8-80fa-d9f2a99a03b0.png")

Visual Editor

• The visual editor is more than just the ability to see the output in real time.
• It also provides "word processor" like formatting of text, math, and other capabilities!

Code chunks

Specified sections of the document that are used to evaluate code and optionally return outputs.

```{r, echo = FALSE}
mtcars %>% 
  distinct(cyl)
```

mtcars %>% 
  distinct(cyl)

##                   cyl
## Mazda RX4           6
## Datsun 710          4
## Hornet Sportabout   8

Anatomy of a code chunk

```{r car-stuff, echo = FALSE}
mtcars %>% 
  distinct(cyl)
```

Code chunks

Code in a chunk auto print, unless saved to an object, which needs to be explicitly returned.

n_manufacturers <- n_distinct(gt::gtcars$mfr)

n_manufacturers

## [1] 19

n_manufacturers <- n_distinct(gt::gtcars$mfr)
n_manufacturers

## [1] 19

Code chunks return more than just data

car_data <- gt::gtcars %>% 
  filter(!is.na(mpg_h)) %>% 
  group_by(mfr) %>% 
  summarise(
    mean_mpg = mean(mpg_h), 
    n_models = n_distinct(model)
    ) %>% 
  filter(n_models >= 2) %>% 
  arrange(desc(n_models))

ggplot(car_data, aes(x = mean_mpg, 
      y = fct_reorder(mfr, mean_mpg))) +
  geom_col()

ggplot(car_data, aes(x = mean_mpg, 
      y = fct_reorder(mfr, mean_mpg))) +
  geom_col()

Code chunks return more than just data

car_data %>% 
  gt::gt()

Code chunks are controllable

There are many chunk options you can control via knitr (the package that provides core features of RMarkdown).

Link to all the knitr options

```{r, eval = FALSE}
mtcars %>% 
  distinct(cyl)
```

# This won't return, because the 
# chunk is not evaluated
# via eval = FALSE
mtcars %>% 
  distinct(cyl)

Code chunks are controllable

Some examples

Code chunks are controllable

```{r, fig.dim = c(6,4), dpi=150}
mtcars %>% 
  count(cyl) %>% 
  ggplot(aes(x = n, y = factor(cyl))) + geom_col()
```

New to knitr v1.35, there's now support for in-chunk option setting via special chunk option comments (ie #|). Very useful for longer options (like fig.cap or fig.alt), for setting many chunks at once, or for logical statements.

```{r}
#| fig.dim = c(6,4), dpi = 150,
#| fig.alt = "A simple barplot with the count of observations on the x-axis by the number of cylinders on the y-axis. There are 14 eight-cylinder cars, 7 six-cylinder cars, and 11 four-cylinder cars.\n
```

Code chunks are controllable

mtcars %>% 
  count(cyl) %>% 
  ggplot(aes(x = n, y = factor(cyl))) + geom_col()

mtcars %>% 
  count(cyl) %>% 
  ggplot(aes(x = n, y = factor(cyl))) + geom_col()

Chunk options can be globally set

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  echo = FALSE, fig.width = 6, dpi = 150
)
```

This is typically most useful in avoiding repeating yourself throughout a document and making the different components consistent between chunks without having to manually set these for EACH chunk.

Chunk option defaults

str(knitr::opts_chunk$get()[1:27])

## List of 27
##  $ eval         : logi TRUE
##  $ echo         : logi TRUE
##  $ results      : chr "markup"
##  $ tidy         : logi FALSE
##  $ tidy.opts    : NULL
##  $ collapse     : logi FALSE
##  $ prompt       : logi FALSE
##  $ comment      : chr "##"
##  $ highlight    : logi TRUE
##  $ size         : chr "normalsize"
##  $ background   : chr "#F7F7F7"
##  $ strip.white  : 'AsIs' logi TRUE
##  $ cache        : logi FALSE
##  $ cache.path   : chr "index_cache/html/"
##  $ cache.vars   : NULL
##  $ cache.lazy   : logi TRUE
##  $ dependson    : NULL
##  $ autodep      : logi FALSE
##  $ cache.rebuild: logi FALSE
##  $ fig.keep     : chr "high"
##  $ fig.show     : chr "asis"
##  $ fig.align    : chr "default"
##  $ fig.path     : chr "index_files/figure-html/"
##  $ dev          : chr "png"
##  $ dev.args     : NULL
##  $ dpi          : num 72
##  $ fig.ext      : NULL

str(knitr::opts_chunk$get()[28:53])

## List of 26
##  $ fig.width : num 7
##  $ fig.height: num 7
##  $ fig.env   : chr "figure"
##  $ fig.cap   : NULL
##  $ fig.scap  : NULL
##  $ fig.lp    : chr "fig:"
##  $ fig.subcap: NULL
##  $ fig.pos   : chr ""
##  $ out.width : NULL
##  $ out.height: NULL
##  $ out.extra : NULL
##  $ fig.retina: num 1
##  $ external  : logi TRUE
##  $ sanitize  : logi FALSE
##  $ interval  : num 1
##  $ aniopts   : chr "controls,loop"
##  $ warning   : logi TRUE
##  $ error     : logi FALSE
##  $ message   : logi TRUE
##  $ render    : NULL
##  $ ref.label : NULL
##  $ child     : NULL
##  $ engine    : chr "R"
##  $ split     : logi FALSE
##  $ include   : logi TRUE
##  $ purl      : logi TRUE

Chunks can be named

label: unnamed-chunk-23
  |..............................|  83%
  ordinary text without R code
  |..............................|  85%
label: unnamed-chunk-24 (with options) 
List of 2
 $ fig.dim: num [1:2] 6 4
 $ dpi    : num 150
  |..............................|  86%
  ordinary text without R code

Named chunks can be re-used!

```{r myPlt, eval = FALSE}
ggplot(mtcars, aes(x = disp, y = mpg, 
    color = factor(cyl))) +
  geom_point()
```

```{r myPlt, dpi=300,fig.dim=c(6,4)}
```

Chunk names, good and bad

The setup chunk

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,   
  comment = "#>", 
  out.width = "100%" 
)
```

Chunks don't have to be R

```{python}
x = 42 * 2
print(x) 
```

```{bash}
echo "Hello Bash!"
cat flights1.csv flights2.csv > flights.csv
```

```{r}
library(DBI)
db = dbConnect(RSQLite::SQLite(), 
  dbname = "sql.sqlite")
```

```{sql, connection=db}
SELECT * FROM trials
```

Chunk language engines

names(knitr::knit_engines$get())

##  [1] "awk"       "bash"      "coffee"    "gawk"      "groovy"    "haskell"  
##  [7] "lein"      "mysql"     "node"      "octave"    "perl"      "psql"     
## [13] "Rscript"   "ruby"      "sas"       "scala"     "sed"       "sh"       
## [19] "stata"     "zsh"       "asis"      "asy"       "block"     "block2"   
## [25] "bslib"     "c"         "cat"       "cc"        "comment"   "css"      
## [31] "ditaa"     "dot"       "embed"     "exec"      "fortran"   "fortran95"
## [37] "go"        "highlight" "js"        "julia"     "python"    "R"        
## [43] "Rcpp"      "sass"      "scss"      "sql"       "stan"      "targets"  
## [49] "tikz"      "verbatim"  "glue"      "glue_sql"  "gluesql"

Use an RStudio Project for your analysis!

One day you will need to quit R, go do something else and return to your analysis the next day. One day you will be working on multiple analyses simultaneously that all use R and you want to keep them separate. One day you will need to bring data from the outside world into R and send numerical results and figures from R back out into the world. To handle these real life situations, you need to make two decisions:
1: What about your analysis is “real”, i.e. what will you save as your lasting record of what happened?
2: Where does your analysis “live”? - Hadley Wickham, R4DS

RStudio > New Project - this gives you a lightweight environment for managing your data analysis code, data, and outputs, that can be shared across teams (ie via version control, shared drives, etc)

Expanded in great detail in R4DS

RMarkdown rendering

Rendering a RMarkdown doc is also called "knitting" as you are knitting all the components together.

• You can use the RStudio button (Knit)
• You can use rmarkdown::render("file-name.rmd")

RMarkdown paths

#> tom/demo-project
#> ├── analysis
#> │   └── report.Rmd
#> ├── data
#> │   └── penguins.csv
#> ├── demo-project.Rproj
#> └── prepare
#>     └── penguins.R

# inside report.Rmd
getwd()
#> [1] "Users/thomasmock/demo-project/analysis"

my_csv <- here::here("data", "penguins.csv")

• RMarkdown + here vignette
• Use here with RMarkdown + RStudio Projects

Creating a document

In RStudio:

• File > New RMarkdown
• Cmd + Shift + P > Create a new R Markdown document
• rstudioapi::documentNew("---", type = "rmarkdown")

DEMO 💻

Insert new chunk

• Click +C (Insert new chunk buttom)
• Cmd + Shift + P > Insert a new code chunk
• Command (or Cmd) ⌘ + Option (or Alt) ⌥ + i (Mac)
• Ctrl + Alt + i (Windows/Linux)

DEMO 💻

Anatomy of a RMarkdown in RStudio

Anatomy of a RMarkdown in RStudio

• Undo-redo buttons
• Open in it's own Source window
• Save
• Automatically Knit/Render on save
• Initiate spell checking
• Find or Find and Replace

Anatomy of a RMarkdown in RStudio

Anatomy of a RMarkdown in RStudio

Anatomy of a RMarkdown in RStudio

Anatomy of a RMarkdown in RStudio

• Publish the document to RStudio Connect or RPubs.com
• Open/Close the Document Outline
• Toggle the Visual Editor mode

Take-aways

• ✔️ Document your document: use YAML to set up meaningful metadata
• ✔️ Style your document: use YAML to add options to your chosen output format
• ✔️ Organize your text: use markdown headers with #
• ✔️ Organize your code: use knitr chunk labels
• ✔️ Style your text: use markdown bold, italics, - bullets, and 1. lists
• ✔️ Style your output: use knitr chunk options

🧶 early, 🧶 often

ggplot2

Some data

mockdata_all <- read_csv(here::here("data/mockdata.csv")) %>% 
  mutate_at(vars(starts_with("ae_")), ~as.factor(.)) %>% 
  mutate(fu_fct = fct_recode(as.factor(fu_stat), 
                             "Lived" = "1", 
                             "Died" = "2"))

## Rows: 1499 Columns: 25
## ── Column specification ────────────────────────────────────────────────────────
## Delimiter: ","
## chr (10): arm, sex, race, age_ord, site, country, ethnicity, name, first_nam...
## dbl (15): case, age, fu_time, fu_stat, ps, hgb, bmi, alk_phos, ast, mdqualit...
## 
## ℹ Use `spec()` to retrieve the full column specification for this data.
## ℹ Specify the column types or set `show_col_types = FALSE` to quiet this message.

mockdata <- mockdata_all %>% 
  filter(!site == "Nur-Sultan")

Generate plots

surv_days_plot <- ggplot(mockdata) +
  aes(x = fu_time, y=arm, fill = fu_fct, 
      group = interaction(arm, fu_fct)) +
  ggridges::geom_density_ridges() +
  labs(x= "Survival Time in Days (Censored)", 
       y= "Study Arm") +
  scale_fill_manual(
    values = c("lightgrey", "#5C5CFF"),
    breaks = c("Died", "Lived"),
    name = "Follow-up status:") +
  theme_minimal() +
  theme(legend.position = "top")
surv_days_plot

## Picking joint bandwidth of 147

Control plots

Figure resolution

## Picking joint bandwidth of 147

## Picking joint bandwidth of 147

Figure resolution

## Picking joint bandwidth of 147

## Picking joint bandwidth of 147

Figure size

## Picking joint bandwidth of 147

## Picking joint bandwidth of 147

Figure size

{r, fig.retina=2, fig.dim=c(4,6)}

## Picking joint bandwidth of 147

Figure size

{r, fig.retina=2, fig.dim=c(8,6)}

## Picking joint bandwidth of 147

Arrange plots

The goal of patchwork is to make it ridiculously simple to combine separate ggplots.

library(patchwork)
p1 <- ggplot(mtcars) + geom_point(aes(mpg, disp))
p2 <- ggplot(mtcars) + geom_boxplot(aes(gear, disp, group = gear))
p1 + p2

One plot, two plot

age_histogram <- 
  ggplot(mockdata, aes(age)) +
  geom_histogram(color = 'white',
                 fill = "#5C5CFF", bins = 20) +
  labs(x = "Age", y = "Count") +
  scale_y_continuous(
    breaks = scales::pretty_breaks()) + 
  theme_minimal() +
  geom_hline(yintercept = 0)

age_histogram

One plot, two plot

# using fig.dim=c(8,4), fig.retina=2
surv_days_plot + age_histogram

## Picking joint bandwidth of 147

Labeled subplots

# using fig.dim=c(8,4), fig.retina=1
surv_days_plot + age_histogram + 
  plot_annotation(tag_levels = "A") # can set the tagging

## Picking joint bandwidth of 147

Labeled subplots

# using fig.dim=c(8,4), fig.retina=1
surv_days_plot + age_histogram + 
  plot_annotation(tag_levels = "1") # can alter the tagging

## Picking joint bandwidth of 147

Saving plots

fig.path - an alternative to calling ggsave() over and over!

I would encourage a past Silvia to experiment with code chunk options like dev=c("png", "pdf") and fig.path to streamline saving plots when knitting

Past Silvia used to specify these things using ggsave() lines after each ggplot, and that eventually became cumbersome ☺️

— Silvia Canelón (@spcanelon) December 1, 2020

A global setup chunk

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  warning = FALSE,
  message = FALSE,
  echo = FALSE,
  fig.retina = 2,
  fig.width = 6,
  fig.path = here::here("tom-figs/")
)
```

You should experiment with your "defaults" so that you have to minimally change the individual chunks.

Tables

Given the duration of this workshop, a deep dive on tables is out of scope. In short, depending on the output (HTML, PDF, Office) you'll likely lean on specific packages. You can always output tables as an image (ie .png) and embed like you would a plot, but note that you lose the accessible benefit of a table in that case.

Great R packages for tables:

• gt: Aiming to be a grammar of tables, as ggplot2 is an implemementation of the grammar of graphics.
• gtsummary: a great package for quickly summarizing data or common statistical outputs.
• flextable: flexible package for output, especially powerful in that it can output tables to Word/Powerpoint.
• gtExtras: my own package, primarily for embedding many data visualizations into gt tables.
• kableExtra: very stable and easy to use package for quickly creating tables in HTML/LaTeX (ie PDF).
• bstfun: A miscellaneous collection of functions to used by members of the Biostatistics Department at MSKCC

gtsummary

I am a huge fan of gtsummary and gt. gtsummary is especially powerful as it combines common tasks with rich support for outputs (Word, PDF, HTML). It is a wrapper around several packages with many additional capabilities built in.

library(gtsummary)
library(tidyverse)
library(survival)

Examples

select(trial, trt, age, grade, response) %>%
  tbl_summary(by = trt)

bstfun adds some fun!

My own package gtExtras can be used natively with gt, and Daniel has wrapped it to be supported in gtsummary!

library(gtsummary)
select(trial, age, marker) %>%
  tbl_summary(missing = "no") %>%
  bstfun::add_sparkline() # brought in from gtExtras

t1 <-
  glm(response ~ trt + grade + age, trial, family = binomial) %>%
  tbl_regression(exponentiate = TRUE)
# time to death Cox model
t2 <-
  coxph(Surv(ttdeath, death) ~ trt + grade + age, trial) %>%
  tbl_regression(exponentiate = TRUE)
# printing merged table
combo_tab <- tbl_merge(
  tbls = list(t1, t2),
  tab_spanner = c("**Tumor Response**", "**Time to Death**")
)

-

More details on parameters and workflow

• RMarkdown book, parameterized reports

• RMarkdown Cookbook, Parameterized reports

• Advanced RMarkdown webinar

Remember, it's all just code!

The different outputs are used for their specific purposes, but remember that the way of writing, adding code, etc is shared across them all!

Learn RMarkdown and R, and you can use your code to generate:

• Plots
• Tables
• Text
• Reports
• Presentations
• Websites
• Books
• Whatever you can think of!

html_document

The "workhorse" of RMarkdown, this is the default format. Amazing amount of power in HTML and has the richest feature set.

RMarkdown - html_document

pdf_document

Useful when you prefer LaTeX instead of HTML, or if you need PDF as an output.

RMarkdown - pdf_document

Office compliance

The Office standards, but created programatically with R and RMarkdown!

word_document

RMarkdown word_document

powerpoint

RMarkdown powerpoint

xaringan

Exceptionally powerful/beautiful presentations created with RMarkdown.

RMarkdown xaringan

distill

My personal favorite format, scientific writing native to the web!

Distill for R Markdown is a web publishing format optimized for scientific and technical communication. Distill articles include:

• Reader-friendly typography that adapts well to mobile devices.
• Features essential to technical writing like LaTeX math, citations, and footnotes.
• Flexible figure layout options (e.g. displaying figures at a larger width than the article text).
• Attractively rendered tables with optional support for pagination.
• Support for a wide variety of diagramming tools for illustrating concepts.
• The ability to incorporate JavaScript and D3-based interactive visualizations.
• A variety of ways to publish articles, including support for publishing sets of articles as a Distill website or as a Distill blog.

Distill for RMarkdown

bookdown

Write entire books in RMarkdown! The RMarkdown book itself was written this way.

RMarkdown bookdown

Resources

• RMarkdown Homepage

• RMarkdown package docs

• RMarkdown learning track

• RMarkdown: The Definitive Guide

• The RMarkdown Cookbook

• Visual RMarkdown Guide

• R4DS Rmarkdown - Communicate

• RMarkdown Driven Development

• RMarkdown for Scientists