2 May 2017

Learning objectives

You will learn to:

  • use the markdown syntax
  • create Rmarkdown documents
  • define the output format you expect to render
  • use the interactive RStudio interface to
    • create your documents
    • insert R code
    • build your final document
  • use some nice rmarkdown features like
    • inserting bibliography
    • creating parameterised reports

RMarkdown

Why using rmarkdown?

  • write detailed reports
  • ensure reproducibility
  • keep track of your analyses
  • comment/describe each step of your analysis
  • export a single (Rmd) document to various formats (Pdf, Html…)
  • text file that can be managed by a version control system (like git)

Rmarkdown

+ +

Markdown

Markdown is used to format the text

Markup language

  • Such as Xml, HTML
  • A coding system used to structure text
  • Uses markup tags (e.g. <h1></h1> in HTML)

HTML

<!DOCTYPE html>
<html>
<body>

<h1>This is a heading</h1>

<p>This is some text in a paragraph.</p>

</body>
</html>

Lightweight markup language

  • Easy to read and write as it uses simple tags (e.g. #)

MD

# This is a heading

This is some text in a paragraph

Markdown

common text formatting tags

Headers

  • Levels are defined using #, ##, ###

Text style

  • bold (**This will be bold**)
  • italic (*This will be italic*)

Links and images

  • [description](http://example.com)
  • ![](path/to/image.jpg)

Verbatim code

  • code (`This will be some inline coding stuff`)
  • triple backticks are delimiting code blocks
```
This is *verbatim* code
# Even headers are not interpreted
```

Rmarkdown cheatsheet

Exercise

Markdown

Learn to use the markdown syntax

Before writing your own Rmarkdown document, use the excellent ressource on commonmark.org to learn the basics of markdown formatting.

An alternative online ressource can be found on www.markdowntutorial.com

Including R code

Rmarkdown

  • extends markdown
  • allows to integrate code chunks that will be interpreted
    • R code
    • bash
    • python
    • css

Knitr

  • R chunks are extracted, interpreted separately
  • The result is formatted (with or without the source code) and integrated into the markdown document
  • The markdown document is converted to the desired document format (Pdf, Html…)
  • Relies on the powerful pandoc converter
  • Fully integrated in Rstudio (Knit button)

Rmarkdown document

Create, step 1

Rmarkdown document

Create, step 2

Rmarkdown document

Structure

A Rmarkdown document document contains 3 elements:

  • A YAML header to define document wide options
  • Text which is formatted using the markdown" syntax
  • chunks containing the code to be interpreted by R

Rmarkdown document

Navigation

Rmarkdown document

Insert a chunk

Inserting a code chunk

R code chunks

  • chunks are defined between two lines starting with a 3 backticks tag (```)
  • curly brackets define how to interprete the content (R code but other languages such as Python are also supported)
  • ```{r} is the minimum to define a starting R chunk
  • can contain more options (name of chunk, whether to show it or not, evaluate it or not)

Inline code

To integrate small pieces of R codes

  • Use backticks (`) combined to the keyword r (`r <your R code>`)
  • Example: type in 1 + 1 = `r 1+1` to render 1 + 1 = 2.

Rmarkdown document

generate

Creating the output document

  • use the integrated Knit button.
  • call rmarkdown::render()

Popular output formats

Bibliographies

Supported bibliography formats

Format File extension
MODS .mods
BibLaTeX .bib
BibTeX .bibtex
RIS .ris
EndNote .enl
EndNote XML .xml
ISI .wos
MEDLINE .medline
Copac .copac
JSON citeproc .json

Defined in the yaml header

---
title: "Sample Document"
output: html_document
bibliography: bibliography.bib
csl: nature.csl
---

Insert your reference [@my-reference] like I did.

Parameterised reports

Parameterised reports

  • use a single Rmarkdown file and adjust R variables
    • data filepath
    • boolean (yes/no)
    • numbers

Define your parameters

  • Place them in the YAML header
---
title: "My Document"
output: html_document
params:
  lines: 10
  show_table: no
  data: 
    label: "Input dataset:"
    value: mtcars.csv
    input: file
---

Parameterised reports

Growing variety of output formats

Output documents

  • Look on the rmarkdown website
  • Documents (HTML, PDF, MS Word…)
  • interactive documents (shiny package)
  • websites (like the sites of this workshop or rmarkdown)

Books

  • Bookdown package. Go on the website to learn more about it.
  • Generate books as PDF, EPUB or MOBI files.
  • Have a look at the R for Data Science website. It is also freely available in the bookdown format (but you might prefer the paid version to support the authors!)

Slideshow presentations

  • ioslides_presentation (HTML)
  • slidy_presentation (HTML)
  • beamer_presentation (pdf, \(\LaTeX\))

Slideshow presentations

IOSlides Plus (iosp)

  • extends ioslides_presentation
  • used for this presentation
  • customised css
  • shortcuts to create columns and/or boxes (### level 3 headers with attributes ({}))
  • have a look on github

Source

## Slide with columns and boxes

IOSlides Plus extends `ioslides_presentation` and allows to easily create boxes:

### Box 1{.box-4 .bg-red}

Test 1

### Box 2{.box-6 .bg-green}

- line 1
- line 2

### Box 3{.box-6 .bg-blue}

This box has again a width of 6 col: it will be rendered in a new row.

Slide with columns and boxes

IOSlides Plus extends ioslides_presentation and allows to easily create boxes:

Box 1

Test 1

Box 2

  • line 1
  • line 2

Box 3

This box has again a width of 6 col: it will be rendered in a new row.

Wrap up

You learned to:

  • create Rmarkdown documents
  • format your text using the markdown syntax
  • insert your R code in chunks
  • adapt some rendering options of R code chunks
  • define the output format you expect to render
  • use the interactive RStudio interface to
    • create your documents
    • insert R code
    • build your final document
  • insert bibliography
  • create parameterised reports