Who am I?

What to expect during this workshop

• Combines slides, live coding examples, and exercises for you to participate in.

• Ask questions throughout!

What to expect during this workshop

Workshop resources

Course website: nrennie.rbind.io/training-intro-to-quarto

What do you currently use?

How do you write your journal articles?

• Microsoft Word?
• LaTeX?
• R Markdown?

What is Quarto?

Quarto is an open-source scientific and technical publishing system that allows you to combine text, images, code, plots, and tables in a fully-reproducible document.

Quarto has support for multiple languages including R, Python, Julia, and Observable.

It also works for a range of output formats such as PDFs, HTML documents, websites, presentations,…

Why use Quarto? Why use R?

• More journals require code to be submitted (for transparency and reproducibility). Keeping the code with the paper makes this easier.

• Copying and pasting is tedious (and a great source of accidental errors).

• If you fix an error in code or data, the results and figures in the paper update automatically.

• Easy to share publicly.

• Open source so anyone can use it.

What about R Markdown?

R Markdown isn’t going anywhere but…

• Quarto has better multi-language support

• More user-friendly

• Better control of the output layouts

Creating a document

Quarto in RStudio

Rendering a document

Within RStudio IDE: click Render (or Ctrl+Shift+K)

library(quarto)
quarto_render("document.qmd")

quarto render document.qmd

What makes a Quarto document?

YAML header

---
title: "A very cool title"
format: html
---

Output types

Live Demo!

Exercise 1

• Create a new Quarto HTML document.
• Fill in the YAML options with a title and author.
• Render your document.
• Change the format to docx.
• Re-render your document.
• What about PDF?

Document content

In Quarto, you can include many things that aren’t code:

These are primarily written using Markdown syntax.

Markdown syntax

• You don’t need special software to read it.

• Separates out the content and structure from the document styling.

• Focus on the content not the way it looks.

Sections

Sections are added to a document using different numbers of #:

• # creates a Level 1 heading (section)

• ## creates a Level 2 heading (subsection)

• ### creates a Level 3 heading (sub-subsection)

• …

Lists

Lists can be created using either * or -:

* Item 1
* Item 2
* Item 3

or

- Item 1
- Item 2
- Item 3

gives:

• Item 1
• Item 2
• Item 3

Numbered lists

Works but isn’t great:

1. Item 1
2. Item 2
3. Item 3

1. Item 1
1. Item 2
1. Item 3

Links

Add a link using square brackets and round brackets:

• the text to appear in square brackets
• followed by the URL in round brackets

A link to the [Quarto documentation](https://quarto.org/).

Links

If the text to appear and the URL should be the same, you can put it inside <> instead:

… can be found at <https://quarto.org>.

Including image files

Add an image using ![](path/image.png).

Image options

Add a figure caption in the square brackets:

![Figure caption goes here](path/image.png).

Tables

You can create simple tables with Markdown syntax:

| Surname | Forename |
|---------|----------|
| Rennie  | Nicola   |
| Smith   | Jane     |
| Barclay | Rebekah  |

Tables

Tables

Table –> Insert Tables:

Tables

Writing equations with LaTeX

---
title: "A very cool title"
format: html
---

\begin{equation}
Y = \beta_0 + \beta_1 \text{age} + \beta_2 \text{education}
\end{equation}

Live Demo!

Exercise 2

• Create level 1 and level 2 section headings in your document.
• Add some text into your document. If you don’t want to write your own, there is some sample text in sample-text.qmd.
• Format the text to include a list, and bold or italic text.
• Add a link to the International Personality Item Pool: https://ipip.ori.org/.
• Include an image in your document. Find your own or use eggs.jpg.
• Add a caption to the image and center align it.
• Render your document - check the image appears and the link works.

Code blocks

• Code blocks are the main way of including executable R code in a document.

• Code blocks always start with three backticks, followed by the an r in curly brackets.

```{r}
2 + 2
```

[1] 4

Some Quarto code tips

Code block options

Code block options can control:

Code block options

```{r}
#| eval: false
#| warning: false
2 + 2
```

```{r, warning=FALSE, eval=FALSE}
2 + 2
```

knitr::convert_chunk_header("document.qmd", output = identity)

Code block options

Code visibility options:

• Hide the code

#| echo: false

• Show the code

#| echo: true

• Show the code and the YAML

#| echo: fenced

Code block options

```{r}
#| echo: fenced
#| eval: true
#| warning: false
#| error: false
#| output: asis
#| include: true
```

Predictive code block options (and YAML)

Global code block options

---
title: "A very cool title"
format: docx
execute:
  echo: false
---

```{r}
knitr::opts_chunk$set(echo = FALSE)
```

Code block options: label

Code block options: label

Let’s say we want to load some data. We can add a load-data label:

```{r}
#| label: load-data
library(psych)
data(bfi)
```

Data

We’ll be using the sat.act data from {psych} for some examples. You can also load the data directly from a CSV file:

```{r}
#| label: load-data-csv
sat.act <- read.csv("https://vincentarelbundock.github.io/Rdatasets/csv/psych/sat.act.csv")
```

See ?psych::sat.act.

Code block options: fig-

Figure options:

```{r}
#| label: age-hist
#| fig-align: center
#| fig-width: 6
#| fig-asp: 0.9
#| fig-cap: "A histogram of participant age"
#| output-location: slide
hist(sat.act$age, xlab = "Age", main = "")
```

Code block options: tbl-

There are lots of options for creating tables in R:

• {knitr} - basic
• {kableExtra} - adds to kable() in {knitr}
• {gt} - more complex “great tables”
• {gtsummary} - creates summary tables using {gt}
• {flextable} - good for Word documents
• {tinytable} - very lightweight

Code block options: tbl-

Prepare the data:

```{r}
data("sat.act")
sat_summary <- aggregate(
  cbind(SATV, SATQ) ~ education,
  FUN = mean,
  data = sat.act
)
```

Code block options: tbl-

Make a table:

```{r}
#| tbl-cap: "Mean scores by education level"
#| output-location: slide
library(tinytable)
tt(sat_summary)
```

Live Demo!

Exercise 3

• Add a code block that loads the {psych} package and a dataset from the package e.g. bfi.
  • Alternatively, use some other data that you have/like.
• Add another code block that makes a plot e.g. a bar chart of participants’ education categories, education. You can use either base R or {ggplot2} (or another package!).
• Change the code block options and see what happens!
• Add a third code block that creates a table showing the first 10 rows and first 5 columns of your data. Hint: head(bfi[, 1:5], 10). Use any table package you prefer.

Referencing results in text

We can also include code inline, rather than as a separate chunk.

This is especially useful for using results values in a paragraph of text.

Referencing results in text

For more complex numbers, you can calculate or extract results from a code block.

```{r}
# Calculate median age of females
# Males = 1, Females = 2
age_f <- median(bfi[bfi$gender == 2, "age"])
```

Figure references

Earlier we saw how to add images to Quarto documents, where image options can be added in curly brackets afterwards:

![Figure caption goes here](path/image.png){fig-align="center" width="50%"}.

Figure references

To reference the figure in the text, use an @ with the figure label:

@fig-my-image.

Cross-referencing

We can add a cross-reference to a different section of our manuscript by adding a reference label that has a sec- prefix:

## Exploratory data analysis {#sec-eda}

Cross references

To make sure that the cross reference numbers make sense, you should also switch on the numbering for the document sections:

---
title: "My Document"
number-sections: true
---

Plot references

Earlier we made a histogram of age:

```{r}
#| label: age-histogram
#| fig-align: center
#| fig-cap: "A histogram of participant age"
#| output-location: column
hist(bfi$age, xlab = "Age", main = "")
```

Plot references

To make this a Figure reference, we need to prefix the label with fig-:

```{r}
#| label: fig-age-histogram
#| fig-align: center
#| fig-cap: "A histogram of participant age"
#| output-location: column
hist(bfi$age, xlab = "Age", main = "")
```

Plot references

Then:

A histogram of participant ages is shown in @fig-age-histogram.

Table references

Table references are similar, except we prefix with tbl-:

```{r}
#| label: tbl-sat-summ
#| tbl-cap: "Mean scores by education level"
#| output-location: column
tt(sat_summary)
```

Table references

Then:

Summary statistics are shown in @tbl-sat-summ.

Citations

To add citations in Quarto, we need two things:

• A source bibliography with citation IDs

• A way to refer citations IDs in Markdown syntax

Bibliography files

• Quarto supports bibliographies in a wide variety of formats including BibTeX and CSL

• .bib files are probably most common.

• The first entry inside the curly brackets is the citation ID.

@Manual{psych,
  title = {psych: Procedures for Psychological, Psychometric, and Personality Research},
  author = {{William Revelle}},
  organization = {Northwestern University},
  address = {Evanston, Illinois},
  year = {2024},
  note = {R package version 2.4.1},
  url = {https://CRAN.R-project.org/package=psych},
}

Bibliography files

• Add a bibliography to your document using bibliography in the document YAML.

• You might also choose to link the citations to the reference list.

---
title: "Some long interesting title"
bibliography: references.bib
link-citations: true
---

Citations

To refer to a citation, use @ and the citation ID:

… as described in @psych.

which gives:

… as described in @psych.

Visual editor

Adding citations is one task where the Visual Editor in RStudio can be really helpful. It provides:

• Integration with Zotero (no set up if using desktop versions).

• Search with DOI, CrossRef, PubMed.

• It updates the .bib file for you!

Visual editor

Click Insert –> Citation:

Live Demo!

Exercise 4

• Update (or add!) a label to the figure code block you created earlier.
• Add a reference to this in the text.
• Add section references, and cross reference to this section somewhere else in the document.
• Add a citation by either:
  • creating a .bib file and listing it in the YAML.
  • using the Zotero integration

Formatting documents

Let’s assume that we’ve written a wonderful, fully-reproducible manuscript and we’re ready to submit it to our favourite journal.

Output formats

Most (but not all)journals aren’t quite ready for Quarto (.qmd) files. They accept Word documents, LaTeX files, and sometimes PDFs to start with.

---
format: docx
---

---
format:
  pdf:
    keep-tex: true
---

Formatting documents

How can you alter the styling of a Quarto document?

---
format:
  docx:
    reference-doc: apa-style.docx
---

Formatting documents

LaTeX

---
format:
  pdf:
    keep-tex: true
    template: apatemplate.tex
---

Quarto extensions

Quarto extensions are a powerful way to modify and extend the behavior of Quarto. Extensions can be used to add styling to your documents.

Journal template extensions

• Quarto extensions can be used to install templates for journal articles.

• Many templates already exist (and the list is getting longer…)

• See: quarto.org/docs/extensions/listing-journals.html

Journal template extensions

---
title: "A very cool title"
format:
  pdf: default
  jss-pdf:
    keep-tex: true 
---

---
title: "A very cool title"
format:
  pdf: default
  elsevier-pdf:
    keep-tex: true 
---

Installing Quarto extensions

• Quarto extensions can be shared in different ways.
• The most common way is via GitHub. This is where you’ll find the journal templates we looked at.
• Two options for installing from GitHub:
  • From the command line
  • Using the {quarto} R package
• Both ways download all the style files you need and put them in the right place.

Installing Quarto extensions

From the command line

To create a new document from a template:

quarto use template username/repository

To convert an existing document

quarto add username/repository

Installing Quarto extensions

Using the {quarto} R package

Version 1.4 onwards

To create a new document from a template:

quarto::quarto_use_template("username/repository")

To convert an existing document

quarto::quarto_add_extension("username/repository")

APA style manuscripts

APA Quarto extension: wjschne.github.io/apaquarto

Install: quarto::quarto_use_template("wjschne/apaquarto")

Live Demo!

Exercise 5

• Install the APA Quarto extension.
• Change the output format of your document to APA (docx, html, or pdf).
• Re-render your document. Do you get an error?
• Look at the installation instructions at wjschne.github.io/apaquarto/installation.html to see what other YAML options are added.
• Add the required information about the author (you).
• Re-render your document.

Collaborating on Quarto documents

We often work with other people when we write papers.

How do we do that effectively using Quarto?

Structuring Quarto documents

• Your .qmd files will get excessively long when you start writing (especially when you include code).

• This quickly gets annoying (especially with multiple people adding to a single document).

• There are several options for breaking them down:

  • multiple files
  • multiple files in a project

Multiple Quarto files

You can use {{< include doc.qmd >}} to include one Quarto document in another.

---
title: "My manuscript"
---

## Introduction

{{< include intro.qmd >}}

## Exploratory data analysis

{{< include analysis.qmd >}}

Quarto projects: Manuscript

Multiple authors: GitHub

Multiple authors: GitHub

Why use GitHub?

• Easily roll back to previous versions.

• History of who added what.

• Add comments and suggestions via pull requests. Ask for a review.

• Can render your documents for you.

Multiple authors: {trackdown}

See claudiozandonella.github.io/trackdown.

Multiple authors: it’s a known problem

GitHub discussion: github.com/quarto-dev/quarto-cli/discussions/405

Tricky things: managing versions

When collaborating with other people, it’s useful (sometimes crucial) that you all have:

• the same R package versions ({renv} can help with this)
• the same Quarto versions (harder to manage)
• the same LaTeX versions (harder to manage)

Tricky things: long computations

Problem: you have R code that takes a long time to run, and you don’t want to re-run it every time you re-render the document.

Tricky things: long computations

Problem: you have R code that takes a long time to run, and you don’t want to re-run it every time you re-render the document.

Solutions:

• {targets}: a Make-like pipeline tool for statistics and data science in R
  • skips costly runtime for tasks that are already up to date
  • run computations upstream before the .qmd document
  • the .qmd is the final “target”

Nice features: shortcodes

Nice features: diagrams

```{dot}
graph G {
  qmd -- Knitr;
  qmd -- Jupyter;
  Knitr -- md;
  Jupyter -- md;
  md -- pandoc;
  pandoc -- HTML;
  pandoc -- PDF;
  pandoc -- Word;
  pandoc -- more;
}
```

Nice features: diagrams

Examples

• www.mm218.dev/papers/shrubland_pub_2022.pdf

• arxiv.org/pdf/2303.04758

  • Source: github.com/gesistsa/rang/tree/paper/paper

• arxiv.org/pdf/2303.07334

  • Source: github.com/cafri-labs/assessing-spatial-cv
  • Uses {targets}

Open discussion

• Would you use Quarto to write a manuscript?

• What things seem difficult or less nice than what you currently use?

• Is there anything that didn’t work the way you expected?

• Questions?

Workshop resources

Course website: nrennie.rbind.io/training-intro-to-quarto

Additional resources

• Documentation: quarto.org

• GitHub Discussions: github.com/quarto-dev/quarto-cli/discussions

• Intro Webinar: jthomasmock.github.io/quarto-2hr-webinar

• Awesome Quarto List: github.com/mcanouil/awesome-quarto

• Zotero Connector (for source editor): github.com/paleolimbot/rbbt