Introduction to R Markdown

• Reports

• Slides

• Manuscripts / books

• Simple websites

• R code and interpretations integrated into a single document

• Separates task of reporting the results from formatting the results:

  • decreases risk of copy-paste errors

  • decreases workload

• Quickly create the same document in different formats, e.g. slides to show and handouts for the audience

source: rstudio.com

whatever format you want to create: html, pdf, docx, …

image source: rstudio.com

pandoc: “an open-source document converter” (wikipedia). Translates markup from one type of format, e.g. markdown, to another

image source: rstudio.com

md: a document written in markdown, “a lightweight markup language with plain text formatting syntax” (wikipedia). Github also uses markdown.

image source: rstudio.com

knitr: an R package for creating reports directly in R. Will translate your R markdown document (Rmd), including embedded R code, to a plain markdown document

image source: rstudio.com

Rmd: file type recognized by RStudio. This is where everything goes: your header, R code chunks, and your content written in markdown

image source: rstudio.com

From RStudio, go to File > New File > R Markdown...

This is what my code chunk looks like for the previous slide:

```{r, out.width = paste0(image_scaler*400,"px"), echo = F}
include_graphics("images/knit_menu.png")
```

1. Download R (https://cran.r-project.org/)
2. Download RStudio to interface with R (https://posit.co/)
3. Go to https://github.com/psboonstra/markdown-workshop, then ‘Code’, then ‘Download ZIP’

1. Unzip the folder, then open the .RProj file
2. In RStudio, click on ‘Files’ at the bottom, and pull up 01-exercise.Rmd

1. Go to https://posit.cloud/ > Get Started
2. Create an account
3. Click the dropdown menu next to the New Project button, and enter the workshop URL of the workshop repository: https://github.com/psboonstra/markdown-workshop
4. Click on ‘Files’ at the bottom, and pull up 01-exercise.Rmd

Complete the tasks in 01-exercise.Rmd.

• Markdown tries to focus on simplicity
• Chunk options control how the chunk is evaluated and used
• You can knit the same document to different formats (sometimes easy to do, sometimes requires a bit of finagling)
• Consider using in-line chunks instead of hard-coding results

If you name a variable in an earlier code chunk, you can refer to it again in a later chunk.

x <- rnorm(20)
y <- 3 * x + rnorm(length(x))
foo = tibble(x = x, y = y)

library(ggplot2)
ggplot(data = foo) + 
  geom_point(aes(x, y))

foo

## # A tibble: 20 × 2
##           x       y
##       <dbl>   <dbl>
##  1  2.05     7.38  
##  2  0.660    3.73  
##  3 -0.344    1.03  
##  4 -0.121    0.0591
##  5 -0.0144  -0.709 
##  6  0.930    2.83  
##  7  0.00650  1.12  
##  8  0.654    2.24  
##  9 -0.0899  -1.86  
## 10 -0.477   -2.51  
## 11 -1.63    -4.74  
## 12  0.254    0.449 
## 13  0.858    1.11  
## 14  1.47     4.31  
## 15  1.82     4.23  
## 16 -1.06    -3.48  
## 17 -0.392   -2.99  
## 18 -0.589   -3.33  
## 19 -0.269   -0.0198
## 20 -3.54    -9.32

kable(foo)

If something (a new header option, a code chunk, etc) is not working as you expect, try adding an additional linebreak

If experimenting with a new feature, re-knit frequently

If, like me, you become a compulsive re-knitter, the code chunk option cache = TRUE is both useful and dangerous.

```{r, cache = TRUE}
# some intensive task
```

As long as you don’t change anything in the chunk, you won’t need to re-run the intensive task upon re-knitting. However, things can go awry…

• Open the file caching_mishap.Rmd and make sure you understand the intended behavior (should be trivial!)

• Knit the document

• Now edit your first chunk, changing to x <- rnorm(n = 1, mean = 0) and leaving the second chunk alone

• Re-knit your document

That’s how we get results like this:

x <- rnorm(n = 1, mean = 0)

x

## [1] 100.71

What happened

We invalidated the cache in the first chunk (triggering it to run again) without invalidating the cache in the second chunk (so it was left alone)

Possible solutions

• Consider if the chunks should be combined

• You can invalidate a cache by adding a comment character (#) at the end of a line, or making some other innocuous change to your chunk. Even extra white space will invalidate the cache

• Go to Knit > Clear Knitr Cache... or delete directly the folder ending in [filename]_cache in your working directory

#RMarkdown question: If I cache the chunk that loads the R packages, then I sometimes (not always) get random errors from downstream chunks that can't find a loaded function, as if it wasn't loaded. Un-cache-ing the chunk seems to fix the problem. Anyone else encounter this?

— Philip Boonstra ((psboonstra?)) February 9, 2021

The cache mechanism is not to be used with code chunk that have side effect used by other chunks - loading package that are used by other chunk is one of this. See more in :https://t.co/bpKPzkFMad
If you activate cache globally you need to se cache=FALSE

— Christophe Dervieux ((chrisderv?)) February 10, 2021

The most appropriate use case of caching is to save and reload R objects that take too long to compute in a code chunk, and the code does not have any side effects, such as changing global R options via options() (such changes will not be cached). If a code chunk has side effects, we recommend that you do not cache it.

Section 11.4, RMarkdown Cookbook

Including

• Python

• SQL

• Julia

• Stan

• Javascript

Use ```{python} to start a python code chunk, ```{julia} to start a julia code chunk, ```{bash} to start a Shell script, etc.

You may need external language engines to successfully call other languages. I have not used this functionality before.

see Chapter 2.7, R Markdown: The Definitive Guide

You are not limited to using Markdown in Rmd files – you can knit R scripts using the same shortcut: Cmd+Shift+K / Ctrl+Shift+K

• Use #' to indicate a switch to markdown

• Use #+ to start a new chunk

Open 02-exercise.R and complete the tasks.

<iframe src="https://isitchristmas.com/"></iframe> 

yields

Part of the tidyverse (along with dplyr and ggplot2):

https://www.tidyverse.org/

readr gives you tools to read in data from files outside R, wrangled and manipulated, and then written to files outside R:

The workhorse of the readr package is read_csv, which reads a comma-separated value (csv) file into R as a data.frame From the help page:

read_csv(file, col_names = TRUE, col_types = NULL, locale = default_locale(), 
na = c("", "NA"), quoted_na = TRUE, quote = "\"", comment = "", trim_ws = TRUE, 
skip = 0, n_max = Inf, guess_max = min(1000, n_max), progress = show_progress(), 
skip_empty_rows = TRUE)

Typical use is my_data <- read_csv("my_files_path.csv")

Get your current working directory in R:

getwd()

## [1] "/Users/philb/Desktop/Work/BDSI2023/markdown-workshop"

How did R know this was my desired working directory? Why did I not need to do this:

setwd("/Users/philb/Desktop/Work/BDSI2023/markdown-workshop")

Your working directory is automatically set when you work inside an R project.

To create an R project, go to File > New Project... > Existing Directory and choose your folder

To open an existing R project, find the .Rproj file or go to File > Open Project...

• $n=37$ mice implanted with human tumor
• Randomized to one of three treatment groups (radiation only; drug only; or both drug and radiation) or no treatment
• Each tumor on each mouse measured daily for up to 4 weeks
• Available at American Statistical Association’s Section on Teaching of Statistics in the Health Sciences (TSHS) data portal
• File is called tumor_growth.csv

Varna, Bertheau, and Legrès (2014)

(tumor_growth <- read_csv("tumor_growth.csv"))

## # A tibble: 574 × 5
##    Grp   Group    ID   Day   Size
##    <chr> <dbl> <dbl> <dbl>  <dbl>
##  1 1.CTR     1   101     0   41.8
##  2 1.CTR     1   101     3   85  
##  3 1.CTR     1   101     4  114  
##  4 1.CTR     1   101     5  162. 
##  5 1.CTR     1   101     6  178. 
##  6 1.CTR     1   101     7  325  
##  7 1.CTR     1   101    10  624. 
##  8 1.CTR     1   101    11  648. 
##  9 1.CTR     1   101    12  836. 
## 10 1.CTR     1   101    13 1030. 
## # ℹ 564 more rows

Open 03-exercise.Rmd and complete the tasks.

https://rmarkdown.rstudio.com/

R Markdown on RStudio.com

R Markdown: The definitive guide

• Free, online version of a book written by the RStudio experts

R Markdown cheatsheet

• Helpful quick reference

Mastering markdown

• Reference site for markdown langauge

Project-oriented workflow

• The benefits of working in self-contained projects