AIM RSF R series: Literate programming with R Markdown

class: center, middle, inverse, title-slide

.title[
# AIM RSF R series: Literate programming with R Markdown
]
.subtitle[
## Based on Data Carpentry: R for Social Scientists
]
.author[
### Eirini Zormpa
]
.date[
### 10 January 2023 (last updated 2023-01-10)
]

---

# Summary of session 4: Data visualisation with `ggplot2`

- ✅ Create line plots, scatter plots, and bar plots using `ggplot2`.
- ✅ Apply faceting in `ggplot2`.
- ✅ Build complex and customized plots from data in a data frame.

---
class: center, middle

# Any questions?

---

# Learning objectives: Literate programming with `R Markdown`

- ✅ Describe what literate programming is and explain why it is useful
- ✅ Create a `.Rmd` document containing R code, text, and plots
- ✅ Understand basic syntax of (R) Markdown
- ✅ Customise code chunks to control formatting

---

# What is literate programming?

With literate programming, we can combine (nicely formatted!) narrative text with code, and code output all in the same document.

`R Markdown` is one example of such a document, but you may have also heard of Jupyter notebooks, which do something similar.

I love `R Markdown` documents because 1. they are reproducible  and 2. they are extremely versatile.

---

# Example of an `R Markdown` document

.pull-left[

]

.pull-right[

]

---

# Why `R Markdown`: reproducibility ♻️

By combining text, code, and code output in the same document:

- it's easier to **document** your data cleaning and analysis, helping you and other understand your work

--
- it's easier to **avoid copy-paste errors**

--
- it's easier to **update your manuscript** if you collect more data or change your data cleaning

--
- because `.Rmd` files are plain text files, they are compatible with version control systems, such as `git`.

---

# Why `R Markdown`: versatility

## Outputs

You can create different kinds of documents from R Markdown: **reports**, **slides** (like these ones!), journal **papers**, interactive **web apps**!

---

# Anatomy of an `R Markdown` document

.pull-left[

]

.pull-right[

1. YAML header
2. Markdown text
3. Code chunks (supports R, Python, Stan, etc.)

]

---

# `here` for relative paths

.footnote[Artwork by [Allison Horst](https://allisonhorst.com/), reused under a CC-BY licence.]

---

# Customising chunk output

There are options available to customise how the code-chunks are presented in the output document.
The options are entered in the code chunk after `chunk-name`and separated by commas, e.g. `{r chunk-name, eval = FALSE, echo = TRUE}`.

| Option | Output |
|--------|--------|
| `eval` | Whether or not the code within the code chunk should be run. |
| `echo` | Whether the code chunk will appear in the output document. |
| `include` | Whether if the output of a code chunk should be included in the document.|
| `warning` | Whether the output document will contain warning messages. |
| `message` | Whether the output document will display messages. |
| `fig.align` | Where the figure from your R code chunk should be positioned on the page.

---
class: center, middle, inverse

# Exercise 1

Play around with the different options in the previous code chunk, and re-**Knit** to see what each option does to the output.

What happens if you use `eval = FALSE` and `echo = FALSE`? What is the difference between this and `include = FALSE`?

---
class: inverse

# Writing papers in `R Markdown`

1. Install `tinytex` to install a LaTeX distribution, if you don't already have one
    - load `tinytex` and then run the command `tinytex::install_tinytex()`
2. Install `rticles`
3. Create a new R Markdown file `From template` and select `Journal of Open Source Software article`

---

# `Quarto`: The future of `R Markdown`

.footnote[Artwork by [Allison Horst](https://allisonhorst.com/), reused under a CC-BY licence.]

---
class: center, middle

# Thank you for your attention and participation throughout this workshop series✨ 🙏