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

Let’s start.

Gerko

1 About rmarkdown

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

2 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:

---
title: "Untitled"
author: "YOURNAME"
date: "TODAYSDATE"
output: html_document
---

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

3 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:

```{r}
a <- 100
```

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:

```{r eval = TRUE, echo = FALSE, cache = TRUE}
a <- 100
```

4 In-line code

We use

`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 a*3`

to evaluate that \(a \times 3\) equals 300.

5 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

6 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})\]

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

9 Figures

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

to generate the following figure (source)

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

This is a caption

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>

HTML5 Icon

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

10 Tables

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


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

generates the following table:

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

11 Exercise

Design a study that:

  1. Does something that requires RNG
  2. Fixes the RNG seed
  3. Replicates the results
  4. Generates an reproducible archive/reprex/markdown
  5. Will run on my machine without trouble (package installs may be excused)
  6. Communicates the info of your session

When finished, push to your GitHub fork of markup2020 and create a pull request.