Writing dynamic and reproducible documents

An introduction to R Markdown / Quarto

Author
Affiliation

Julien Martin

BIO 8940 - Lecture 2

Published

September 19, 2024

Credit: Ignasi Bartomeus, PhD

0.1

1 How can you reproduce results?

1.1

1.2 What do we need to make research reproducible?

  • Something to integrate text, figures and code
    • R, Python, etc
  • Something that can be continuously edited and updated
    • Living or dynamic document
  • Something that can be easily used in versioning tools
    • Git

1.3

1.4 Quarto ?

  • multi-language, next generation version of R Markdown

  • include many new new features and capabilities

  • Like R Markdown, Quarto uses knitr to execute R code, and is therefore able to render most existing Rmd files without modification.

1.5 R Markdown workflow

1.6 Quarto workflow

2 Structure of a Rmd/qmd document

2.1

qmd/Rmd
YAML frontmatter
Markdown content
Code chunks

2.2 Rmd/qmd document

2.3 Rmd/qmd document

3 Markdown

qmd/Rmd
YAML frontmatter
Markdown content
Code chunks

3.1 What is Markdown?

  • A way to write stuff
  • Mostly plain words, with some formating

3.2 Websites that use Markdown

3.3 Headers

  • Use # to create headers
  • Multiple #’s create lower level headers

3.4 Text

  • Text is rendered as plain text

3.5 Lists

  • Use asterisks to make bullet points
  • Use numbers to make numbered lists
  • Use 4 spaces or 1 tab for indentation

3.7 Images

  • Use a link preceded by an ! to insert an image
  • The link text should be
    • a URL if the image is hosted online
    • a file path if the image is saved on your computer

3.8 Equations

  • Write equations with Latex syntax

3.9 Equation blocks

3.10 Tables

| header A | header B  | header C |
|:---------:|:--------:|---------:|
| left      | center   | right    |

Table: This is a title
This is a title
header A header B header C
left center right

3.11 R Markdown Reference Guide

https://rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf

4 Knitr Code chunks

qmd/Rmd
YAML frontmatter
Markdown content
Code chunks

4.1 Embed code

  • Insert chunk of R code
  • Code will run and include results.

4.2 Inline code

  • Place code in a sentence with
  • Code will be replaced with results

4.3 Chunk options

Rmd (R markdown) and qmd (quarto) differ:

  • Rmd: chunk options on one line between the {} after the r
  • qmd: either as Rmd or within the chunk with yaml style notation

Rmd

```{r name, echo=FALSE}
1+1
```

Can lead to really long lines

qmd

```{r}
#| label: name
#| echo: false
1+1
```

takes more vertical space but cleaner

4.4 echo

  • echo = FALSE or #| echo: false hides code.

4.5 eval

  • eval = FALSE or #| eval: false prevents code from being run
  • No results is displayed, only code

4.6 fig.height, fig.width

  • Specify dimension of plots (in inches) with fig.width and fig.height
  • Separate multiple arguments with commas.

4.7 message

  • message = FALSE or #| meassage: falseprevents messages from appearing in output

4.8 Default chunk options

  • Repeating chunk options can be painful

  • If you have echo = FALSE in every single chunk, how to set the default chunk option to echo = FALSE ?

  • Use knitr::opts_chunk$set(echo = FALSE)

  • You may overwrite the default for each chunk

  • For chunk options, check out https://yihui.name/knitr/options/

4.9 Including tables

# cars is a built-in-to-R data set of cars and their stopping distances
cars %>%
  head(4) %>%
  knitr::kable(format = "html", caption = "A kable table")
A kable table
speed dist
4 2
4 10
7 4
7 22
  • The kable package is often used with the kableExtra package
  • A number of other packages are available for making pretty tables, by far my favourite is gt using similar approach to table that ggplot has to figures

4.10 R Markdown Reference Guide

https://rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf

5 YAML: Yet Another Markup Language

qmd/Rmd
YAML frontmatter
Markdown content
Code chunks

5.1 YAML in brief

  • Contains the metadata of the document

  • Starts and ends by three dashes

  • Comes first in the document

5.2 Simplest example

5.3 Knit

5.4 Output formats

5.5 Appearance and style

Rmd

  • In HTML output, you can use theme or a custom .css style sheet

  • theme options (bootswatch.com) : “cerulean”, “journal”, “flatly”, “darkly”, “readable”, “spacelab”, “united”, “cosmo”, “lumen”, “paper”, “sandstone”, “simplex”, “yeti”

  • You may also use LaTeX templates with R Markdown, and write reproducible scientific paper

qmd

  • this is were Quarto is leaps beyong R markdown

  • excellent doc on the website

6 Managing bibliography

6.1 Reference file

  1. Put references in a plain text file with the extension .bib, in BibTex format (my advice: use Zotero and betterbibtex extension for dynamic file)
*@article{Shea2014,
  author =        {Shea, Nicholas and Boldt, Annika},
  journal =       {Trends in Cognitive Sciences},
  pages =         {186--193},
  title =         {{Supra-personal cognitive control}},
  volume =        {18},
  year =          {2014},
  doi =           {10.1016/j.tics.2014.01.006},
}
  1. Reference this file in your YAML header and add a csl style for formatting (browse through and download styles at zotero.org/styles)
---
title: "Citation test"
output: html_document
bibliography: example.bib
csl: my-style.csl 
---

6.2 Citations

  1. In your text, citations go inside brackets and separated by semicolons

This…

Blah blah (Shea2014?, Lottridge2012?).

turns into this…

Blah blah (Shea et al. 2014; Lottridge et al. 2012).

6.3 Citations

  1. In your text, citations go inside brackets and separated by semicolons

This…

Blah blah (Shea2014?, Lottridge2012?).

(Shea2014?) says blah.

Blah blah (see Shea2014?, also Wu2016?, ch. 1).

turns into this…

Blah blah (Shea et al. 2014; Lottridge et al. 2012).

Shea et al. (2014) says blah.

Blah blah (see Shea et al. 2014, 33–35; also Wu 2016, ch. 1).

6.4 Citations

For an easy way to insert citations, try the citr RStudio add-in.

If you are using Zotero, then RStudio can link directly for both Rmd and qmd files (same for VScode)

7 Notebook vs console in Rstudio

7.1 Notebook and console

In Rstudio, Rmarkdown file = notebook

Meaning that R output:

  • are embedded in doc
  • not available in R envir and console

If you don’t like the notebook and want the console, add to YAML header

editor_options:
  chunk_output_type: console

7.2 Notebook

7.3 Console

7.4 R Markdown Reference Guide

https://rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf

8 What else can we do with R Markdown/ Quarto?

8.1 Let’s have a tour

8.2 To go further

Most of what works for R markdown works for Quarto

R Markdown cookbook


R Markdown Guide


Quarto website

9 Happy coding

I borrowed slides from Garrett Grolemund, Ulrik Lyngs, Olivier Gimenez . I also used the beautiful illustrations shared by Allison Horst