A quick introduction to R/markdown

These are notes and materials for a short (2-hour) course on using R/markdown to generate reports and dynamic documents.

Here's a link to the slides. Here is also a document with some gotchas that I've figured out my way around, and some technical notes on getting pandoc, R+markdown, and this presentation to work.

Outline

1. Markdown

   • philosophy: just write
   • structure: headers, breaks
   • formatting: bold, emphasis
   • links
   • math
   • code blocks
   • images
   • metadata
   • the wider world of markdown(s)

2. Rendering markdown with pandoc

   • bare-bones
   • adding style
   • metadata/YAML headers
   • self-contained documents (+local mathjax)
   • gotchas
   • the documentation and where to look for help

3. Adding R

   • what knitr does
   • code chunks
   • figures
   • tables
   • chunk options
   • inline R
   • rmarkdown and rstudio

4. One report, many documents: a working example

   • one subdirectory per dataset
   • json configuration + simulated data
   • external variables with knitr
   • using Rscript instead

Compiling the presentation yourself

The presentation uses reveal.js. You can get this repository along with reveal.js like so:

git clone https://github.com/petrelharp/r-markdown-tutorial.git
cd r-markdown-turoial
git submodule init && git submodule update

With an up-to-date version of pandoc, R, and knitr, you should be able to compile the presentation like so:

make using-rmarkdown.slides.html

Note: OSX, for some reason, passes strings through make differently, so you need to uncomment a line in the Makefile, so it looks like this:

# or, uncomment for OSX:
KNITR_PATTERNS = list( chunk.begin="^```+\\\\s*\\\\{[.]?(r[a-zA-Z]*.*)\\\\}\\\\s*$$", chunk.end="^```+\\\\s*$$", inline.code="`r +([^`]+)\\\\s*`")

(the only difference is an extra level of escaping the slashes).

Since I give presentations sometimes not on the internet, this by default relies on a local installation of MathJax, so unless you've installed this on Debian/Ubuntu (aptitude install libjs-mathjax), to view the maths properly you need to change the location in the Makefile.

The presentation will not render in Rstudio because: by default, knitr tries to process all code blocks; so to have example code in the document you have to munge your own code. To keep my document processable by just pandoc, and prettier (except the inline code) I am rendering the presentation after modifying the regular expression knitr uses to identify code chunks to require exactly three backticks, at the start of the line, and the identifier r (by default it is much more lax). See the Makefile for how this is done.