Reproducible documents step by step

An HTML example

Reproducible documents step by step

1. Create a .qmd document
2. Write the document including:

• text e.g. introduction, methods, or discussion
• code (R, Python, Julia) that produces numbers, figures, tables, …
• metadata that defines how the document should look like (e.g. which output format)

3. Render the document to a defined output format (e.g. PDF) using Quarto

References for all the elements

• Mardown syntax reference
• Code chunks:
  • R code
  • Python code
• YAML header options:
  • HTML
  • PDF
  • DOCX

The text body - Markdown

Markdown is a simple markup language to create formatted text, you can e.g.

# Header level 1
## Header level 2
### Header level 3

A bullet point list

- item 1
- item 2
- item 3

The text body - Markdown

You can also do more complex things like:

• Including images, links or footnotes
• Adding citations
• Latex style mathematical formulas

The text body - Markdown

• RStudio and Positron also have visual editors
• Convenient, word-like interface for formatting text and adding features.
  • E.g. Insert citations from Zotero library, DOI search, PubMed, …

The Code

Inline code starts and ends with 1 backtick

`{r} `

The mean of the values 1, 2 and 3 is `{r} mean(1:3)`

The mean of the values 1, 2 and 3 is `{python} np.mean([1,2,3])`

The Code

Code chunks starts and ends with 3 backticks

```{r}
library(ggplot2)

ggplot(penguins, aes(flipper_len, body_mass)) + 
  geom_point() + 
  geom_smooth(method = "lm")
```

```{python}
import numpy as np
import matplotlib.pyplot as plt

r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(subplot_kw = {'projection': 'polar'})
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()
```

The Code

Run code chunk

• Code chunks can be run inside the document
• Code chunks are run when document is rendered

The code

Code chunk have special comments that start with #| and that control the behaviour of the chunk.

```{r}
#| label: fig-penguins
#| fig-cap: Temperature and ozone level.
#| echo: false

library(ggplot2)

ggplot(penguins, aes(flipper_len, body_mass)) + 
  geom_point() + 
  geom_smooth(method = "lm")
```

• label: Figure and chunk label that can be referred to in text
• fig-cap: Figure caption
• echo: Include the output (i.e. the plot) in the document but don’t show the code

YAML header

---
title: "My first document"
subtitle: "Whatever subtitle makes sense"
author: "Selina Baldauf"
date: today
---

YAML header

For document output formats

---
format: html
---

or other formats like pdf, docx, revealjs, powerpoint, …

---
title: "My first document"
author: "Selina Baldauf"
date: today
format: 
  html: default
  pdf: default
  docx: default
---

YAML header

For document options

---
title: "My first document"
author: "Selina Baldauf"
date: today
format: 
  html: 
    number-sections: true
    toc: true
    toc-location: left
---

• Some options are shared, some are specific to one format
• Be careful to get the indentation right!

YAML header

Execute options

---
title: "My first document"
author: "Selina Baldauf"
date: today
format: html
execute: 
  message: false
  warning: false
---

• Default options for code chunks
• Can be overwritten by local comments in code chunks

Render the document

Many different options:

• In RStudio/Positron/VS Code: Render button or keyboard shortcut (usually Ctrl/Cmd + Shift + K)
• In the terminal/console: quarto render my_document.qmd
• From R, using the quarto package: quarto::quarto_render("my_document.qmd")

quarto render my_document.qmd --to html
quarto render my_document.qmd --to docx

Render the document

What happens during rendering?

Artwork from “Hello, Quarto” keynote by Julia Lowndes and Mine Çetinkaya-Rundel,presented at RStudio Conference 2022. Illustrated by Allison Horst.

Parameterized reports

You can also define parameters to be used in your document

---
title: "My first document"
format: html
params:
  species: "Adelie"
---

```{python}
#| tags: [parameters]

species = 'Adelie'
```

Parameterized reports

Render your document with different parameter inputs:

In R:

quarto::quarto_render(
  input = "my_report.qmd",
  output_format = "pdf",
  output_file = "report_chinstrap.pdf",
  params = list(species = "Chinstrap")
)

In the console:

quarto render my_report.qmd --to pdf --output "report_chinstrap.pdf" -P species:Chinstrap

Summary

• Quarto combines formatted text and code in one document

• Other options and formats: Presentations, Books, Websites
• Easily publish documents or websites
• Check out the demo project and the resources on the lecture website

Next lecture

Topic tba

📅 20th November 🕓 4-5 p.m. 📍 Webex

🔔 Subscribe to the mailing list

📧 For topic suggestions and/or feedback send me an email