Dynamic documents?

What?

• Combines report writing/slides/etc and code and data source in one file.
• Change input data and the document will dynamically update.
• Single source for multiple output formats (HTML, PDF, Word)
• Single language for multiple output types (presentations, reports, books, papers, ...)

Why?

A major challenge for using data in industry, commercial and research settings is that reporting can become separated from the data itself, leading to problems in tracing how a particular graphic, statistic, etc was produced.

• Harms reproducibility
• Slows down making changes to graphics/analysis
• Updating with new data slow
• Error prone if process by which document generated is obfuscated

RMarkdown allows us to mix content and code in a plain text format (no WYSIWYG).

RMarkdown

• Simple plain text format

• Separate presentational style from content

• Simplified formatting commands

• Embedded code

• Include LaTeX for mathematical content

Document preamble

Section enclosed between two lines of --- at the top is the "document preamble".

Specifies various options for the document, including:

• title: the document title
• author: (optional) author's name
• date: (optional) date for the document
• output: a tree like structure for setting options of different output formats (HTML/PDF/Word)

Simple formatting

Styles:

• *italic text*
  • italic text
• **bold text**
  • bold text
• ~~strikeout text~~
  • strikeout text

Sections:

• # Section heading
  • 1. Section heading
• ## Sub-section heading
  • 1.1 Sub-section heading
• ### Sub-sub-section heading
  • 1.1.1 Sub-sub-section heading

Misc:

• [Dr Aslett's homepage](https://www.louisaslett.com/)
  • Dr Aslett's homepage

Lists

- First item
- Second item
    - First sub-item
    - Second sub-item
- Third item

1. First item
1. Second item
    i. First sub-item
    i. Second sub-item
1. Third item

Note: 4 spaces needed to create the indent

Note: Don't need to increment the numbering manually

Including R code and output (inline)

R can be included inline in text very easily. eg:

`r 1+1`

will substitute the value 2 in that place.

To show the code in a code font, but not execute, don't include the "r". eg:

`1+1`

will make the text look like this 1+1.

Including R code and output (chunks) I

Use the triple-backtick fence, specifying the language to be R.

```{r}
x <- rnorm(10, 3)
mean(x)
```

Prints both the code (nicely formatted) and the result of executing that code:

x <- rnorm(10, 3)
mean(x)

[1] 3.317083

Including R code and output (chunks) II

Various options change the behaviour, including:

• echo=FALSE to suppress printing the code (just show the output)
• eval=FALSE to show the code, but not run it

Obviously using both together is ... largely pointless!

Plots can be included by simply calling the plotting command.

• fig.width and fig.height take numeric options to specify size
• out.width and out.height allow character options (eg "25%") to proportionately scale.

```{r,echo=FALSE}
hist(x, main="Histogram of 100 Normal(mean=3, sd=1)")
```

Tables

| Col1 | Col2 | Col3 | Col4 | Col5 |
|------|------|-----:|------|:----:|
| a    | 1    | x    | `a`  | x    |
| b    | 2    | y    | `b`  | y    |

See also the great package gt https://gt.rstudio.com

Maths

You can write LaTeX inside a pair of dollar symbols, eg:

$\alpha+\beta$ renders $\alpha+\beta$

You can use the display style with double dollar signs:

$$\bar{X}=\frac{1}{n}\sum_{i=1}^nX_i$$

$$\bar{X}=\frac{1}{n}\sum_{i=1}^nX_i$$

\begin{align*}
asd &= asd \\
&= asd
\end{align*}

$$\begin{align*} e^{i \pi} &= \cos \pi + i \sin \pi \\ &= -1 \end{align*}$$

Presentations

Exactly the same source can support generating presentations rather than documents!

Main difference: ## triggers a new slide.

Resources

See also:

• R Markdown cheat sheet

  • https://github.com/rstudio/cheatsheets/raw/main/rmarkdown.pdf

• R Markdown website has good gallery of examples:

  • https://rmarkdown.rstudio.com

• R Markdown books:

  • The Definitive Guide https://bookdown.org/yihui/rmarkdown/
  • Cookbook https://bookdown.org/yihui/rmarkdown-cookbook/