Writing dynamic and reproducible documents

class: center, middle, inverse, title-slide

# Writing dynamic and reproducible documents
## An introduction to R Markdown
### Olivier Gimenez
### last updated: 2021-03-21

---

# Credits

- Garrett Grolemund [RStudio webinar](https://github.com/garrettgman/webinars/tree/master/12-Getting-started-with-R-Markdown)

![](img/garrett.jpg)

- Ulrik Lyngs [workshop material](https://github.com/ulyngs/rmarkdown-workshop-2019)

![](img/ulrik2.jpg)

---

.center[![](assets/img/trio.jpg)]

---
# Literate programming

* A programming paradigm introduced by Donald E. Knuth

* Treat program as literature meant to be understandable to human beings

*  Makes it easy to comment code, and share your analyses/thoughts with collaborators

* Move away from writing programs in the manner and order imposed by the computer

* Focus instead on the logic and flow of human thought and understanding

* Single document to integrate data analysis (executable code) with textual documentation, linking data, code, and text

---
# R Markdown workflow

.center[![](assets/img/rmarkdown_workflow.png)]

---
# Structure of a R Markdown document
.center[![](assets/img/rmd_struc.png)
https://yongfu.name/2019-fju-rmd-talk/slide/#1
]

---
class: inverse, center, middle
# Demo

Open RStudio

Create a new Rmd file

Identify 3 components (frontmatter, content, chunks)

---

.center[![](assets/img/3components.png)]

---

.center[![](assets/img/3componentson.png)]

---
# Structure of a R Markdown document
.center[![](assets/img/rmd_struc.png)]

---
# Structure of a R Markdown document
.center[![](assets/img/rmd_struc_markdown.png)]

---
class: inverse, center, middle
# Format your text with Markdown

---
# What is Markdown?

- A way to write stuff
- Mostly plain words, with some formating

.center[![](assets/img/md.png)]

---
# Websites that use Markdown

- GitHub <https://github.com/>
- StackOverflow <https://stackoverflow.com/>
- HackMD <https://hackmd.io>
- Many more

---
# Headers

- Use # to create headers
- Multiple #'s create lower level headers

.center[![](assets/img/headers.png)]

---
# Text

- Text is rendered as plain text

.center[![](assets/img/text.png)]

---
# Lists

- Use asterisks to make bullet points
- Use numbers to make numbered lists
- Use 4 spaces or 1 tab for indentation

.center[![](assets/img/lists.png)]

---
# Hyperlinks

- To add a hyperlink, put your text between brackets
- Then place the URL between parentheses

.center[![](assets/img/url.png)]

---
# Equations

- Write equations with Latex syntax

.center[![](assets/img/eqns.png)]

---
# Equation blocks

.center[![](assets/img/eqns2.png)]

---
# Images

- Use a link preceded by an ! to insert an image
- The link text should be
    - a URL if the image is hosted online
    - a file path if the image is saved on your computer

.center[![](assets/img/images.png)]

---
# Tables

```md
| header A | header B |
|---------:|:---------|
| data     | data     |

Table:title

```

- A bit of a hassle...

- Use a [generator of Tables for Markdown](https://www.tablesgenerator.com/markdown_tables)

- Wait for next section to learn how to generate tables from `R`

---
# R Markdown Reference Guide

<https://rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf>

.center[![](assets/img/refguide.png)]

---
# Structure of a R Markdown document
.center[![](assets/img/rmd_struc.png)]

---
# Structure of a R Markdown document
.center[![](assets/img/rmd_struc_chunks.png)]

---
class: inverse, center, middle
## Code, figures and tables

---
# Embed code

- Insert chunk of `R` code
- R Markdown runs code and includes results.

.center[![](assets/img/embed.png)]

---
# Inline code

- Place code in a sentence with 
- R Markdown replaces code with results

.center[![](assets/img/inline.png)]

---
# Chunk options
 
- By default, R markdown includes both code and results

.center[![](assets/img/chunk_options.png)]

---
# echo

- Add options between brackets after `r`.
- `echo = FALSE` hides code.

.center[![](assets/img/echo.png)]

---
# echo

- Add options between brackets after `r`.
- `echo = FALSE` hides code.

.center[![](assets/img/echo2.png)]

---
# eval

- `eval = FALSE` prevents code from being run  
- No results is displayed, only code

.center[![](assets/img/eval.png)]

---
# fig.height, fig.width

- Specify dimension of plots (in inches) with fig.width and fig.height
- Separate multiple arguments with commas.

.center[![](assets/img/figheightfigwidth.png)]

---
# message

- `message = FALSE` prevents messages from appearing
in output

.center[![](assets/img/message.png)]

---
# Default chunk options

- Repeating chunk options can be painful

- If you have `echo = FALSE` in every single chunk, how to set the default chunk option to `echo = FALSE` ?

- Use `knitr::opts_chunk$set(echo = FALSE)`

- You may overwrite the default for each chunk

- For chunk options, check out <https://yihui.name/knitr/options/>

---
# Cache time-consuming code chunks

- When you time-consuming calculations (simulations, Bayes stuff), and/or a looooong document

- Use `cache = TRUE` in all chunks or the chunk that takes long to compile

- Skip execution if executed before and nothing has changed since then

- If you do modifications to the cached chunk(s), previous cache will be automatically invalidated, and new cache is built

---
# Including tables

```r
# cars is a built-in-to-R data set of cars
# and their stopping distances
cars %>% 
  head(5) %>% 
  knitr::kable(format = "html", caption = "A kable table")
```

<table>
<caption>A kable table</caption>
 <thead>
  <tr>
   <th style="text-align:right;"> speed </th>
   <th style="text-align:right;"> dist </th>
  </tr>
 </thead>
<tbody>
  <tr>
   <td style="text-align:right;"> 4 </td>
   <td style="text-align:right;"> 2 </td>
  </tr>
  <tr>
   <td style="text-align:right;"> 4 </td>
   <td style="text-align:right;"> 10 </td>
  </tr>
  <tr>
   <td style="text-align:right;"> 7 </td>
   <td style="text-align:right;"> 4 </td>
  </tr>
  <tr>
   <td style="text-align:right;"> 7 </td>
   <td style="text-align:right;"> 22 </td>
  </tr>
  <tr>
   <td style="text-align:right;"> 8 </td>
   <td style="text-align:right;"> 16 </td>
  </tr>
</tbody>
</table>

- The [`kable`](https://www.rdocumentation.org/packages/knitr/versions/1.21/topics/kable) package is often used with the [`kableExtra`](https://cran.r-project.org/web/packages/kableExtra/vignettes/awesome_table_in_html.html) package
- A number of other packages are available for making pretty tables, see [rmarkdown.rstudio.com](https://rmarkdown.rstudio.com/lesson-7.html)

---
# R Markdown Reference Guide

<https://rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf>

.center[![](assets/img/knitr.png)]

---
# Structure of a R Markdown document
.center[![](assets/img/rmd_struc.png)]

---
# Structure of a R Markdown document
.center[![](assets/img/rmd_struc_yaml.png)]

---
class: inverse, center, middle
# YAML Yet Another Markup Language

---
# YAML in brief

- Contains the metadata of the document

- Starts and ends by three dashes

- Comes first in the document

---
# Simplest example

.center[![](assets/img/yaml.png)]

---
# Output formats

.center[![](assets/img/output_formats.png)]

---
# Knit

---
# Output formats

.center[![](assets/img/knit_rstudio.png)]

---
# Appearance and style

- In HTML output, you can use `theme` or a custom **.css** style sheet

- `theme` options ([bootswatch.com](https://bootswatch.com/)) : *“cerulean”, “journal”, “flatly”, “darkly”, “readable”, “spacelab”, “united”, “cosmo”, “lumen”, “paper”, “sandstone”, “simplex”, “yeti”*

- You may also use LaTeX templates with R Markdown, and write [reproducible scientific paper](https://github.com/rstudio/rticles)

- You can also [use Word templates in R Markdown](http://rmarkdown.rstudio.com/articles_docx.html) (see also [this short video](https://vimeo.com/110804387))

---
# Managing bibliography

--
<ol>
<li> Put references in a plain text file with the extension **.bib**, in **BibTex** format (my advice: use [Zotero](https://www.zotero.org))
</ol>
```bibtex
*@article{Shea2014,
  author =        {Shea, Nicholas and Boldt, Annika},
  journal =       {Trends in Cognitive Sciences},
  pages =         {186--193},
  title =         {{Supra-personal cognitive control}},
  volume =        {18},
  year =          {2014},
  doi =           {10.1016/j.tics.2014.01.006},
}
```

--
<ol start = 2>
<li>Reference this file in your YAML header
</ol>
```yaml
---
title: "Citation test"
*bibliography: example.bib
output: html_document
---
```

---
# Citations
<ol start = 3>
<li>In your text, citations go inside brackets and separated by semicolons
</ol>

--
.pull-left[
### This...
Blah blah [@Shea2014; @Lottridge2012].
]

.pull-right[
### turns into this...
  
Blah blah (Shea et al. 2014; Lottridge et al. 2012).
]
---
class: larger-body
# Citations
<ol start = 3>
<li>In your text, citations go inside brackets and separated by semicolons
</ol>

.pull-left[
### This...
Blah blah [@Shea2014; @Lottridge2012].

@Shea2014 says blah.

Blah blah [see @Shea2014, pp. 33-35; also @Wu2016, ch. 1].
]

.pull-right[
### turns into this...
  
Blah blah (Shea et al. 2014; Lottridge et al. 2012).

Shea et al. (2014) says blah.

Blah blah (see Shea et al. 2014, 33–35; also Wu 2016, ch. 1).
]

---
class: larger-body
# Citations
<ol start = 3>
<li>In your text, citations go inside brackets and separated by semicolons
</ol>

.pull-left[
### This...
Blah blah [@Shea2014; @Lottridge2012].
  
@Shea2014 says blah.

Blah blah [see @Shea2014, pp. 33-35; also @Wu2016, ch. 1].
]

.pull-right[
### turns into this...
  
Blah blah (Shea et al. 2014; Lottridge et al. 2012).

Shea et al. (2014) says blah.

Blah blah (see Shea et al. 2014, 33–35; also Wu 2016, ch. 1).
]

- Add e.g `csl: my-style.csl` in the YAML header to change to other formats
- Browse through and download styles at [zotero.org/styles](https://www.zotero.org/styles)

---
# Citations

For an easy way to insert citations, try the [`citr`](https://github.com/crsh/citr) RStudio add-in.

---
# R Markdown Reference Guide

<https://rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf>

.center[![](assets/img/pandoc.png)]

---

.center[![](assets/img/sorcerers.jpg)]

---
class: inverse, center, middle
## What else can we reproduce with R Markdown?

---
# Let's have a tour

R Markdown gallery <https://rmarkdown.rstudio.com/gallery.html>

---
# Websites

- Use package `blogdown` <https://bookdown.org/yihui/blogdown/>

- Customize with Hugo <https://themes.gohugo.io/>

- Deploy via GitHub pages or Netlify

- See a video tutorial [here](https://www.youtube.com/watch?v=4OUEss2XF7E&t=4s)

---

# Reproducibility and collective work

* How to work with Word using [`redoc`](https://bookdown.org/yihui/rmarkdown-cookbook/word-redoc.html): generate a Word document, revise the Word document, and convert the revised Word document back to R Markdown

* How to collaborate on Rmd documents with [Google Drive](https://bookdown.org/yihui/rmarkdown-cookbook/google-drive.html).

---
##

.center[![](assets/img/repro_rmarkdown.jpg)]

---
class: inverse, center, middle
## To go further

---
# Books

![](assets/img/books.png)