Introduction to R Markdown

class: center, middle, inverse, title-slide

# Introduction to R Markdown
### Nikos Bakogiannis
### 15 April, 2020

---

class:left, inverse

### Why R Markdown

-  **Because it offers**
    - Code, results and text in the same document
    - Plots automatically generated and updated from your data
    - A future-proof file format for your documents
    - An easy-to-write syntax with no need for solid programming experience

---

class:left, inverse

### Why R Markdown

- **R Markdown** is a file format for making dynamic documents with R
   - Written in markdown (an easy-to-write plain text format)
   - Contains chunks of embedded R code

---

class:left, inverse

### Why R Markdown

- Create **content rich, reproducible** documents
   - Reproducible reports using **knitr package**
   - **Knitr** runs individually each chunk of R code and appends the results to the file
   
- Variety of output formats
   - Rmd file can be converted into HTML, PDF or Microsoft Word file
   - **rmarkdown** preserves the text, code results, as well as original formatting

<img src="images/sl3_process.png" width="400px" style="display: block; margin: auto;" />
---

class:left, inverse

### Why R Markdown

- Plethora of tasks can be performed with **R Markdown**
   - Compile a single R Markdown document to a report in different formats
   - Create notebooks  in which you can run code interactively
   - Write journal articles
   - Author books of multiple chapters
   - Generate website and blogs

---

class:left, inverse

### Anatomy of an R Markdown document

---

class:left, inverse

### Anatomy of an R Markdown document

**Basic syntax**

---

class:left, inverse

### Anatomy of an R Markdown document

**Basic syntax**

<img src="images/sl8_basicSyntax.png" width="800px" style="display: block; margin: auto;" />
---

class:left, inverse

### Time for practice

**Exercise 1**

[Exercise 1](https://rstudio-pubs.zhaw.ch/connect/#/apps/65/access)

---

class:left, inverse

### Anatomy of an R Markdown document

**Code**

Chunk options:
  - **echo**: binary option to display or not the code in the knitted ouptut
  - **eval**: binary option to run or not the code within the chunk, while it is knitting
  - **include**: binary option to include or not in the knitted output, whatever lies within the code chunk

---

class:left, inverse

### Anatomy of an R Markdown document

**Code**

*Setup chunk*

- Usually an R Markdown document starts with a setup chunk which imbues a special behaviour to all other chunks as well
- **knitr::opts_chunk$set()** sets the default options for all the other chunks

---

class:left, inverse

### Anatomy of an R Markdown document

**Code**

*Including images*

---

class:left, inverse

### Anatomy of an R Markdown document

**Code**

*Including plots*

---

class:left, inverse

### Anatomy of an R Markdown document

**Code**

*Including tables*

---

class:left, inverse

### Time for practice

**Exercise 2**

[Exercise 2](https://rstudio-pubs.zhaw.ch/connect/#/apps/65/access)

---

class:left, inverse

### Citations, cross-referencing

- Create a simple textfile with **.bib** extension
   - Add all your references (in **BibTex format**) in the .bib file

- Reference the .bib file in the YAML header
       - Define the correct path that links to the .bib file
         **"working_directory/bib_file_name"**
   
<img src="images/crossRef_2.png" width="350px" style="display: block; margin: auto auto auto 0;" />

---

class:left, inverse

### Citations, cross-referencing

- Within text, references go inside brackets
   - Chicago reference style is the default one
   - You can change the reference style by adding the following to the YAML header: **csl: my-style.csl**

---

class:left, inverse

### Citations, cross-referencing

- **bookdown** package offers the option for cross-referencing
    - Option to refer to **sections**, **figures** as well as to **tables** within the text
    - The option is enabled by changing the output format to:
        - bookdown:: html_document2
        - bookdown:: pdf_document2
        - bookdown:: word_document2

---

class:left, inverse

### Citations, cross-referencing

- **Cross-referencing figures**
    - Figures and tables must have captions in order to reference them
    - The following syntax is used for the cross-reference
        - **\ref(fig:label)**
        
<img src="images/slide19_cross.png" width="600px" style="display: block; margin: auto;" />

---

class:left, inverse

### Time for practice

**Exercise 3**

[Exercise 3](https://rstudio-pubs.zhaw.ch/connect/#/apps/65/access)

---
class:left, inverse

### Customizing your output

-  **Customizing** via YAML header
  - Variery of available output formats (html, pdf, doc)
  - Customization options depend on the specified output format

Always think about the **IDENTATION** rules !!  [read more about it!!](https://learn-the-web.algonquindesign.ca/topics/markdown-yaml-cheat-sheet)

---
class:left, inverse

### Customizing your output

---
class:left, inverse
### Customizing your output

-  **html output** -- further customization
  - Option to use a theme or a a custom .css _(cascading style sheets)_ style
    - variety of theme options: (“cerulean”, “journal”, “flatly”, “darkly” etc)

- For further customization options, read the following:
   - [pandoc documentation](https://pandoc.org/MANUAL.html)
   - [Rmd to docx](https://rmarkdown.rstudio.com/articles_docx.html)

---
class:left, inverse
### Customizing your output

-  **html output** -- putting content in tabs
   - Adding **{.tabset}** after a header makes its sub-headers appear as tabs

---
class:left, inverse
### Collaborating and version control

-  **Create an R Project**
   - The best way of keeping your files (scripts, figures, text) in a centralized, well-structured working directory
   - Manage your workflow by defining global and project options
   - Option for version control and portability

---
class:left, inverse
### Collaborating and version control - Git

- **Git** is a version control system that allows to keep track of changes to files
projects over time
   - It is mainly used as a collaboration tool allowing people to work on the same project at the same time.
- **GitHub** is a website that hosts Git repositories online, making easier for developers
to share code
- **Repositories** are folders which contain intentional snapshots of progress, the    so-called **commits**

---
class:left, inverse
### Collaborating and version control - Git

-  **Working with repositories**
- There are two main ways a user can "use" a repository
   - download as a zip file
   - cloning the reporitory

---

class:left, inverse

### Time for practice

**Exercise 4**

[Exercise 4](https://rstudio-pubs.zhaw.ch/connect/#/apps/65/access)

---

class:left, inverse

### References

- [bookdown: Authoring Books and Technical Documents with R Markdown](https://bookdown.org/yihui/bookdown/)
- [Writing your thesis with bookdown, by Ed D. J. Berry](https://eddjberry.netlify.com/post/writing-your-thesis-with-bookdown/)
- [R Markdown: The Definitive Guide](https://bookdown.org/yihui/rmarkdown/)
- [Hands-On Programming with R](https://rstudio-education.github.io/hopr/)
- [R for Data Science](https://r4ds.had.co.nz/)

*The tutorial is mainly inspired by the R Markdown workshop from Ulrik Lyngs, which took place at St. Anne’s College, University of Oxford (March 12-13 2019)*