1 Introduction

Let’s look at a few examples on the Rstudio gallery

2 Markdown

• Markdown is a lightweight markup language with plain text formatting syntax (Easy-to-read, easy-to-write plain text format). It is designed so that it can be easily converted to HTML and many other formats (e.g. PDF, MS Word, .docx).

• Like other markup languages (e.g. HTML and Latex), it is completely independent from R.

• Typically, files have the extension .md .

• Look at this example. Examine the html render (GitHub automatically interprets .md files) and the raw file.
  

3 R Markdown

• An extension of the Markdown syntax that enables R code to be embedded and executed.

• Generate fully reproducible reports in different static and dynamic output formats.

• Most of these packages are maintained by the R studio team (https://rmarkdown.rstudio.com/, Yihui Xie)

• Plain text files that typically have the file extension .Rmd.

4 R Markdown basics

• Write text & code in R studio.

• Knit: The R package rmarkdown feeds the .Rmd file to the R package knitr.

• knitr executes code and creates a new `Markdown (.md) document which includes the code and output.

• Subsequently tranformed into .html/.tex/.docx by pandoc. (Note that .tex files need to be transformed by pdflatex into .pdf files. We’ll come back to that later.)

• Pandoc is an universal document converter, independent of R.

• By default, R studio comes with rmarkdown, knitr, and pandoc (but not pdflatex).

• When you click the Knit button (top left), a document will be generated that includes both content as well as the output of R code within the document. You can also use the render() function.

5 R Markdown syntax

Markdown provides an easy way to make standard types of formatted text, like:

• italics (*text*) or italics (_text_)

• bold (**bold**)

• backslash (\) to interpret a special characters as character

• “# and space” at the beginning of line for a header level (6 levels, # to ######)

• bold italic (_**bold italic**_)

• links ([links](https://www.rmarkdown.rstudio.com))

• <!–comments–>

• newline character: Two spaces and the end of line

• paragraph mark: Two cariage returns

• list (first level using: * or + and space)
  • item 1 (second level using: space, space, * or +, and space)
  • item 2
    • subitem 1a
      
    • subitem 1b
      • subsubitem 1b
  • item 3

• *** for an horizontal line

• quoted text (`quoted text`)

> Quoted text: 1st way
> more quoted text
> still more quoted text

Quoted text: 1st way
more quoted text
still more quoted text

`Quoted text: 2nd way`
`more quoted text`
`still more quoted text`

Quoted text: 2nd way
more quoted text
still more quoted text

```
text: 3rd way
quoted text
more quoted text
```

Quoted text: 3rd way    
more quoted text         
still more quoted text        

• Tables

Species | Counts
——— | —–
H. sapiens | 24
M. musculus | 442

• The cheatsheet is your friend.

6 Header

---  
title: "Rmarkdown"  
author: "Sebastien Renaut"  
date: '2018-03-12'  
output: html_document  
---  

• Header, metadata, YAML, YAML Ain’t Markup Language (https://en.wikipedia.org/wiki/YAML#History_and_name)

• Header specifies configurations (what kind of document will be created, and the options chosen).

• It is not required (defaults then apply).

• It uses Python-style indentation to specify some options.

• Many options possible depending what type of document you are generating. See below for some examples.

• Note that some options can be specified either for the whole document (in the header), the code chunks, or both (chunks options supersede header). More on code chunks later.

---  
title: "Rmarkdown"  
author: "Sebastien Renaut"  
date: "March 20, 2019"   
output: 
  html_document:  
    code_folding: hide
    highlight: tango  
    number_sections: T  
    theme: cerulean 
    toc: yes  
    toc_depth: 3  
---  

# Preface {-}

7 Code chunks

• The real power of R Markdown comes from mixing Markdown syntax with chunks of code.

• A code chunk is intepreted by knitr. It works essentially the same as the R syntax we are familiar with.

• A main code chunk may look like this:

```{r example, include = T, message = T, warning=T, echo = F, fig.cap="A figure of random points"}  
#Running some R code.
x = rexp(1000)  
min(x)  
max(x)  
hist(x)  
```    

## [1] 0.0008266717

## [1] 8.883759

A figure of random points

• On the 1st line, I specify that I will run the R programming language.

• Then, I give the chunk a UNIQUE name and specify options.

• There are a large number of chunk options in knitr documented here.

• Here are common options:

  • include = FALSE: Code and results will NOT appear in the finished file. Code is still interpreted, and the results can be used by other chunks.

  • echo = F prevents code, but not results from appearing in the finished file. This is a useful way to embed figures.

  • message = F prevents messages that are generated by code from appearing in the finished file.

  • warning = F prevents warnings that are generated by code from appearing in the finished file.

  • fig.cap = "..." adds a caption to graphical results.

  • fig.width=..., fig.height=... can also change figure width/heigth.

• By default R studio creates a Global Options code chunk. Let’s examine this chunk:

```{r setup, include=FALSE}  
knitr::opts_chunk$set(echo = TRUE)  
```  

• see cheat sheet for more info.

• Note that you can also run inline code. For example, ` r 10+5 ` would be processes as 15.

```{bash, echo = F}
ls -1 | head -3
```

## rmarkdown_main.Rmd
## rmarkdown_main.html
## rmarkdown_main.log

```{python, echo = F}
x = "hello python!"
print(x.split(' '))
```

## ['hello', 'python!']

```{perl, echo = F}
print "Hello perl!";
```

## Hello perl!

8 Math symbols

Mathematical material is set off by the use of single dollar-sign characters (similar as in the LaTeX typesetting language).

• So to write \(E = mc^{2}\), you’d write: $E = mc^{2}$

• \(\sum_{i=1}^n ASV\)

• \(F_{(1,69)}\) = 1.27, p-value=0.26

• \(A = \pi*r^{2}\)

• \(\sqrt{b^2 - 4ac}\)

• If you need to use an actual dollar sign, you need to preface it with a back-slash \(E = mc^{2}\) versus $E = mc^{2}$

• The use of double dollars quotations allows for displayed formulas (centered). \[\sqrt{b^2 - 4ac}\]

• See more example equations from this McGill math R Markdown tutorial.

9 Include pictures & figures

There are several ways to include figures.

knitr

Images can also be interpreted by knitr as below:

```{r graphic_example, out.width = "20%", fig.cap = "rosa_banksiae", echo = F,fig.align = "center"}  
knitr::include_graphics("../figures/rosa_banksiae.JPG")  
```

rosa_banksiae

```{r roses, out.width = "50%",echo = F,out.extra='style="float:right; padding:10px"'}
knitr::include_graphics("../figures/rosa_banksiae.JPG")  
```

```{r another example, echo = F, message = F}
library(ggplot2)
mtcars_ggplot = ggplot(mtcars, aes(x=wt, y=mpg)) + 
geom_point() + geom_smooth()
mtcars_ggplot
```

```{r out.width=c('50%', '50%'), fig.show='hold',echo=F,message = F}
mtcars_ggplot
plot(rnorm(10))
```

## `geom_smooth()` using method = 'loess' and formula 'y ~ x'

10 Including Tables

• By default, R Markdown displays data frames and matrices as they would be in the R terminal.

• You can use the knitr::kable function for additional formatting, as in the .Rmd file below.

#Default R printout (ugly)
print(head(mtcars))

##                    mpg cyl disp  hp drat    wt  qsec vs am gear carb
## Mazda RX4         21.0   6  160 110 3.90 2.620 16.46  0  1    4    4
## Mazda RX4 Wag     21.0   6  160 110 3.90 2.875 17.02  0  1    4    4
## Datsun 710        22.8   4  108  93 3.85 2.320 18.61  1  1    4    1
## Hornet 4 Drive    21.4   6  258 110 3.08 3.215 19.44  1  0    3    1
## Hornet Sportabout 18.7   8  360 175 3.15 3.440 17.02  0  0    3    2
## Valiant           18.1   6  225 105 2.76 3.460 20.22  1  0    3    1

#With kable function from knitr (better looking)
knitr::kable(head(mtcars),digits =1,caption = "A motorcars table")

11 References

csl: ../csl/peerj.csl  
bibliography: ../biblio/test_library.bib  

@article{altschul1997gapped,
  title={Gapped BLAST and PSI-BLAST: a new generation of protein database search programs},
  author={Altschul, Stephen F and Madden, Thomas L and Sch{\"a}ffer, Alejandro A and Zhang, Jinghui and Zhang, Zheng and Miller, Webb and Lipman, David J},
  journal={Nucleic acids research},
  volume={25},
  number={17},
  pages={3389--3402},
  year={1997},
  publisher={Oxford University Press}
}

12 Cheatsheets and help

• Lessons

• Book
  • This is a great reference. In addition, it is (of course) written in R Markdown and publicly available on GitHub. As such, if you see something you want to reproduce, go see how it was written in the .Rmd version!

• Cheatsheet (newer - longer)

• Pimp my Rmd

• Stack Overflow

13 References

(Note that references below are generated automatically, except for the footnote.)