A brief introduction to (R)Markdown

class: center, middle, inverse, title-slide

# A brief introduction to (<code>R</code>)Markdown
### Pedro Henrique P. Braga<bolder>, Ph.D. Candidate</bolder> 
### Community and Quantitative Ecology Laboratory (Dr. Pedro Peres-Neto) Concordia University
### 2020-06-08 Use arrow keys to navigate, press <code>H</code> for help

---

class: middle

### Step I: A brief background to `Markdown` (3-min)

### Step II: A brief background to `RMarkdown` (10-min)

### Step III: A few examples! (5-min)

### Step IV: Advanced stuff (2-min)

---
class: center, middle

### Wait! Why should I learn this?

---
class: inverse
#### RMarkdown has the potential to facilitate scientific workflow

**RMarkdown** documents allow you to combine your “data, code, and narrative” in a single file. Each of the components of your project can be tied together and easily re-run when data are updated or changes need to be made to other steps in the research workflow.

.pull-left[
##### Project conception

You can maintain a project notebook to track the development of your projets, which can be come very useful on to track history and progress of a project.

##### Reproducible and collaborative research

It facilitates reproducible research (irreproducibility costs money), and a collaborative workflow (e.g., by integrating it with GitHub).
]
.pull-right[
##### Publication

Most scientific journals accept `TeX` submissions, and `RMarkdown` has advanced article publication tools (such as `rticles` for manuscripts, and `bookdown` for books).

##### Blogs

Many blogging platforms support `markdown`. You can also use `blogdown` to create your own blog.
]

.onfire[**Caution #1**: I am not telling you that you should concentrate **everything** within R and RMarkdown.]

---
class: center, middle

# Part I: A brief background to `Markdown`

---

## What is Markdown?

**Markdown** is a light-weight **markup** language that one can use to add formatting elements to plain-text documents.

It is different from **WYSIWYG**-like editors, such as Microsoft Word, Google Docs or Open Office.

> **WYSIWYG** (/ˈwɪziwɪɡ/ WIZ-ee-wig) stands for **W**hat **Y**ou **S**ee **I**s **W**hat **Y**ou **G**et and implies a user-interface that allows one to view something very similar to the end result — while the document is being created.

Instead of clicking buttons to format words and phrases, you have to add Markdown syntax (mostly, punctuation characters) to see the same changes in the text. For instance, here is how part of this slide looks like in Markdown:

````
# What is Markdown?

**Markdown** is a light-weight **markup** language that one can use to add formatting 
elements to plain-text documents.

> **WYSIWYG** (_/ˈwɪziwɪɡ/ WIZ-ee-wig_) stands for **W**hat **Y**ou **S**ee **I**s
W**hat **Y**ou **G**et and implies a user-interface that allows one to view something 
very similar to the end result — while the document is being created.
```` 
---
## How does Markdown work?

.pull-left[
We can summarize how Markdown works in two processes:

1. When you write and export a Markdown document, the text is stored in a plaintext file that has an `.md` or `.markdown` extension;

2. A **Markdown application** processes it using a **parser** and  renders an output in a desired format, _e.g._ `.html`, `.pdf`, `.pptx`, `.tex`, and many other options.

Many websites and programming languages support and developed Markdown parsers or libraries:  Moodle, Slack, Reddit, GitHub, WordPress, StackExchange, and many other websites and applications.
]

.pull-right[
![a](imgs/process.png)
]

---
### A short tale on Markdown

**Markdown** was conceived as a **text-to-HTML converter** (by Mark Gruber, in 2004), to make it easy to read, write and edit webpages (`HTML` and `LaTeX` can be tedious and unreadable!).

.pull-left[
Some text in Markdown:
```` 
 * Bird
 * Magic
````
]

.pull-right[
This is how that was converted to HTML:
````
<ul>
<li>Bird</li>
<li>Magic</li>
</ul>
````
]

`Markdown` was deeply improved when **pandoc** - *an open source tool for broad-scale document conversion* - was released (by John MacFarlane; UC Berkley), providing a greater range of possibilities and a more enriched `Markdown` version for users.

In the meanwhile, users were already creating dynamic and *somewhat* reproducible reports in `R` using `Sweave`.

The `knitr` package was designed to be a transparent engine for dynamic report generation with `R`, solve some long-standing problems in Sweave and combine features in other add-on packages into one package.

---
### `RMarkdown` (`.Rmd`) in a nutshell

`R` **Markdown** stands on the shoulders of `knitr` and `pandoc`.

![A diagram illustrating how an R Markdown document is converted to the final output document.](imgs/workflow.png)

---
## Getting started with `RMarkdown`

**RStudio** already comes with stable and recent versions of `rmarkdown` and `pandoc`. You do not need to install or load them. But, if you want to use `rmarkdown` outside RStudio, you can install it:

```
install.packages("rmarkdown")
```

This is the easiest way to make a new R Markdown document: go to *File > New File > R Markdown*.

If you would like to produce `.pdf` reports, you will need a LaTeX compiler. You can try `tinytex`:

```
install.packages('tinytex')

tinytex::install_tinytex()
```

.center[Now that we are all set, let us take a look at the components of a `RMarkdown` document.]

---
## Structure of a RMarkdown document (`.Rmd`)

.pull-left[
A RMarkdown document usually looks like this:
1. An YAML (**Y**et **A**nother **M**arkup **L**anguage) header, surrounded by `---`; 
2. The body of the document containing prose in `Markdown` formatting; and,
3. Code chunks, delimited by ` ``` `.
]
.pull-right[

````markdown
---
title: "Hello R Markdown"
author: "Awesome Me"
date: "2018-02-14"
output: html_document
---

This is a paragraph in an R Markdown 
document. Below is a code chunk:

```{r}
fit = lm(dist ~ speed, data = cars)
b   = coef(fit)
plot(cars)
abline(fit)
```

The regression's slope is `r b[1]`.

````
]
---
### YAML (YAML Ain’t Markup Language)

The YAML (originally, *Yet Another Markup Language*) header (or metadata) is very important in determining the outcome of your document. By modifying it, you can change, for example:

.pull-left[
1. The **title** and the **subtitle** of your document;
2. The **author** information;
3. The **date**; and,
4. The type, the template and other characteristics of the **output** document (_e.g._, `html_document`, `pdf_document`, `word_document`).
]
.pull-right[
````markdown
 ---
title: "Hello R Markdown"
subtitle: "My first document"
author: "Awesome Me"
date: "2018-02-14"
output: 
 html_document:
  toc: true
 ---
````
]

The YAML metadata depends on the template you are using, causing some YAML fields to not work in some templates.

> For instance, defining `latex_engine: xelatex` only works if your `output` is `pdf_document`. Many templates do not include a table of content, _i.e._ defining  `toc: true` and `toc_depth: 2` will not change your document.

You will find the YAML information in the guide of your template of interest.

---
### Body of the document: Markdown syntax

The text in an RMarkdown document is written in **pandoc**'s `Markdown` syntax.

I strongly recommend that you read [**pandoc**'s `Markdown` manual](https://pandoc.org/MANUAL.html) and the [Definitive Guide to RMarkdown](https://bookdown.org/yihui/rmarkdown/) to know more about the possibilities we have. Here are a few  examples:

.pull-left[
* `_text_` or `*text*` makes your text *italic*;
* `**text**` makes it **bold**;
* Inline code is delimited by a pair of backticks ` `hello` `, while code blocks are determined by three pairs of backticks ``` ``` ``` ````;
* Hyperlinks work as `[text](link)`, _e.g._, [RStudio](https://www.rstudio.com).
]

.pull-right[
* Dolar signs (`$`) translate LaTeX equations, *e.g.*, `$f(k) = {n \choose k} p^{k} (1-p)^{n-k}$` gives us `$$f(k) = {n \choose k} p^{k} (1-p)^{n-k}$$`
* A caret followed by brackets determine footnotes `^[]`, _e.g._, `^[This is a footnote.]`.footnote[1This is a footnote.].1

]

You can also use a [cheatsheet](https://rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf) as quick-reference guide!

---
### Body of the document: Figures

You can also include figures from your directories (or from the Internet) within your `RMarkdown` document using `![caption](figure_directory.extension)`.

.center[![caption](https://communityandquantitativeecology.weebly.com/uploads/8/0/1/8/80182498/image-header-en.png?1471622009)]

---
### Code chunks and inline `R` code

As you have seen, code can be written using backticks. A code chunk usually starts with ` ```{} and ends with ``` `.

You can also write inline code using one backtick, instead of three, _e.g._ ` `pi * x^2` `.

You can also control the behaviour of the code you write!

.center[*Do you want it to be executed? Do you want to show both the code and the output or just the output? Do you want it to be displayed? Do you want to resize the output?*]

.pull-left[
````markdown
```{r}
x <- 5 # radius of a circle
```
For a circle with the radius `r x`,
its area is `r pi * x^2`.
````
]

.pull-right[

```r
x <- 5 # radius of a circle
```

For a circle with the radius 5, its area is 78.5398163.
]

---
## Code chunks and inline `R` code

You can also create a code chunk using the `Insert` button or using the keyboard shortcut `Ctrl + Alt + I` (or `Cmd + Option + I` on macOS).

Code chunks have their own arguments, which are determined within `knitr`. The first argument determines the language of the code block (in this case, `r`), and the following ones determine the chunk's behaviour.

.pull-left[
For instance the one below implies that the figure height is set to four inches and that we are hiding the text output of the code chunk.

````markdown
```{r, chunk-label, results='hide', fig.height=4}
```
````
]

.pull-right[
In the following one, we are echoing the source code in the output document. If you set it to `FALSE`, only the output of the code chunk will be shown.

````markdown
```{r, chunk-label-2, echo = TRUE}
```
````
]

.shout[Note that code chunks must have different labels within the same document. Also, exercise using informative chunk labels. We'll get into that soon!]

---
### Code chunks and inline `R` code: other languages and engines

R Markdown supports (through `knitr`) many other languages, such as Python, Julia, C++, and SQL.

.pull-left[

The chunk below uses the `python` engine:

```python
x = 'hello, python world!'
print(x.split(' '))
## ['hello,', 'python', 'world!']
```

Or, in `Rcpp`:

```cpp
#include <iostream>
using namespace std;

int main() {
 cout << "Hello World!" << endl;
 return 0;
}
```
]

.pull-right[
You can also work in one language and use its output within R!

Let's use the `stan` engine (_i.e._, Stan probabilistic programming language) to create a `stanmodel` object and represent it within R:

]

> Run `names(knitr::knit_engines$get())` to list the names of all available engines.

---
### Code chunks and inline `R` code: Options

The many chunk options in `knitr` are documented at https://yihui.name/knitr/options. Here are a few of them:

.pull-left[
`eval`: whether to evaluate a code chunk.

`echo`: whether to echo the source code in the output document.

`results`: whether to hide or show the results as-is.

`warning`, `message`, and `error`: whether to show warnings, messages, and errors in the output document.

`cache`: whether to evaluate the code block everytime the document is compiled.
]

.pull-right[

`fig.width` and `fig.height`, or `fig.dim`: to define the (graphical device) size of R plots in inches.

`fig.align`: `left`, `center`, or `right` align the figure.

`fig.cap`: to define a figure caption in a string.

`dev`: to define the graphical device to record R plots (default: 'pdf' for LaTeX output, and 'png' for HTML output)

`...` and many other options.
]

---
### Code chunks and inline `R` code: Global settings

If a certain option needs to be frequently set to a value in multiple code chunks, you can set it globally in the first code chunk of your document, *e.g.*:

````markdown
```{r, setup, include=FALSE}
knitr::opts_chunk$set(fig.width = 8, collapse = TRUE)
```
````

I also prefer to include all packages that I am loading within the setup chunk, _e.g._:

````markdown
```{r setup, include=FALSE}
options(htmltools.dir.version = FALSE)

# Include packages to be loaded below here:
library(knitr)    # For knitting document and include_graphics function
library(ggplot2)  # For plotting
library(sf)
library(png)      # For grabbing the dimensions of png files
```
````
.shout[Note: `RMarkdown` documents work as "self-contained" sessions, in a way that you need to include needed libraries and objects in your document, *i.e.* you cannot fetch them from your `R` environment.]
---
### Code chunks and inline `R` code: Figures and Tables

.pull-left[
By default, figures produced by `R` code will be placed immediately after the code chunk they were generated from. For example:
````markdown
```{r mtcars-drat-qsec-plot, echo = TRUE, fig.align = "center", out.width='50%', include=TRUE}
ggplot(mtcars, aes(drat, qsec)) +
 geom_point() +
 theme_classic()
```
````
<img src="BriefIntroRMarkdown_PPN_LabMeeting_PHPB_files/figure-html/mtcars-drat-qsec-plot-1.jpeg" width="50%" style="display: block; margin: auto;" />
]

.pull-right[
And, you can use both `kable` and `kableExtra` to output tables after the code chunks:
````markdown
```{r tables-mtcars}
knitr::kable(iris[1:5, ], caption = 'A caption')
```
````

Table: A caption

Sepal.Length   Sepal.Width   Petal.Length   Petal.Width  Species 
-------------  ------------  -------------  ------------  --------
          5.1           3.5            1.4           0.2  setosa  
          4.9           3.0            1.4           0.2  setosa  
          4.7           3.2            1.3           0.2  setosa  
          4.6           3.1            1.5           0.2  setosa  
          5.0           3.6            1.4           0.2  setosa  
]

---
class: middle

### We have just covered the basics of Markdown and RMarkdown!

### Now, let's work on a few RMarkdown documents!

---
class: middle

### Let's start by:

1. Creating a `RMarkdown` document (*File > New File > R Markdown document*);
2. Knitting (or rendering) it; and,
3. Changing its template.

---
## `RMarkdown` templates

There are many templates for `RMarkdown` documents:

* `rmdformats` 
* `prettydocs`
* `tufte`

As well as extensions to write articles, books and blogs:

* `rticles`
* `bookdown`
* `blogdown`

---

## Creating manuscripts with `rticles`

You can install and use rticles from `CRAN` as follows:

```
install.packages("rticles")
```

In a nutshell, `rticles` contain `LaTeX` templates that conform precisely to submission standards. At the same time, one can write the manuscript in `markdown` syntax, `R` code and seamless `knit` a submission-ready manuscript.

.pull-left[
You can obtain the current implemented templates using `getNamespaceExports("rticles")`. Here are the first 15:
]

.pull-right[

```
##  [1] "mnras_article"      "ctex"               "springer_article"  
##  [4] "copernicus_article" "sim_article"        "rsos_article"      
##  [7] "pnas_article"       "rjournal_article"   "tf_article"        
## [10] "joss_article"       "aea_article"        "oup_article"       
## [13] "acs_article"        "ams_article"        "plos_article"
```
]

To use `rticles` outside of RStudio, you can create manuscripts using `rmarkdown::draft()`

``` 
rmarkdown::draft("MyJSSArticle.Rmd", template = "jss_article", package = "rticles")
rmarkdown::draft("MyRJournalArticle", template = "rjournal_article", package = "rticles")
```

---
## Creating manuscripts with `rticles`

`rticles` templates have an extended YAML, which allows you to specify details on your paper. For instance, this is the `Springer` one:
.pull-left[
````markdown
title: Title here
subtitle: Do you have a subtitle? If so, write it here
titlerunning: Short form of title
authorrunning:
  Short form of author list if too long for running head
thanks: |
  Grants or other notes about the article that should go
  on the front page should be placed here. General
  acknowledgments should be placed at the end.
authors:
  - name: Author 1
    address: Department of YYY, University of XXX
    email: abc@def
  - name: Author 2
    address: Department of ZZZ, University of WWW
    email: djf@wef
keywords:
  - key
  - dictionary
  - word
````
]

.pull-right[
````markdown
MSC:
  - MSC code 1
  - MSC code 2    
abstract: |
  The text of your abstract.  150 -- 250 words.
bibliography: bibliography.bib
output: 
  rticles::springer_article
````
]

---
### Writing very long RMarkdown documents can be a problem

.pull-left[
Tip #1: You can either adopt "mother- and child-RMarkdown documents":
]

.pull-right[
```
/
data/ – where I save my raw data
  output/ – where I save my analysis and plot
  RMarkdown/ – save all Rmd scripts here
    main_analysis_file.Rmd [mother]
    analysis-part1.Rmd [child]
    analysis-part2.Rmd [child]
    analysis-part3.Rmd [child]
    analysis-part4.Rmd [child]
  functions/ – save functions here
```
]

.pull-left[
Tip #2: Use [`bookdown`](https://github.com/rstudio/bookdown):

]

.pull-right[
````markdown
index.Rmd
01-intro.Rmd
02-literature.Rmd
03-method.Rmd
04-application.Rmd
05-summary.Rmd
````

]

---
### A few advantages and disadvantages (in my opinion):
.pull-left[
#### Advantages

`rmarkdown` helps you create dynamic analysis documents that combine code, rendered output (such as figures), and prose. You can use its rendered content to:

1. Do data science interactively (within the RStudio IDE);
1. Reproduce your analyses;
1. Collaborate and share code with others; and
1. Communicate your results to others.

]

.pull-right[

#### Disadvantages

1. Getting your collaborative network to work on `RMarkdown` can be challenging. Someone not willing to work with it can translate into extra work to you;

2. Until yesterday (2020-06-07), I could not find a grammatical proofreader for `RMarkdown`. A potential strategy should be then to *Export* or *Paste* the final manuscript to an application that has proofreading (such as Word). *Not very happy about this!*

3. *Gather thoughts from other people from the lab*.

]

---

### Other applications: websites with `blogdown`

```r
knitr::include_url("https://pedrohbraga.github.io/")
```

---
### Building your own CV

```r
knitr::include_graphics("https://github.com/pedrohbraga/my-curriculum-vitae-friggeri/raw/master/braga_php-cv.pdf")
```

![](https://github.com/pedrohbraga/my-curriculum-vitae-friggeri/raw/master/braga_php-cv.pdf)

---

## What about avoiding issues?

In the first place, I recommend the following:

1. Develop code in chunks and execute the chunks until they work, then move on;
2. `knit` the document regularly to check for errors.

.pull-left[
Error messages usually are informative:

````markdown
```{r title-one}
```
````

````markdown
```{r title-one}
```
````
]

.pull-right[
R Markdown output:

```
processing file: common-problems.Rmd
Error in parse_block(g[-1], g[1], params.src) : 
  duplicate label 'title-one'
```
]

.pull-down[.onfire[Tip: Having adequate chunk labels help tracking errors.]]

---
# Advanced customization

Many `RMarkdown` packages were originally designed to have some flexibility in terms of customization, meaning that if you know CSS, HTML and LaTeX, you should be able to freely customize the style of your document.

This presentation has a modified CSS theme (`phpb-theme.css`):

````markdown
output:
  xaringan::moon_reader:
    css: ["default",  "css/phpb-theme.css"]
````

.pull-left[

A very simple example: everytime time I want to *shout* something in a different font and in bold, I can write `.shout[This is a special text!]`, which will display:

.shout[This is a special text!]
]

.pull-right[
Within the `CSS` theme `phpb-theme.css`, there are a few lines defining what `.shout[]` will do:

```
.shout { color: #1c5253; 
font-family: 'Lato', sans-serif;
font-weight: bold;
}
```
]

.onfire[This can be fun and rewarding, but it can also waste your time.]

---
class: inverse, middle, center

# This is all for today! Questions?

.pull-down[.onfire[Thank you all!]]
---