R Markdown

R Markdown provides a framework for combining code, results, and commentary.

You can use R Markdown

• to generate reports, articles, books ...
• as an environment in which to do data science, as a lab notebook where you can capture not only what you did, but also what you were thinking.

Some interesting links:

• R Markdown: The Definitive Guide
• Introduction to R Markdown
• Cheatsheet

Example:

• Introduction to Econometrics with R

What’s possible with R Markdown?

Basic example

---
title: "Diamond sizes"
date: 2016-08-25
output: html_document
---
```{r, include=FALSE}
library(tidyverse)
data("diamonds")
smaller <- diamonds %>%
            filter(carat < 2.5)
```
We have data about `r nrow(diamonds)` diamonds. Only 
`r nrow(diamonds) - nrow(smaller)` are **larger** than
2.5 *carats*. The distribution of the remainder is shown
below:
```{r, echo = FALSE}
smaller %>% 
  ggplot(aes(carat)) + 
  geom_freqpoly(binwidth = 0.01)
```
If $\frac{\alpha}{\beta} = \gamma$ then $\alpha = \gamma\beta$.

How it works

An R Markdown document is a basic text file, with the (conventional) extension .Rmd.

The example already contains the most important components:

• An (optional) YAML header surrounded by ---
• Chunks of R code surrounded by ```{r, ...} and ```
• Inline R code surrounded by `r and `
• Text mixed with simple text formatting like bold and italics
• Mathematical expressions

How it works

When we click knit in RStudio then

1. the knitr package executes the code chunks and creates a markdown document (.md) which contains the text we have written and optionally the code and its output
2. the .md file gets processed by pandoc which creates the final file in the desired output format (e.g. html, pdf, word, ...)

The YAML header

The YAML header contains settings passed to pandoc and the rendering functions. Here you can:

• specify the output format with optional output specific options
• provide information for the title page such as title, name, and date
• include external files (e.g. .css) or additional packages for $LATEX$
• define parameters.

---
title: Habits
author: John Doe
date: March 22, 2005
output: html_document
---

The YAML header

---
title: Habits
author: John Doe
date: March 22, 2005
output:
  html_document:
    toc: true
    toc_float:
      collapsed: false
      smooth_scroll: false
    css: my_style.css
params: 
  pi: 3.141593
---

Output Formats

• html_notebook - Interactive R Notebooks
• html_document - HTML document
• pdf_document   - PDF document
• word_document - Microsoft Word document

Learn more about further output formats at https://rmarkdown.rstudio.com.

Text Formatting

• R Markdown is built on Pandoc Markdown, which in turn is a flavour of the markup language Markdown.
• The advantage of Markdown compared to other markup languages such as HTML and $LATEX$ is its simplicity.

Text Formatting

     #   Header 1     
     ##  Header 2   
     ### Header 3

     *italics* 
     **bold**
     This ~~is deleted text.~~
     Some code: `lm(y ~ x)`.

italics
bold
This is deleted text.
Some code: lm(y ~ x). 

Text Formatting

  * Item
    - Item belonging to item
    - Another item belonging to item
  * Item
  * Item

  1. First item
    - First subitem
    - Second subitem 
  2. Second item
  3. Third item

Note: Markdown does not support nested ordered lists with numbering 1.1, 1.2.1 and so on. For this, you would have to fall back to HTML or $LATEX$.

Text Formatting

First line  
Second line

  First paragraph
  Second paragraph

Math Expressions

When rendering to a pdf $LATEX$ can be used throughout the document.
Through MathJax the $LATEX$ math mode can also be used for HTML output as follows:

• Inline $LATEX$ equations can be written within dollar signs.

This is an inline equation $f(x)=\frac{1}{\sqrt{2\pi}}\exp{\left(-\frac{1}{2}x^2\right)}$.

This is an inline equation $f\left(x\right)=\frac{1}{\sqrt{2\pi }}\exp (-\frac{1}{2}{x}^2)$.

• Display style $LATEX$ equations can be written within double dollar signs.

This is display style $$f(x)=\frac{1}{\sqrt{2\pi}}\exp{\left(-\frac{1}{2}x^2\right)}$$.

This is display style $$f\left(x\right)=\frac{1}{\sqrt{2\pi }}\exp (-\frac{1}{2}{x}^2)$$

Math Expressions

• Even more complex math environments such as align can be used

\begin{align}
(a+b)^{3} &=(a+b)(a+b)^{2} \\
          &=(a+b)\left(a^{2}+2 a b+b^{2}\right) \\
          &=a^{3}+3 a^{2} b+3 a b^{2}+b^{3} 
\end{align}

$$\begin{array}{}(a+b{)}^3& =(a+b)(a+b{)}^2& & =(a+b)(a^2+2ab+b^2)& & =a^3+3a^{2}b+3a{b}^2+b^3& \text{(1)}& \text{(2)}& \text{(3)}\end{array}$$

Code Chunks

Code Chunks

```{r lin_reg, echo=TRUE, cache = TRUE}
x <- runif(100)
y <- 0.4 * x + rnorm(100)
lm(y ~ x)
```

If you mainly use chunk options which are not the default, then it saves time to change the default for the document with knitr::opts_chunk$set().

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo=FALSE, warning=FALSE, message=FALSE)
```

Inline R Code

You can also use R in your running text. When something changes (e.g. the input data) the numbers in the text adjust accordingly as well.

```{r, echo=FALSE}
x <- 4
y <- 38
answer <- x + y
```
The answer is `r answer`

The answer is 42.

Tables

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |   12 |   12    |   12   | 
|  123  |  123 |  123    |  123   | 
|    1  |    1 |    1    |    1   |

In general, however, tables should be produced by your code. The following slides show some examples.

kable

• knitr::kable() is probably the easiest way to transform a matrix or a data frame into a table.

```{r}
result        <- data.frame(rbind(rep(12,4), rep(123, 4), rep(1,4)))
names(result) <- c("Right", "Left", "Default", "Center")
knitr::kable(result, align = c("r", "l", "l", "c"), format = "html")
```

kableExtra

• The appearance of a table (not only produced by knitr::kable()) depends on the underlying css (in case of an HTML document) or the generated $LATEX$ code.
• The package kableExtra allows to format your knitr::kable() table without the use of css or $LATEX$

```{r}
library(magrittr)
library(kableExtra)
knitr::kable(result, 
             align = c("r", "l", "l", "c"), 
             format = "html") %>%  
  kableExtra::kable_styling(bootstrap_options = "bordered")
```

• Have a look at the kableExtra vignette for examples.

xtable

```{r, echo=FALSE, results='asis'}
library(xtable)
my_xtable <- xtable(result, align = c("r", "r", "l", "l", "c"))
print.xtable(my_xtable, type  = "html", include.rownames = FALSE)
```

stargazer

• stargazer takes model objects as input and automatically creates an output table

```{r, results='asis', echo=TRUE}
linear_model <- lm(mpg ~ cyl + wt, 
      data = mtcars)
stargazer::stargazer(linear_model, 
      type = "html", 
      out.header = TRUE, 
      omit.table.layout = "sn")
```

Plots

```{r, fig.height = 5}
hist(rnorm(1000))
```

Links and External Graphics

• Links can be created as follows:

[This is a link to the R Markdown book](https://bookdown.org/yihui/rmarkdown/)

• To include figures saved on your computer use

![Figure Description](path/to/figure.png)

• If you need more control over the appearence of the figure you can use

```{r, out.width = "500px", fig.align='center'}
knitr::include_graphics("path/to/figure.png")
```

Using HTML and $LATEX$

• If only R Markdown is used the document can be compiled without problems to all supported output formats.

• Sometimes R Markdown is too limited and one would like to use the more powerful tools provided by HTML or $LATEX$.

• If the output format is HTML, you can also use HTML instead of R Markdown or mix both.

• If the output format is PDF, the same can be said about $LATEX$

Interactive documents

• If the output is HTML, interactive elements (usually some JavaScript) can be included.
• There are R packages producing interactive output e.g. plotly for interactive plots or leaflet for interactive maps.

```{r}
library(plotly)
mtcars$am[which(mtcars$am == 0)] <- 'Automatic'
mtcars$am[which(mtcars$am == 1)] <- 'Manual'
mtcars$am <- as.factor(mtcars$am)
plot_ly(mtcars, x = ~wt, y = ~hp, z = ~qsec, color = ~am, colors = c('#BF382A', '#0C4B8E')) %>%
  add_markers() %>%
  layout(scene = list(xaxis = list(title = 'Weight'),
                     yaxis = list(title = 'Gross horsepower'),
                     zaxis = list(title = '1/4 mile time')))
```

Interactive documents

• For more examples see plot.ly.

Interactive documents

```{r, out.width='100%'}
library(leaflet)
leaflet() %>% addTiles() %>%
  setView(7.005070, 51.463675,zoom = 17) %>%
  addMarkers(
    7.005070, 51.463675
  )
```

+−

Leaflet | © OpenStreetMap contributors, CC-BY-SA

• Learn more at Leaflet for R.

Interactive documents

```{r}
DT::datatable( head(iris, 10),
  fillContainer = TRUE,  options = list(pageLength = 5))
```

Advanced Topics: Hooks

Chunk Hooks

# Template for a chunk hook
knitr::knit_hooks$set(
foo_hook = function(before, options, envir) {
    if (before) {
        ## code to be run before a chunk
    } else {
        ## code to be run after a chunk
    }
  })

Chunk Hooks: Example

```{r, eval = FALSE, echo=TRUE}
knitr::knit_hooks$set(small.mar = function(before) {
    if (before) par(mar = c(1, 1, 1, 1))  
})
```

```{r, small.mar = TRUE}
hist(rnorm)
```

Output Hooks

knitr::knit_hooks$set(small.mar = function(before) {
    if (before) par(mar = c(1, 1, 1, 1))  
})

Output Hooks: Example

• You can e.g. use a hook to consistently style all your tables using kableExtra.

default_source_hook <- knit_hooks$get("source")
knit_hooks$set(
  source = function(x, options) {
    if(is.null(options$table))
      default_source_hook(x, options)
    else {
      eval(parse(text = x)) %>%
        kable("html") %>%
        kable_styling("hover", full_width = F)
    }
  }
)

The here package

load(here::here("Data", "my_dataset.rda"))