Literate programming

Overview

Teaching: 30 min
Exercises: 10 min
Questions
  • What tools are available to easily disseminate our work?

  • How can we make our work more reproducible?

Objectives
  • Learn the basics of RMarkdown and knitr

  • Learn to integrate R code with text and images.

2. Literate programming

  • Organize your work
  • make work more pleasant for yourself? (less tedium, less manual, less …)
  • reduce friction for collaboration?
  • reduce friction for communication?
  • make your work navigable, interpretable, and repeatable by others?

Process, packaging, and presentation are often the weak links in the chain.

Markdown

What is Markdown?

Adapted from Carson Sievert’s markdown slides

Markdown enables fast publication to the web

Markdown versus HTML code

This is a Markdown document.

## Medium header 

It's easy to do *italics* or __make things bold__.

> All models are wrong, but some are useful. An approximate answer to the right problem is worth a good deal more than an exact answer to an approximate problem.

Code block below. Just affects formatting here.

```
x <- 3 * 4
```

I can haz equations. Inline equations, such as the average is computed as $\frac{1}{n} \sum_{i=1}^{n} x_{i}$. Or display equations like this:


$$
\begin{equation*}
|x|=
\begin{cases} x & \text{if $x\ge 0$,} \\\\
-x &\text{if $x\lt 0$.}
\end{cases}
\end{equation*}
$$

<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>Title</title>
<!-- MathJax scripts -->
<script type="text/javascript" src="..."></script>
<style type="text/css">
body {
   font-family: Helvetica, arial, sans-serif;
   font-size: 14px;
...
</style>
</head>
<body>
<p>This is a Markdown document.</p>

<h2>Medium header</h2>

<p>It's easy to do <em>italics</em> or <strong>make things bold</strong>.</p>

<blockquote><p>All models are wrong, but some are...</p></blockquote>

<p>Code block below. Just affects formatting here.</p>

<pre><code>x <- 3 * 4</code></pre>

Markdown versus rendered HTML


This is a Markdown document.

## Medium header 

It's easy to do *italics* or __make things bold__.

> All models are wrong, but some are useful. An approximate answer to the right problem is worth a good deal more than an exact answer to an approximate problem.

Code block below. Just affects formatting here.


```r
x <- 3 * 4
```

I can haz equations. Inline equations, such as the average is computed as $\frac{1}{n} \sum_{i=1}^{n} x_{i}$. Or display equations like this:

$$
\begin{equation*}
|x|=
\begin{cases} x & \text{if $x\ge 0$,} \\
-x &\text{if $x\lt 0$.}
\end{cases}
\end{equation*}
$$

This is a Markdown document.

Medium header

It's easy to do italics or make things bold.

All models are wrong, but some are useful. An approximate answer to the right problem is worth a good deal more than an exact answer to an approximate problem.

Code block below. Just affects formatting here.

x <- 3 * 4

I can haz equations. Inline equations, such as the average is computed as \(\frac{1}{n} \sum_{i=1}^{n} x_{i}\).

Or display equations like this:

\[ \begin{equation*} |x|= \begin{cases} x & \text{if $x\ge 0$,} \ -x & \text{if $x\lt 0$.} \end{cases} \end{equation*} \]

Markdown can be rendered to multiple formats

RMarkdown

RMarkdown is rendered to Markdown. The strength of RMarkdown, is that with an easy syntax, it is possible to mix ideas, code, and generated results seamlessly.

Input

This is an R Markdown document.

```{r sec_3}
x <- rnorm(1000)
head(x)
```

`knitr` offers a lot of control over representing different
types of output. We can also have inline `R` expressions
computed on the fly.

The mean $\bar{x} = \frac{1}{n} \sum_{i=1}^{n} x_{i}$ of the
`r length(x)` random variates we generated is
`r round(mean(x), 3)`.

This figure is computed on-the-fly as well. No more
copy-paste, including for figures:

```{r sec_4}
plot(density(x))
```

Output

This is an R Markdown document.

x <- rnorm(1000)
head(x)
## [1] -3.2538882  0.6478847 -2.3089858 -1.8085141  0.5498946  1.4029523

knitr offers a lot of control over representing different types of output. We can also have inline R expressions computed on the fly.

The mean \(\bar{x} = \frac{1}{n} \sum_{i=1}^{n} x_{i}\) of the 1000 random variates we generated is 0.036.

This figure is computed on-the-fly as well. No more copy-paste, including for figures:

plot(density(x))

plot of chunk sec_4

Rendering can be automated is thus repeatable

From within R:

rmarkdown::render("filename.Rmd")

From the command line:

$ Rscript -e "rmarkdown::render('filename.Rmd')"

Summary

Key Points

  • RMarkdown and knitr are powerful tools.

  • Output can be rendered in many formats.

  • You don’t need to know HTML!