4_Day2.knit

class: inverse title-slide
background-image: url(img/rmarkdown.png)
background-size: 30%
background-position: 90% 90%

# Reproducible Documents with `{rmarkdown}`

## Day 2

### Instructor: [Selina Baldauf](https://www.bcp.fu-berlin.de/biologie/arbeitsgruppen/botanik/ag_tietjen/People/wissenschaftliche_programmierer/baldauf/index.html) <br>

### Freie Universität Berlin - Theoretical Ecology

.footnote-left[
  2022-22-03 (updated: 2022-09-13)
]

---

# Topics today

- Visual editor in RStudio

- Citations

- Make tables look nice

- Some more tips and good practice

---

# The visual editor in RStudio

- WYSIWYG editor (*What you see is what you get*)

- More similar to Word etc. but with less functionality
  
--
  
- Click on the button on the top left

![:scale 40%](img/day2/source_visual.png)

--

- Very helpful in the beginning until you remember how everything works in markdown

- Especially helpful for markdown tables and citations

--

- But careful: Can reformat the `.Rmd` file a bit, so sometimes if you switch back 
it can look different than before.

- Best to choose the editor you like most and stick with it

---

# Adding citations - The classic way

Bibliographies can be included via a BibTeX data base.

--
  
- Create a `.bib` file that consists of bibliography entries
  
```bibtex
@Book{cookbook,
  title = {R Markdown Cookbook},
  author = {Yihui Xie and Christophe Dervieux and Emily Riederer},
  publisher = {Chapman and Hall/CRC},
  address = {Boca Raton, Florida},
  year = {2020},
  note = {ISBN 9780367563837},
  url = {https://bookdown.org/yihui/rmarkdown-cookbook},
  }
 ```

---

# Adding citations - The classic way

Bibliographies can be included via a BibTeX data base.

- Create a `.bib` file that consists of bibliography entries

- Add name and location of your `.bib` file as a medatada field in YAML header
  
```yaml
---
output: html_document
bibliography: references.bib
---
```

--

- Cite an article from the database with `@bib_item_name` for in text citations or
`[@bib_item_name]` for citation in brackets
  - Here, I cite `@cookbook` because it's a good book `[@cookbook]`
  - Here, I cite Xie, Dervieux, and Riederer (2020) because it’s a good book (Xie, Dervieux, and Riederer 2020)

--

- List of references used will be added to the end of the document
  - Just add a heading `# References` to end of the doc

---

# Adding citations - The classic way

- Add a custom citation style file with:

```yaml
---
output: html_document
bibliography: references.bib
csl: myrefstyle.csl
---
```

--

- Most (all?) reference managers can export your citations as a `.bib` file

---

# Adding citations - Visual editor

Citations can also be added using the **visual editor** in RStudio.

--

- Visual editor creates and updates `.bib` file automatically

--

- Search and add citations from
  - The bibliography file
  - Zotero
  - DOI
  - ...
  
---

# Adding citations - Visual editor

- Just click on the `Insert -> citation`

![](img/day2/visual_editor_citation.png)

---

# Adding citations - Visual editor

- Select source of citation on the left (e.g. DOI, Zotero, ...)
- Click `Insert` to add citation to `bibliography.bib`

![:scale 60%](img/day2/insert_citation_window.png)

---

# Adding citations - Visual editor

- You can also start typing `@` and the editor will suggest you a list of citations that fit

![](img/day2/citation_insert.png)

---

# Adding citations - Visual editor

**Using Zotero**

- If you use Zotero on your machine, RStudio should automatically detect the installation

- If not, go to `Tools->Global Options->R Markdown -> Citations` and enter the location
of your Zotero data directory and the library that you would like to use
  - In General this should be recognized automatically

---
class: inverse, middle, center

# .large[Now you]

## Task 1: Add some citations (20 mins)

#### Find the task description <a href="https://selinazitrone.github.io/rmarkdown/tasks/day2/02_01_penguin_citation.html">here</a>

---
class: inverse, middle, center

# .large[Nice looking tables in R Markdown]

---

# Nice looking tables with R Markdown

- The default for printing tables looks the same as printing it in the console:

```r
iris_sum
```

```
## # A tibble: 3 x 5
##   Species    Sepal.Length Sepal.Width Petal.Length Petal.Width
##   <fct>             <dbl>       <dbl>        <dbl>       <dbl>
## 1 setosa             5.01        3.43         1.46       0.246
## 2 versicolor         5.94        2.77         4.26       1.33 
## 3 virginica          6.59        2.97         5.55       2.03
```
- This is not really nice for documents

---

# `knitr::kable()`

Simple to use table generator from the `knitr` package.

```r
knitr::kable(iris_sum) # or iris_sum %>% knitr::kable()
```

<table>
 <thead>
  <tr>
   <th style="text-align:left;"> Species </th>
   <th style="text-align:right;"> Sepal.Length </th>
   <th style="text-align:right;"> Sepal.Width </th>
   <th style="text-align:right;"> Petal.Length </th>
   <th style="text-align:right;"> Petal.Width </th>
  </tr>
 </thead>
<tbody>
  <tr>
   <td style="text-align:left;"> setosa </td>
   <td style="text-align:right;"> 5.006 </td>
   <td style="text-align:right;"> 3.428 </td>
   <td style="text-align:right;"> 1.462 </td>
   <td style="text-align:right;"> 0.246 </td>
  </tr>
  <tr>
   <td style="text-align:left;"> versicolor </td>
   <td style="text-align:right;"> 5.936 </td>
   <td style="text-align:right;"> 2.770 </td>
   <td style="text-align:right;"> 4.260 </td>
   <td style="text-align:right;"> 1.326 </td>
  </tr>
  <tr>
   <td style="text-align:left;"> virginica </td>
   <td style="text-align:right;"> 6.588 </td>
   <td style="text-align:right;"> 2.974 </td>
   <td style="text-align:right;"> 5.552 </td>
   <td style="text-align:right;"> 2.026 </td>
  </tr>
</tbody>
</table>

--

- Chose `kable` as default table printing in YAML header:

```yaml
df_print: "kable"
```

--

- `kable` works for PDF, HTML and Word output

---

# `knitr::kable()`

Add arguments for additional formatting:

```r
kable(x,
  format,
  digits = getOption("digits"),
  row.names = NA,
  col.names = NA,
  align, caption = NULL,
  label = NULL,
  format.args = list(),
  escape = TRUE, ...
)
```

- See [here](https://bookdown.org/yihui/rmarkdown-cookbook/kable.html) for many examples
many different use cases

---

# `knitr::kable()`

**Example:**

```r
knitr::kable(
  iris_sum,
  digits = 1,
  col.names = c("Species", "Sepal Length", "Sepal Width", "Petal Length", "Petal Width"),
  caption = "Summary of the Iris data",
  align = "l"
)
```

<table>
<caption>Summary of the Iris data</caption>
 <thead>
  <tr>
   <th style="text-align:left;"> Species </th>
   <th style="text-align:left;"> Sepal Length </th>
   <th style="text-align:left;"> Sepal Width </th>
   <th style="text-align:left;"> Petal Length </th>
   <th style="text-align:left;"> Petal Width </th>
  </tr>
 </thead>
<tbody>
  <tr>
   <td style="text-align:left;"> setosa </td>
   <td style="text-align:left;"> 5.0 </td>
   <td style="text-align:left;"> 3.4 </td>
   <td style="text-align:left;"> 1.5 </td>
   <td style="text-align:left;"> 0.2 </td>
  </tr>
  <tr>
   <td style="text-align:left;"> versicolor </td>
   <td style="text-align:left;"> 5.9 </td>
   <td style="text-align:left;"> 2.8 </td>
   <td style="text-align:left;"> 4.3 </td>
   <td style="text-align:left;"> 1.3 </td>
  </tr>
  <tr>
   <td style="text-align:left;"> virginica </td>
   <td style="text-align:left;"> 6.6 </td>
   <td style="text-align:left;"> 3.0 </td>
   <td style="text-align:left;"> 5.6 </td>
   <td style="text-align:left;"> 2.0 </td>
  </tr>
</tbody>
</table>

---

# The `{kableExtra}` package

- Provides options for table styling for HTML and PDF tables

--

- Most of the features work for both HTML and PDF tables

- Find the full documentation [here](https://haozhu233.github.io/kableExtra/)
  - If you use tables a lot, I recommend looking through the documentation to see
  all possibilities

--

- Load the packages in the setup chunk before using them

```r
library(knitr)
library(kableExtra)
```

--

- **Careful:** Don't load `kableExtra` for `word_document` output. This will break 
the tables made with `kable`

---

# The `{kableExtra}` package

**`kable_styling()`** is the basic styling function

- Use the pipe operator (`%>%`) to pipe `kable()` output to styling function `kable_styling()`
  - Use the keyboard shortcut ` Ctrl/Cmd + Shift + M ` to insert ` %>% `

--

```r
iris_sum %>% 
  kable() %>%
  kable_styling(
  full_width = FALSE, # display table on full page width?
  position = "center",  # if not full width -> where to put table
  font_size = 15
)
```

<table class="table" style="font-size: 15px; width: auto !important; margin-left: auto; margin-right: auto;">
 <thead>
  <tr>
   <th style="text-align:left;"> Species </th>
   <th style="text-align:right;"> Sepal.Length </th>
   <th style="text-align:right;"> Sepal.Width </th>
   <th style="text-align:right;"> Petal.Length </th>
   <th style="text-align:right;"> Petal.Width </th>
  </tr>
 </thead>
<tbody>
  <tr>
   <td style="text-align:left;"> setosa </td>
   <td style="text-align:right;"> 5.006 </td>
   <td style="text-align:right;"> 3.428 </td>
   <td style="text-align:right;"> 1.462 </td>
   <td style="text-align:right;"> 0.246 </td>
  </tr>
  <tr>
   <td style="text-align:left;"> versicolor </td>
   <td style="text-align:right;"> 5.936 </td>
   <td style="text-align:right;"> 2.770 </td>
   <td style="text-align:right;"> 4.260 </td>
   <td style="text-align:right;"> 1.326 </td>
  </tr>
  <tr>
   <td style="text-align:left;"> virginica </td>
   <td style="text-align:right;"> 6.588 </td>
   <td style="text-align:right;"> 2.974 </td>
   <td style="text-align:right;"> 5.552 </td>
   <td style="text-align:right;"> 2.026 </td>
  </tr>
</tbody>
</table>

---

# The `{kableExtra}` package

**`kable_styling()`** provides styling options

- Additional styling options for HTML output are passed via `bootstrap_options`

--

```r
iris_sum %>% 
  kable() %>%
  kable_styling(
  full_width = FALSE, # display table on full page width?
  position = "center",  # if not full width -> where 
  font_size = 15,
* bootstrap_options = c("striped", "hover")
)
```

<table class="table lightable-classic lightable-striped lightable-hover" style='font-size: 15px; width: auto !important;  font-family: "Arial Narrow", "Source Sans Pro", sans-serif; margin-left: auto; margin-right: auto;'>
 <thead>
  <tr>
   <th style="text-align:left;"> Species </th>
   <th style="text-align:right;"> Sepal.Length </th>
   <th style="text-align:right;"> Sepal.Width </th>
   <th style="text-align:right;"> Petal.Length </th>
   <th style="text-align:right;"> Petal.Width </th>
  </tr>
 </thead>
<tbody>
  <tr>
   <td style="text-align:left;"> setosa </td>
   <td style="text-align:right;"> 5.006 </td>
   <td style="text-align:right;"> 3.428 </td>
   <td style="text-align:right;"> 1.462 </td>
   <td style="text-align:right;"> 0.246 </td>
  </tr>
  <tr>
   <td style="text-align:left;"> versicolor </td>
   <td style="text-align:right;"> 5.936 </td>
   <td style="text-align:right;"> 2.770 </td>
   <td style="text-align:right;"> 4.260 </td>
   <td style="text-align:right;"> 1.326 </td>
  </tr>
  <tr>
   <td style="text-align:left;"> virginica </td>
   <td style="text-align:right;"> 6.588 </td>
   <td style="text-align:right;"> 2.974 </td>
   <td style="text-align:right;"> 5.552 </td>
   <td style="text-align:right;"> 2.026 </td>
  </tr>
</tbody>
</table>

---

# The `{kableExtra}` package

**`kable_styling()`** provides styling options

- Additional styling options for PDF output are passed via `latex_options`

```r
iris_sum %>%
* kable(booktabs = TRUE) %>%
  kable_styling(
    full_width = FALSE,
    position = "center", 
    font_size = 15,
    bootstrap_options = c("striped", "hover"),
*   latex_options = c("striped", "hold_position", "scale_down")
  )
```

- `booktabs = TRUE` will use the `booktabs` LaTeX package to create nice horizontal lines and removes vertical lines
- `hold_position` places the table where it is created in the document (no floating)
- `scale_down` scales the text down to fit the table width

---

# The `{kableExtra}` package

**`kable_styling()`** provides styling options

- Additional styling options for PDF output are passed via `latex_options`

```r
iris_sum %>%
* kable(booktabs = TRUE) %>%
  kable_styling(
    full_width = FALSE,
    position = "center", 
    font_size = 15,
    bootstrap_options = c("striped", "hover"),
*   latex_options = c("striped", "hold_position", "scale_down")
  )
```

- Depending on the output format you chose, `bootstrap_options` or `latex_options` will be ignored

---

# The `{flextable}` package

--

- Works with PDF, HTML and Word output
  - Can be used as an option to style tables in Word

- Alternative to `kable` and `kableExtra`

- See [here](https://ardata-fr.github.io/flextable-book/index.html) for an extensive documentation
of the flextable package

---
class: inverse, middle, center

# .large[Now you]

## Task 3: Create a nice table (20 mins)

#### Find the task description <a href="https://selinazitrone.github.io/rmarkdown/tasks/day2/02_02_penguin_tables.html">here</a>