An introduction to R markdown

# >    📖 💻 >    R markdown
### Danielle Navarro

---

layout: true
 
<div class="my-footer">

</div>

---

## What are we going to cover?

- **Markdown:** a simple text-only format for writing documents
- **R markdown:** a tool for mixing R code with markdown

---

## What is the assumed knowledge?

- This is an introductory unit
- No previous knowledge of R is needed
- No previous knowledge of markdown needed

---

## What do I need to do before starting?

- Sign up for a free RStudio cloud account
- https://rstudio.cloud/

---

## Where can I find the resources?

- These slides: [slides.djnavarro.net/starting-rmarkdown](https://slides.djnavarro.net/starting-rmarkdown)
- YouTube videos: [youtube.djnavarro.net/starting-rmarkdown](https://youtube.djnavarro.net/starting-rmarkdown)

---

## R markdown is a "chimera"

### On the input side...

- Write text in markdown
- Insert code using R
- Write "metadata" with YAML
- Insert equation with LaTeX
]

---

## R markdown is a "chimera"

### On the output side...

- Output to HTML
- Output to PDF
- Output to Word
- Many other variations too
]

---

---

.pull-left-narrow[
 .huge-bisque-number[1]
]
.pull-right-wide[
 
.larger[.embolden[Stating the problem...]]

]

---

![](img/word_document_surface.png)

---

![](img/word_document_inside.png)

---

## Word documents are complicated

- A .docx file is a compressed folder with lots of files
- Your text is buried in with a lot of formatting information

---

---

![](img/html_document_inside.png)

---

## HTML documents are complicated

- Looks simple because I removed most formatting
- Still unpleasant to look at

---

]

---

## What do we want?

- Something that... you can write in **plain text**
- Something that... is **human readable**
- Something that... allows **formatting**
- Something that... can **build** to something pretty

---

---

Welcome to my **awesome** class. You will learn 
all kinds of useful things about R markdown.

## Why should you care?

- Markdown is simple and reproducible
- You can make it pretty if you want to
- The R Markdown variant lets you add R code

## Where can you find these slides?

https://slides.djnavarro.net/starting-rmarkdown
```
]

---

---

# Introduction

Welcome to my **awesome** class. You will learn 
all kinds of useful things about R markdown.

## Why should you care?

- Markdown is simple and reproducible
- You can make it pretty if you want to
- The R Markdown variant lets you add R code

## Where can you find these slides?

https://slides.djnavarro.net/starting-rmarkdown

---

## Notice the theme!

- My slides are written using markdown (...sort of)
- So the markdown output you see here matches the slides theme
- I'll talk about modifying themes later

---

---

---

## Professional websites

---

## Visual blogs

---

## Books

---

## Academic papers

---

## Slide decks

---

## Résumés

---

]

---

---

.pull-left-narrow[
 .huge-bisque-number[4]
]
.pull-right-wide[
 
.larger[.embolden[Starting markdown]]

]

---

---

## Emphasising text

--
.pull-left[
 
### What you type...
 
```

this is *italics*

this is **bold**

this is ***bold italics***
```
]
--
.pull-right[
 
### What you get...

this is *italics*

this is **bold**

this is ***bold italics***
]

---

## Creating lists

--
.pull-left[
 
### What you type...
 
```
- unnumbered lists
- look like this

1. numbered lists
2. look like this
```
]
--
.pull-right[
 
### What you get...

- unnumbered lists
- look like this

1. numbered lists
2. look like this
]

---

## Creating headings

--
.pull-left[
 
### What you type...
 
```
# Level 1 heading
## Level 2 heading
### Level 3 heading

```
]
--
.pull-right[
 
### What you get...

# Level 1 heading
## Level 2 heading
### Level 3 heading
]

---

---

- create your own RStudio Cloud project (see the demo)
- open a new plain markdown document
- save it as `my_first_markdown.md`
- write some markdown, build it to HTML file
- try to use all these markdown features

---

]

---

## Inserting hyperlinks

--
.pull-left-wide[
 
### What you type...
 
```
https://placekitten.com

[Placekitten](https://placekitten.com)
```
]
--
.pull-right-narrow[
 
### What you get...
 
https://placekitten.com

[Placekitten](https://placekitten.com)
]

---

## Inserting local images

--
.pull-left-wide[
 
### What you type...
 
```
![](./img/rmarkdown.png)
```
]
--
.pull-right-narrow[
 
### What you get...
 
![](./img/rmarkdown.png)
]

---

## Inserting images from the web

--
.pull-left-wide[
 
### What you type...
 
```
![](https://placekitten.com/200/300)
```
]
--
.pull-right-narrow[
 
### What you get...
 
![](https://placekitten.com/200/300)
]

---

## Using blockquotes

--
.pull-left[
 
### What you type...
 
```
This is normal text
> This is a block quote
```
]
--
.pull-right[
 
### What you get...
This is normal text
> This is a block quote
]

---

## Using nested lists

--
.pull-left[
 
### What you type...
 
```
1. First item in list 
2. Second item in list
 - first item in sub-list
 - second item in sub-list
3. Third item in list
```
]
--
.pull-right[
 
### What you get...
 
1. First item in list 
2. Second item in list
 - first item in sub-list
 - second item in sub-list
3. Third item in list
]

---

- go back to your RStudio Cloud project
- open your `my_first_markdown.md` document
- edit the markdown, use these new features
- save the document
- build it to HTML

---

]

---

## What do we want?

- Something that... lets you write text in **markdown**
- Something that... lets you include **R code** (e.g. for data vis)
- Something that... can **build** to HTML, PDF, Word, etc

---

---

## Let's dissect the document we just wrote!

---

## The part inside ` --- ` is the "YAML header"

---

<h2>The part inside <code>&#96;&#96;&#96;{r}</code> is R code</h2>

---

## The rest is markdown

---

.pull-left-narrow[
 .huge-bisque-number[7]
]
.pull-right-wide[
 
.larger[.embolden[Custom documents]]

]

---

## The YAML header is used for customisation

---

## Wait... what's the YAML acronym?

- Originally: "Yet Another Markup Language"
- Later: "YAML Ain't Markup Language"
- ... it really doesn't matter 🙄

---

## Output HTML only
```
---
title: "My First R Markdown Document"
author: "Danielle J. Navarro"
date: "10/02/2021"
output: html_document
---
```

---

## Output HTML and PDF

```
---
title: "My First R Markdown Document"
author: "Danielle J. Navarro"
date: "10/02/2021"
output:
  pdf_document: default
  html_document: default
---
```

- Notice the indentation
- YAML is *very* picky about this

---

---

## Themes for HTML documents

```
---
output: 
  html_document:
    theme: readable
---
```

**Possible themes**: default, cerulean, journal, flatly, darkly, readable, spacelab, united, cosmo, lumen, paper, sandstone, simplex, yeti

---

---

## Table of contents

```
output:
  html_document:
    toc: true
    toc_float: true
```

---

---

- practice editing the YAML header
- try creating different outputs and themes
- try creating a floating table of contents
- try to get it to not float!

---

.pull-left-narrow[
 .huge-bisque-number[8]
]
.pull-right-wide[
 
.larger[.embolden[Inserting equations]]

]

---

## An overview

- Anything inside dollar signs `$` is treated as "inline" maths
- Anything inside two dollar `$$` is a standalone equation
- Whitespace matters: `$x$` is an equation, `$x $` is not
- Equations follow "LaTeX" rules

---

## Equations are special

This equation is standalone
$$
a^2 + b^2 = c^2
$$
```
]
--
.pull-right[
This `$x^2$` is inline

This equation is standalone
$$
a^2 + b^2 = c^2
$$
]

---

## Literal $ signs are "easy"

$10 is text

$10 and $20 are text

$10 $ and $20 $ are text

$10$ uses math mode
```
]
--
.pull-right[
$ is text

$10 is text

$10 and $20 are text

$10 $ and $20 $ are text

`$10$` uses math mode
]

---

## Rescorla-Wagner model

.pull-left-wide[
```
The formula for the associative strength $V$ 
at time $t+1$ is given by 
$$
V^{t+1} = V^{t} + \Delta V
$$

where $\Delta V$ is given by

$$
\Delta V = \alpha \beta (\lambda - V_{tot})
$$
```
]

---

## Rescorla-Wagner model

.pull-left-wide[
The formula for the associative strength `$V$` 
at time `$t+1$` is given by 
$$
V^{t+1} = V^{t} + \Delta V
$$

where `$\Delta V$` is given by

$$
\Delta V = \alpha \beta (\lambda - V_{tot})
$$
]

---

---

.pull-left-narrow[
 .huge-bisque-number[9]
]
.pull-right-wide[
 
.larger[.embolden[Publishing documents]]

]

---

- upload the .Rmd and .html files: e.g., dropbox, github, osf
- one-click publishing with RStudio through RPubs

---