18 November, 2019

Overview

  • What is RMarkdown?
  • A quick intro to RMarkdown syntax
  • Using RMarkdown for reproducible research
  • How I made this presentation
  • Using Markdown and RMarkdown to publish to the web

What is RMarkdown?

What is Markdown?

The wikipedia article on Markdown describes it as;

A lightweight markup language with plain text formatting syntax.

Its principle author, John Gruber created it for writing articles on his website, Daring Fireball in 2004

For example

The Markdown code for the previous slide looks like this

# What is Markdown?

The wikipedia article on Markdown describes it as;

> A lightweight markup language with plain text formatting syntax.

Its principle author, John Gruber created it for 
writing articles on his website, Daring Fireball in 2004

Translated to html it looks like this

<h2>What is RMarkdown?</h2>
<div class="slideContent" >

<p>The wikipedia article on Markdown describes it as;</p>

<blockquote>
<p>A lightweight markup language with plain text formatting 
syntax.</p>
</blockquote>

<p>Its principle author, John Gruber created it for writing 
articles on his website, Daring Fireball in 2004</p>

Components

Markdown documents are often converted to something else. Usually html. This means there are two components to Markdown

  1. The lightweight text syntax

  2. A program that converts Markdown documents into html (or other formats as we will see later)

Design and Syntax

Markdown was designed to be easy to read as-is

Since it was originally written as a text-to-html it’s syntax reflects the basic html tags

For example;

# Heading
## Subheading
### Smaller Subheading
<h1>Heading</h1>
<h2>Subheading</h2>
<h3>Smaller Subheading</h3>

More Syntax: Lists

You can make lists in Markdown like this

- Item 1
- Item 2
  • Item 1
  • Item 2

Or this

1. Item 1
2. Item 2
  1. Item 1
  2. Item 2

More Syntax: Emphasis

Emphasise text with **bold** or _italics_

Emphasise text with bold or italics

> Or you can put some text in a blockquote

Or you can put some text in a blockquote

Github flavoured Markdown

Github uses a variant of Markdown that has become very popular among programmers.

Perhaps the most important new feature is the “fenced code block”.

This is a fenced code block with a piece of R code

```r
rhello <- function(){ print("Hello") }
rhello()
```

Which gets converted to html with syntax highlighting like this

rhello <- function(){ print("Hello") }
rhello()

RMarkdown

RMarkdown is an extension to Markdown that is designed to enable reproducible research.

RMarkdown takes the idea of fenced code blocks and makes them into runnable code blocks.

```{r}
rhello <- function(){ print("Hello") }
rhello()
```
rhello <- function(){ print("Hello") }
rhello()
## [1] "Hello"

Plots with RMarkdown

This code chunk will produce a plot

```{r}
library(ggplot2)
ggplot(cars) + geom_smooth(aes(x=speed,y=dist))
```
library(ggplot2)
ggplot(cars) + geom_smooth(aes(x=speed,y=dist))
## `geom_smooth()` using method = 'loess' and formula 'y ~ x'

Chunk options

The way chunks are evaluated and displayed can be changed with various options

```{r , message=FALSE, echo=FALSE, fig.height=3}
library(ggplot2)
ggplot(cars) + geom_smooth(aes(x=speed,y=dist))
```

The RMarkdown engine

The engine behind RMarkdown is an R package called knitr and a command line program called pandoc

  • knitr does the job of running code in chunks and generating an intermediate Markdown file
  • pandoc converts the Markdown file into other formats such as html or pdf.
  • RStudio automates this process

Supported Languages

RMarkdown is not just for R.

names(knitr::knit_engines$get())
##  [1] "awk"       "bash"      "coffee"    "gawk"      "groovy"   
##  [6] "haskell"   "lein"      "mysql"     "node"      "octave"   
## [11] "perl"      "psql"      "Rscript"   "ruby"      "sas"      
## [16] "scala"     "sed"       "sh"        "stata"     "zsh"      
## [21] "highlight" "Rcpp"      "tikz"      "dot"       "c"        
## [26] "fortran"   "fortran95" "asy"       "cat"       "asis"     
## [31] "stan"      "block"     "block2"    "js"        "css"      
## [36] "sql"       "go"        "python"    "julia"     "sass"     
## [41] "scss"

—

For example here is a code block that runs bash

echo "Hello from bash" | cowsay
##  _________________ 
## < Hello from bash >
##  ----------------- 
##         \   ^__^
##          \  (oo)\_______
##             (__)\       )\/\
##                 ||----w |
##                 ||     ||

—

If you want to use python just install the reticulate package

print("Tabs or spaces I don't care, just don't mix them anywhere")
## Tabs or spaces I don't care, just don't mix them anywhere

RStudio even works nicely with python graphics engines like matplotlib if you’re into that sort of thing.

RMarkdown for reproducible research

My workflow

My research tasks are divided evenly between running command-line tools on the HPC and analyzing outputs from those tools with R.

I document my command-line workflows with plain Markdown and bash scripts I do all my R work with RMarkdown so it is easily converted into documentation

An Example

Github Output

I often use the output format github_document. This works very well for publication because the rendered markdown files will be turned into nice web pages by Github.

---
title: "Population Structure"
author: "Ira Cooke"
output: github_document
---

Other types of output

At the top of every RMarkdown document is a short bit of yaml. Here you can change the output type.

RMarkdown can be rendered into many different output types including

  • Presentations (ioslides_presentation, beamer_presentation)
  • Document formats (pdf_document, word_document, latex_document)
  • Markdown derivatives (github_document, md_document)
  • html (html_document)

In principle it is easy to switch output types but you will often need to customize to get things looking good in different formats.

Learning Resources