RMarkdown Basics

class: center, middle, inverse, title-slide

# RMarkdown Basics
### Haley Jeppson, Sam Tyner
### 2018/06/08

---

class: primary
# What do you use to write?

- Microsoft Word 
- LaTeX / Overleaf
- Pages 
- Google Docs 
- Others?

Have you ever had to put math or graphs in those? How did you do it?

---
class: primary
# Another way...

- RMarkdown documents (.Rmd)
- Put results from `R` directly into your writing
- Fosters reproducibility and transparency

---
class: primary
# Hello RMarkdown!

---
class: primary
# Choose your output format!

---
class: primary
# Why RMarkdown?

- It's **simple**. Focus on writing, rather than debugging silly errors (I'm looking at you *LaTeX*).

- It's **flexible**. Markdown was created to simplify writing HTML, but thanks to [pandoc](http://pandoc.org/), Markdown converts to many different formats!

- It's **dynamic**. Find a critical error? Get a new dataset? Regenerate your report without copy/paste hell!

- Encourages **transparency**. Collaborators (including your future self) will thank you for integrating your analysis & report.

- Enables **interactivity/reactivity**. Allow your audience to explore the analysis (rather than passively read it).

---
class: primary
# What is Markdown?

- Markdown is a particular type of markup language.

- Markup languages are designed produce documents from plain text.

- *LaTeX* is another (less human friendly) markup language for creating pdf documents.

- *LaTeX* gives you much greater control, but it is restricted to pdf and has a **much** greater learning curve.

- Markdown is becoming a standard. Many websites will generate HTML from Markdown (e.g. GitHub, Stack Overflow, reddit).

---
class: primary
# Who's using it? For what?

* The [R Markdown website](http://rmarkdown.rstudio.com/) is built with R Markdown.

* The [new edition of the ggplot2 book](https://github.com/hadley/ggplot2-book/) uses it.

* R package vignettes (for example, [this one for `plotly`](http://cpsievert.github.io/plotly/pipe-dsl/)).

* [Many](http://lincolnmullen.com/projects/dh-r/index.html) great [books](https://bookdown.org/yihui/blogdown/) use R markdown! You can write a whole book in RMarkdown with [`bookdown`](https://bookdown.org/)

* People are [blogging with it](https://juliasilge.com/).

* Our [website](https://csafe-isu.github.io/reu18/)

* Sam's [website](https://sctyner.github.io/)

---
class: primary
# What is RMarkdown?

* Straight from the [R Markdown home page](http://rmarkdown.rstudio.com/):

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

---
class: primary
# Your Turn 7.1

Study the first page of the [R Markdown Cheatsheet](https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf).

Yes, the *entire* markdown syntax can be described in one page!

Can you think of anything that is missing from the syntax (that you might want when creating documents)?

---
class: primary
# Contents of a .Rmd

1. The YAML front matter
2. The markdown
3. Code chunks

---
class: primary
# YAML Front Matter

The stuff at the top of the .Rmd file (called YAML front matter) tells **rmarkdown** what output format you want.

```
---
title: "Untitled"
author: "Sam Tyner"
date: "June 7, 2018"
output: html_document
---
```

In this case, when you click "Knit HTML", RStudio calls `rmarkdown::render("file.Rmd", html_document())`. You can certainly change these default values (see the [source of this presentation](https://raw.githubusercontent.com/cpsievert/slides/gh-pages/rmd/index.Rmd)). <- FIX  THIS LINK!

---
class: primary
# Markdown

Any writing, written using the Markup syntax

```
This is a really smart sentence you wrote.

You also cite your work [@ref1].

You also emphasize *important* words. 
```

---
class: primary
# What is a code chunk?

A code chunk is a concept borrowed from the [knitr](http://yihui.name/knitr/) package (which, in turn, was inspired by [literate programming](http://en.wikipedia.org/wiki/Literate_programming)). In .Rmd files, you can start/end a code chunk with three back-ticks.

````
```{r, eval=TRUE}
1 + 1
```
2
````

---
class: primary
# Code chunk options

There are a plethora of [chunk options](http://yihui.name/knitr/options/) in **knitr** (engine is one of them). Here are some that I typically use:

* `echo`: Show the code?
* `eval`: Run the code?
* `message`: Relay messages?
* `warning`: Relay warnings?
* `fig.width` and `fig.height`: Change size of figure output.
* `cache`: Save the output of this chunk (so we don't have to run it next time)?

---
class: primary
# Your Turn 7.2

Study the second page of the [R Markdown Reference Guide](https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf) and go back to the Hello R Markdown example we created.

**Easy**: Modify the figure sizing and alignment.

**Medium**: Add a figure caption.

**Hard**: Can you create an animation? (Hint: look at the `fig.show` chunk option -- you might need to the **animation** package for this)

**Pro Tip**: Don't like the default chunk option value? Change it at the top of the document:

```r
knitr::opts_chunk$set(message = FALSE, warning = FALSE)
```

---
class: primary
# Formatting Tabular Data

The function `knitr::kable()` will render a markdown table from a data frame:

````
```{r, , results='asis'}
dat <- head(cars)
knitr::kable(dat)
```
````

shows as

<table>
 <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>
  <tr>
   <td style="text-align:right;"> 9 </td>
   <td style="text-align:right;"> 10 </td>
  </tr>
</tbody>
</table>

---
class: primary
# Formatting R output

Other options:

- [pander](http://rapporter.github.io/pander/) 
- [xtable](https://CRAN.R-project.org/package=xtable)

---
class: primary
# Your Turn 7.3

- Re-create a plot from one of the `ggplot2` slide sets and create an RMarkdown document that contains some written content in addition to the plot. Explore the many chunk options for plots to do this.

- **Bonus:** Use `knitr::include_graphics()` to include an image from your computer or the web from within an R code chunk.