<style type="text/css">

body{ /* Normal  */
      font-size: 12px;
  }
td {  /* Table  */
  font-size: 12px;
}
h1.title {
  font-size: 20px;
  color: DarkBlue;
}
h1 { /* Header 1 */
  font-size: 18px;
}
h2 { /* Header 2 */
    font-size: 16px;
}
h3 { /* Header 3 */
  font-size: 14px;
}
code.r{ /* Code block */
    font-size: 12px;
}
pre { /* Code block - determines code spacing between lines */
    font-size: 12px;
}
</style>

---

Dear students, 

This week we will learn how to use `rmarkdown` to produce documents from within `RStudio`. This means that we have just a single file that generates, publishes and type-sets all our outcomes into a single target
document. 

I'll quickly walk you through the basics, but I strongly suggest that you follow 
[this elaborate quick course](http://rmarkdown.rstudio.com/lesson-2.html) afterwards. 

Let's start. 

Gerko

---

# About `rmarkdown`
[`rmarkdown`](http://rmarkdown.rstudio.com/index.html) is `RStudio's` document interface that, just like `markdown`, provides 
users with a lightweight markup language with plain text formatting syntax. This 
document, for example, is prepared using `rmarkdown`. Have a look at this 
(`Exercise 5.html`) and [`Exercise 5.Rmd`](Exercise 5.Rmd) files and you'll see that the body of the
document is just text (somewhat like with $\LaTeX$ - but simpler) and that figures, 
links, code, tables - and so on - are easily marked up by simple commands or 
straightforward use of text symbols. Let's have a look at some of these components. 

---

# The header
Every `rmarkdown` document starts with a header. In this header, the output format 
is specified, as well as information regarding the title and authorship of the 
document. Whenever a new `rmarkdown` document is opened in `RStudio`, the following
default header appears for a html document:

<pre><code>---
title: "Untitled"
author: "YOURNAME"
date: "TODAYSDATE"
output: html_document
---
</code></pre>

The header can be expanded to contain document-wide display and redering parameters.

---

# Code chunks
The beauty in `rmarkdown` is to weave text and code into a single document. There 
are many languages that plug into `rmarkdown`, but for now we focus on `R`. To run 
`R` code, a code chunk has to be formally declared:

<pre><code>```{r}
a <- 100
```</code></pre>

The above code renders a code chunk, which will be printed by default. There are 
many options that can be explored with respect to code chunks, such as caching, 
evaluation and printing, For example, the following code renders a chunk that is 
evaluated and cached, but not printed (= echoed) to the final document:

<pre><code>```{r eval = TRUE, echo = FALSE, cache = TRUE}
a <- 100
```</code></pre>

```{r echo=FALSE}
a <- 100
```

---

# In-line code
We use 

```{r, results='asis', echo=FALSE}
cat("`` `this` ``")
```

to render in-line code as `this`. Consequently, 
we can use code executions to obtain in-line evaluations of previously rendered r-code via 

```{r, results='asis', echo=FALSE}
cat("`` `r a*3` ``")
```

to evaluate that $a \times 3$ equals `r a*3`.

---

# Emphasizing text
Use `*` to put emphasis on (parts) of text. For example 

- `*This text will be in italic*` renders *This text will be in italic*
- `**This text will be in bold face**` renders **This text will be in bold face**
- `***This text will be in both bold face and italic***` renders ***This text will be in both bold face and italic***

---

# LaTeX
Raw $\LaTeX$ can be used via `$X \sim \mathcal{N}(\mu,\,\sigma^{2})$` to render $X \sim \mathcal{N}(\mu,\,\sigma^{2})$ as in-line equation. However, the same can be obtained as displayed equation via `$$X \sim \mathcal{N}(\mu,\,\sigma^{2})$$` to render 

$$X \sim \mathcal{N}(\mu,\,\sigma^{2})$$

---

# Sections

Sections are created with symbol `#`, where 

- `# The First` conforms to `\section{The First}` in $\LaTeX$, 
- `## Deeper level` conforms to `\subsection{Deeper level}`, 
- `### Even deeper level` conforms to `\subsubsection{Even deeper level}`, 
- and so on. 

---

# Links
Urls are displayed via `[the text](the url)` such that `[Gerko Vink](https://www.gerkovink.com)` is rendered as [Gerko Vink](https://www.gerkovink.com).

---

# Figures
To post externally generated figures in `rmarkdown`, use `![](figure.jpg)`

to generate the following figure [(source)](https://www.ethos3.com/wp-content/uploads/2015/11/humor-public-speaking.jpg)

![](figure.jpg)

and use `![This is a caption](figure.jpg)` to generate the same figure with a caption. 

![This is a caption](figure.jpg)

For centering and resizing graphs, I find it most convenient to post the figure in a html container:

`<center> <img src="figure.jpg" width = 50%>  </center>`

<center>
<img src="figure.jpg" alt="HTML5 Icon" width = 50%>
</center>

Note that the above figure is now centered and spans `50%` of the width of the document. 


---

# Tables
Creating tables in `markdown` or `rmarkdown` is very straightforward. For example, 
the following code 

<pre><code>
First Header     | Second Header
---------------- | -------------
Content Cell 1,1 | Content Cell 1,2
Content Cell 2,1 | Content Cell 2,2
</code></pre>

generates the following table:

First Header      | Second Header
----------------- | -------------
Content Cell 1,1  | Content Cell 1,2
Content Cell 2,1  | Content Cell 2,2

---

# Exercise 

Design a study that:

  a. Does something that requires RNG
  b. Fixes the RNG seed
  c. Replicates the results
  d. Generates an reproducible archive/reprex/markdown
  e. Will run on my machine without trouble (package installs may be excused)
  f. Communicates the info of your session
  
When finished, push to your GitHub fork of [`markup2020`](https://github.com/gerkovink/markup2020) and create a `pull request`. 


