Writing dynamic and reproducible documents

class: center, middle, inverse, title-slide

# Writing dynamic and reproducible documents
## An introduction to R Markdown
### Olivier Gimenez
### November 2020

---

# Credits

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

![](assets/img/garrett.jpg)

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

![](assets/img/ulrik2.jpg)

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

---
<iframe width="1300" height="600" src="https://www.youtube.com/embed/s3JldKoA0zw" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

Credit: [Ignasi Bartomeus, PhD](https://bartomeuslab.com/)

---
#

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

---
# How can you reproduce results?

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

---
# What do we need to make research reproducible?

- Something to integrate text, figures and code 
     * `R`, `Python`, etc

- Something that can be continuously edited and updated 
     * Living or dynamic document

- Something that can be easily used in versioning tools
     * Git

---

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

---
# 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/>

---
# 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

---
class: inverse, center, middle
# Live demo
## Build your own website in a few minutes

---
##

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

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

---
# Books

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

---
class: title-slide-final, middle
background-size: 55px
background-position: 9% 15%

# Thanks!

### I created these slides with [xaringan](https://github.com/yihui/xaringan) and [R Markdown](https://rmarkdown.rstudio.com/) using the [rutgers css](https://github.com/jvcasillas/ru_xaringan) that I slightly modified.

### Credit: I borrowed slides from [Garrett Grolemund](https://rstudio.com/speakers/garrett-grolemund/) and [Ulrik Lyngs](https://ulriklyngs.com/). I also used the beautiful illustrations shared by [Allison Horst](https://github.com/allisonhorst/stats-illustrations).

|                                                                                                            |                                   |
| :--------------------------------------------------------------------------------------------------------- | :-------------------------------- |
| <i class="fas  fa-envelope "></i> | **olivier.gimenez@cefe.cnrs.fr**       |
| <i class="fas  fa-home "></i> | [**https://oliviergimenez.github.io/**](https://oliviergimenez.github.io/) |
| <i class="fab  fa-twitter "></i> | [**@oaggimenez**](https://twitter.com/oaggimenez)                         |
| <i class="fab  fa-github "></i> | [**@oliviergimenez**](https://github.com/oliviergimenez)