Literate Programming in R Markdown

R Markdown is a tool for generating richly documented, reproducible analyses. This worksheet introduces the basic steps in creating an R Markdown document.

This worksheet is to test your understanding of the talk Literate Programming in R Markdown, presented at the R-thritis Group on Friday 15^th January 2021.

Resources

• Talk slides
• Example Markdown file
• Example R Markdown file

Writing a Markdown document

Basic syntax

Create a new file with the .md file extension, e.g. hello.md. Open this file in RStudio or your favourite plain-text editor, such as Notepad. See if you can recreate the following passage in Markdown syntax.

I am writing in Markdown. It is intended to be

1. easy to read and
2. easy to write.

Literate programming emphasises the idea that source code should be human-readable and computer-executable.

Like \(\LaTeX\), Markdown can support mathematical expressions, such as \(E = mc^2\).

Tip: To remind yourself of Markdown syntax, see Help > Markdown Quick Reference in RStudio—or refer to the talk slides.

Metadata

Add a YAML header to the top of your file including a title, author and today’s date.

Convert your Markdown document into an HTML document and view it.

Tip: There are several ways to convert a Markdown document:

1. using RStudio’s Knit button,
2. using rmarkdown::render or knitr::knit in the R console,
3. using a hotkey in RStudio (see Help > Keyboard Shortcuts Help).

Images

Let’s liven up the document a bit. Find a fun picture online and add it to your report. I quite like this one:

Figure 1: Picture of a chick, by Toni Cuenca

R Markdown documents

Now that we know how to write and compile static documents, let’s start adding R code.

Rename or copy your file so it has the extension .Rmd, e.g. hello.Rmd. (Or, in RStudio, use File > New File > R Markdown…)

R code chunks

The chickwts dataset, included with R, describes an experiment on the effect of different diets on the early growth of chickens. It includes two columns: the weight in grams of the chicks after six weeks, and the feed type that was given to them.

Add an R chunk that evaluates the following code.

plot(chickwts$weight ~ chickwts$feed, xlab = 'Feed type')

It should initially look something like this.

Modify the code to add a nicer y-axis label (ylab) and some colours (col) to the plot.

Tweak the chunk options so that the R code is hidden in your final document but the bar plot remains visible.

Tip: remember, R code chunks take the form:

```{r} 
# Your R code here
```

Inline R code

Write a short paragraph giving some summary statistics of your dataset, calculated in-line. For example, you might want to describe the number of rows (nrow), mean (mean), minimum (min), maximum (max) and standard deviation (sd) for the chickwts dataset.

Tip: evaluate R code inline using the syntax `r R_code_here`; for example: “A chair has `r 2+2` legs”.

Dynamic numbers

Modify your date field in the YAML header so that it automatically includes the time/date that your document was last compiled.

Tip: For the current time, try Sys.time() or Sys.Date(). If you aren’t happy with the format in which the date/time is displayed, refer to ?format.POSIXct.

Tables

Include some/all of the chickwts dataset as a nice-looking table in your report.

Tip: use the command knitr::kable(), in combination with results = 'asis' in your chunk options. Or, add df_print: kable to your document header. You can also try the xtable package, if you have it installed.

Chunks in chunks

Remember your barplot from earlier? Reproduce that chunk’s code (but not the plot again), without copying and pasting it, in an “Appendix” section at the end of your report.

Tip: check the talk slides.

Output formats

Regenerate your entire report as a Word document. Then (only if you have \(\LaTeX\) installed), generate it as a PDF as well.