R Markdown

<br>

# R Markdown

<br>

## Florian Privé & Julyan Arbel

### April 11, 2019

<br>

**Slides:** `bit.ly/RUGgre18`

<br>

<small>(adapted with permission from [Antoine Bichat's presentation](https://abichat.github.io/slides/sciencecommunication/))</small>

---

# R Markdown

---

## R Markdown?

<br>

* Markdown is a _lightweight markup language_ with plain text formatting syntax that can be converted to many formats, including HTML.    
It is completely independent from R.    
The extention is typically `.md`.

* R Markdown is an extension of the markdown syntax that enables R code to be executed. The extention is typically `.Rmd`.

* {rmarkdown} is an R package that proceses and converts `.Rmd` files into a number of different formats, including HTML, PDF and Word.

---

## Create a new `.Rmd` in RStudio

.pull-left[
.center[
  <img src="https://abichat.github.io/slides/sciencecommunication/CreateRmd1.png" width="400">
]
]

.pull-right[
  <div style = "margin-top: 80px"></div> 
  .center[
    <img src="https://abichat.github.io/slides/sciencecommunication/CreateRmd2.png" width="400">
  ]
]

---

## New `.Rmd`

.center[
  <img src="https://abichat.github.io/slides/sciencecommunication/CreateRmd3.png" width="700">
]

---

## Compile `.Rmd`

Use the `Knit` button to produce a HTML file

.center[
  <img src="https://abichat.github.io/slides/sciencecommunication/CreateRmd4.png" width="300">
]

<br>

Shortcut: `Ctrl + Shift + K`

---

# Markdown syntax

---

## Titles and text fonts in Markdown

```
# Big title

## Title

### Small title

_Italic_, *italic*, __bold__, **bold**, and `monospace`
```

***

# Big title

## Title

### Small title

_Italic_, *italic*, __bold__, **bold**, and `monospace`

---

## Lists in Markdown

2. an ordered

3. list
```
1. This is

2. an ordered

3. list
]

* a bullet list

* with indent
```
* This is

* a bullet list

* with indent
]

<br>

- You can enumerate only with '`1.`'; it will increment automatically

- You can also use '`-`' or '`+`' instead of '`*`'

---

## More in Markdown

```
> You can insert quotes and $\LaTeX$ expressions
```

> You can insert quotes and `$\LaTeX$` expressions

<br>

```
$$ \frac{1}{n} \sum_{i=1}^n X_i $$
```

$$ \frac{1}{n} \sum_{i=1}^n X_i $$

<br>

- Make an horizontal line with '`***`'

- Add 4 spaces at the end of your text in order to write to the next line

- You can write HTML in Markdown (e.g. use '`<br>`' to get a blank line)

---

## Insert links and pictures

```
[Antoine's personal page](https://abichat.github.io/)
```

[Antoine's personal page](https://abichat.github.io/)

```
![](https://slides.yihui.name/gif/impossible-parking.gif)
```

![](https://slides.yihui.name/gif/impossible-parking.gif)

It also works directly with HTML syntax:

```
<a href="https://abichat.github.io/">Antoine's personal page</a>

<img src="https://slides.yihui.name/gif/impossible-parking.gif">
```

---

# Code chunks

---

## Basic chunk

````
```{r}
x <- 4
x
```
````

Output:

```
[1] 4
```

To display the output of a code chunk but not the underlying R code, you specify the `echo=FALSE` option

````
```{r, echo=FALSE}
x <- 5
x
```
````
]

To display R code without evaluating it, you specify the `eval=FALSE` chunk option

````
```{r, eval=FALSE}
x <- 5
```
````
]

---

## Figure options (1/2)

````
```{r, fig.align="center", out.width="60%"}
ggplot2::qplot(Sepal.Length, Sepal.Width, data = iris)
```
````

---

## Figure options (2/2)

````
```{r, fig.align="center", out.width="80%", fig.asp=0.7, fig.width=4}
ggplot2::qplot(Sepal.Length, Sepal.Width, data = iris)
```
````

---

## A better way to include pictures

````
```{r, fig.align="center", out.width="80%", echo=FALSE}
knitr::include_graphics(
  "https://slides.yihui.name/gif/impossible-parking.gif")
```
````

It allows you to use the chunk options for image size.

---

## FAQ: two figures side-by-side

````
```{r, echo=FALSE, out.width="50%", fig.show="hold", fig.align="default"}
plot(iris)
plot(iris, pch = 20, col = iris$Species)
```
````

---

# Options and Formats

---

## Supported languages in chunks

- R

- Python

- Shell

- SQL

- Rcpp

- Stan

- JavaScript

- CSS

- Julia

- C and Fortran

- [many others...](https://bookdown.org/yihui/rmarkdown/language-engines.html)

---

## Data frame printing and tables

You can play with YAML option `df_print`. For example, `df_print: paged`:

```r
iris   ## or directly with `DT::datatable(iris)`
```

<div data-pagedtable="false">
  <script data-pagedtable-source type="application/json">
{"columns":[{"label":["Sepal.Length"],"name":[1],"type":["dbl"],"align":["right"]},{"label":["Sepal.Width"],"name":[2],"type":["dbl"],"align":["right"]},{"label":["Petal.Length"],"name":[3],"type":["dbl"],"align":["right"]},{"label":["Petal.Width"],"name":[4],"type":["dbl"],"align":["right"]},{"label":["Species"],"name":[5],"type":["fct"],"align":["left"]}],"data":[{"1":"5.1","2":"3.5","3":"1.4","4":"0.2","5":"setosa"},{"1":"4.9","2":"3.0","3":"1.4","4":"0.2","5":"setosa"},{"1":"4.7","2":"3.2","3":"1.3","4":"0.2","5":"setosa"},{"1":"4.6","2":"3.1","3":"1.5","4":"0.2","5":"setosa"},{"1":"5.0","2":"3.6","3":"1.4","4":"0.2","5":"setosa"},{"1":"5.4","2":"3.9","3":"1.7","4":"0.4","5":"setosa"},{"1":"4.6","2":"3.4","3":"1.4","4":"0.3","5":"setosa"},{"1":"5.0","2":"3.4","3":"1.5","4":"0.2","5":"setosa"},{"1":"4.4","2":"2.9","3":"1.4","4":"0.2","5":"setosa"},{"1":"4.9","2":"3.1","3":"1.5","4":"0.1","5":"setosa"},{"1":"5.4","2":"3.7","3":"1.5","4":"0.2","5":"setosa"},{"1":"4.8","2":"3.4","3":"1.6","4":"0.2","5":"setosa"},{"1":"4.8","2":"3.0","3":"1.4","4":"0.1","5":"setosa"},{"1":"4.3","2":"3.0","3":"1.1","4":"0.1","5":"setosa"},{"1":"5.8","2":"4.0","3":"1.2","4":"0.2","5":"setosa"},{"1":"5.7","2":"4.4","3":"1.5","4":"0.4","5":"setosa"},{"1":"5.4","2":"3.9","3":"1.3","4":"0.4","5":"setosa"},{"1":"5.1","2":"3.5","3":"1.4","4":"0.3","5":"setosa"},{"1":"5.7","2":"3.8","3":"1.7","4":"0.3","5":"setosa"},{"1":"5.1","2":"3.8","3":"1.5","4":"0.3","5":"setosa"},{"1":"5.4","2":"3.4","3":"1.7","4":"0.2","5":"setosa"},{"1":"5.1","2":"3.7","3":"1.5","4":"0.4","5":"setosa"},{"1":"4.6","2":"3.6","3":"1.0","4":"0.2","5":"setosa"},{"1":"5.1","2":"3.3","3":"1.7","4":"0.5","5":"setosa"},{"1":"4.8","2":"3.4","3":"1.9","4":"0.2","5":"setosa"},{"1":"5.0","2":"3.0","3":"1.6","4":"0.2","5":"setosa"},{"1":"5.0","2":"3.4","3":"1.6","4":"0.4","5":"setosa"},{"1":"5.2","2":"3.5","3":"1.5","4":"0.2","5":"setosa"},{"1":"5.2","2":"3.4","3":"1.4","4":"0.2","5":"setosa"},{"1":"4.7","2":"3.2","3":"1.6","4":"0.2","5":"setosa"},{"1":"4.8","2":"3.1","3":"1.6","4":"0.2","5":"setosa"},{"1":"5.4","2":"3.4","3":"1.5","4":"0.4","5":"setosa"},{"1":"5.2","2":"4.1","3":"1.5","4":"0.1","5":"setosa"},{"1":"5.5","2":"4.2","3":"1.4","4":"0.2","5":"setosa"},{"1":"4.9","2":"3.1","3":"1.5","4":"0.2","5":"setosa"},{"1":"5.0","2":"3.2","3":"1.2","4":"0.2","5":"setosa"},{"1":"5.5","2":"3.5","3":"1.3","4":"0.2","5":"setosa"},{"1":"4.9","2":"3.6","3":"1.4","4":"0.1","5":"setosa"},{"1":"4.4","2":"3.0","3":"1.3","4":"0.2","5":"setosa"},{"1":"5.1","2":"3.4","3":"1.5","4":"0.2","5":"setosa"},{"1":"5.0","2":"3.5","3":"1.3","4":"0.3","5":"setosa"},{"1":"4.5","2":"2.3","3":"1.3","4":"0.3","5":"setosa"},{"1":"4.4","2":"3.2","3":"1.3","4":"0.2","5":"setosa"},{"1":"5.0","2":"3.5","3":"1.6","4":"0.6","5":"setosa"},{"1":"5.1","2":"3.8","3":"1.9","4":"0.4","5":"setosa"},{"1":"4.8","2":"3.0","3":"1.4","4":"0.3","5":"setosa"},{"1":"5.1","2":"3.8","3":"1.6","4":"0.2","5":"setosa"},{"1":"4.6","2":"3.2","3":"1.4","4":"0.2","5":"setosa"},{"1":"5.3","2":"3.7","3":"1.5","4":"0.2","5":"setosa"},{"1":"5.0","2":"3.3","3":"1.4","4":"0.2","5":"setosa"}],"options":{"columns":{"min":{},"max":[10]},"rows":{"min":[10],"max":[10]},"pages":{}}}
  </script>
</div>

For more refined tables, you can use `knitr::kable()`, `xtable::xtable()`, `kableExtra::kable().`

---

## Use R Markdown for..

<br>

- Reports (analysis, etc) with text, code and results in the same place! With many possible output formats including HTML, PDF, MS Word, etc.

- Notebooks (vs "Chunk Output in Console")

- Slides (like this one! -- see [source code](https://github.com/privefl/R-presentation/blob/master/rmarkdown.Rmd))

- Websites (such as [the website of our R user group](https://r-in-grenoble.github.io/))

- Books (e.g. my online [advanced R course](https://privefl.github.io/advr38book/) or even [a thesis](https://keurcien.github.io/book/introduction.html))

- [WIP] [{pagedown}](https://github.com/rstudio/pagedown): Paginate the HTML Output of R Markdown with CSS for Print

---

## Slides formats

- [ioslides](https://bookdown.org/yihui/rmarkdown/ioslides-presentation.html) ([example](https://privefl.github.io/R-presentation/pResentation.html))

- [slidy](https://bookdown.org/yihui/rmarkdown/slidy-presentation.html) ([example](https://www.jvcasillas.com/slidify_tutorial/))

- [beamer](https://bookdown.org/yihui/rmarkdown/beamer-presentation.html) (pdf)

- [powerpoint](https://bookdown.org/yihui/rmarkdown/powerpoint-presentation.html) (ppt)

- [xaringan / remark.js](https://bookdown.org/yihui/rmarkdown/xaringan.html) (example: this presentation!)

- [reveal.js](https://bookdown.org/yihui/rmarkdown/revealjs.html)

<br>

3 main reasons to make your slides with R Markdown:

1. Include code and results very easily

1. Make HTML presentations directly available online (easy to export them to PDF using "print to PDF" of Chrome)

1. Include fancy HTML widgets (like maps, searchable tables, interactive graphics, etc)

---

### Include an interactive map with {leaflet}

```r
library(leaflet)
leaflet(width = "100%") %>% 
  setView(lng = 5.767249, lat = 45.190590, zoom = 12) %>% 
  addTiles(options = providerTileOptions(minZoom = 2, maxZoom = 19))
```

<div id="htmlwidget-1a33bf536f135aa7f3a3" style="width:100%;height:360px;" class="leaflet html-widget"></div>
<script type="application/json" data-for="htmlwidget-1a33bf536f135aa7f3a3">{"x":{"options":{"crs":{"crsClass":"L.CRS.EPSG3857","code":null,"proj4def":null,"projectedBounds":null,"options":{}}},"setView":[[45.19059,5.767249],12,[]],"calls":[{"method":"addTiles","args":["//{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",null,null,{"errorTileUrl":"","noWrap":false,"detectRetina":false,"minZoom":2,"maxZoom":19,"attribution":"© <a href=\"http://openstreetmap.org\">OpenStreetMap<\/a> contributors, <a href=\"http://creativecommons.org/licenses/by-sa/2.0/\">CC-BY-SA<\/a>"}]}]},"evals":[],"jsHooks":[]}</script>

---

## Websites

<br>

Example: webpage of the [Grenoble RUG](https://r-in-grenoble.github.io/)

<br>

How does it work?

- just multiple Rmd documents (one by page) rendered as HTML with a common navigation bar

- host the static HTML pages using e.g. GitHub pages

- make your own website in 20 minutes with [this tutorial](https://github.com/privefl/rmarkdown-website-template)

.footnote[You can also use {blogdown}. See the [full documentation](https://bookdown.org/yihui/blogdown/).]

---

## Books

<br>

Every R book is now written with [{bookdown}](https://bookdown.org/yihui/bookdown/).

See many of them at https://bookdown.org/.

<br>

Again, from our side, it is just a collection of R Markdown documents.

E.g. see [my advanced R course](https://privefl.github.io/advr38book/) and [the associated GitHub repository](https://github.com/privefl/advr38book).

---

## Technical Documents

<br>

Formats in {bookdown} allows you to:

- number and reference equations, tables, figures, etc

- use special chunks such as theorems and proofs

- special headers such as "PART" and "APPENDIX"

- citations

- etc

<br>

To use this in single R Markdown documents (not books), you can use formats

- `bookdown::html_document2()`
- `bookdown::pdf_document2()`
- `bookdown::word_document2()`

---

# References

---

.pull-left[
<img src="https://bookdown.org/yihui/rmarkdown/images/cover.png" width="95%" style="display: block; margin: auto;" />
]

.pull-right[
<img src="https://bookdown.org/yihui/bookdown/images/cover.jpg" width="95%" style="display: block; margin: auto;" />
]

---

## Useful materials

* [Official website](https://rmarkdown.rstudio.com)

* [*R Markdown: The Definitive Guide*](https://bookdown.org/yihui/rmarkdown/)

* [*Authoring Books and Technical Documents with R Markdown*](https://bookdown.org/yihui/bookdown/)

* [Reference guide](https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf)

* [Cheat sheet](https://rmarkdown.rstudio.com/lesson-15.HTML)

* [Tips for R Markdown](https://holtzy.github.io/Pimp-my-rmd/)

* For less problems with LaTeX distributions: [{TinyTeX}](https://yihui.name/tinytex/)

* [Embed a File in the HTML Output of R Markdown](https://yihui.name/en/2018/07/embed-file/)

* [Xaringan documentation](https://slides.yihui.name/xaringan)

* [Decouple Code and Output in xaringan slides](https://www.garrickadenbuie.com/blog/2018/08/16/decouple-code-and-output-in-xaringan-slides/)

* [Tips for making slides](https://www.tidyverse.org/articles/2018/07/carpe-talk/)

---

# Thanks!

<br>

**Slides:** `bit.ly/RUGgre18`

<br>

<i class="fab  fa-twitter "></i> [privefl](https://twitter.com/privefl) &nbsp;&nbsp;&nbsp;&nbsp; <i class="fab  fa-github "></i> [privefl](https://github.com/privefl) &nbsp;&nbsp;&nbsp;&nbsp; <i class="fab  fa-stack-overflow "></i> [F. Privé](https://stackoverflow.com/users/6103040/f-priv%c3%a9)

<i class="fab  fa-twitter "></i> [JulyanArbel](https://twitter.com/JulyanArbel) &nbsp;&nbsp;&nbsp;&nbsp; <i class="fab  fa-github "></i> [jarbel](https://github.com/jarbel)