Reproducibility 2: Introduction to Quarto

reproducibility
quarto
Author

Horacio Lopez-Nicora

Published

October 21, 2024

1 Introduction

Quarto is an open-source scientific and technical publishing system supporting multiple programming languages. It allows seamless integration of code, outputs, and narrative in a single document.

Quarto documents include all code and data analysis steps, which improves understanding and reproducibility for readers. Reproducibility ensures that analyses can be independently verified, enhancing credibility and transparency.

Artwork by @allison_horst
Note
  1. Why Choose Quarto?
    • Consistent document creation for reports, articles, and documentation.
    • Supports multi-format outputs like HTML, PDF, Markdown, etc.
    • Facilitates collaborative analysis through version control systems.
  2. Applications of Reproducibility:
    • Essential in academic research for replicating experiments.
    • Useful in data science for maintaining project integrity across teams.

2 Creating a Quarto Document

Quarto (.qmd files) is a versatile document format that enables the integration of narrative text, R code, and the results of code execution into a single document. In RStudio, navigate to File > New File > Quarto Document to create a new document.

Initially, this document will be titled Untitled.qmd. Let’s rename it to something more recognizable for future reference. To do so, go to File > Save As, place this new Quarto document alongside your other course materials, and give it a meaningful name.

2.1 Practice

  1. Start a new R Project.
  2. Within your R Project, create a new Quarto document and save it.

3 Rendering your Quarto document

Once you create and save your Quarto document (.qmd), open it in RStudio, and click on Render.

To render the file and preview the output quickly in the RStudio IDE, simply click the Render button or use the keyboard shortcut (⇧⌘K).

If you prefer to have the file render automatically every time you save, you can enable the “Render on Save” option located on the editor toolbar. This ensures the preview updates each time you re-render the document. The side-by-side preview feature supports both HTML and PDF outputs.

Additionally, more options can be discovered by clicking the gear icon next to the Render button.

3.1 How does it works

When you render a Quarto document, the process begins with knitr executing all the code chunks and generating a new markdown (.md) document that includes both the code and its output. This Markdown file is then processed by Pandoc, which creates the final, polished format. The Render button automates and organizes these steps, executing them in the correct sequence for you.

During the rendering process, Quarto creates a new file that includes the selected text, code, and results from the .qmd file. This new file can be formatted as an HTML, PDF, MS Word document, presentation, website, book, interactive document, or other formats.

3.2 Practice

  1. Render your Quarto document.
  2. Use the gear icon to select your preferred preview option, such as displaying it in the viewer panel or opening it in a new window, after rendering.

4 Components of a Quarto document

There are 3 main parts of a Quarto document:

  1. The YAML (rhymes with camel) header
  2. Text
  3. Code

4.1 YAML Header

The YAML (Yet Another Markdown Language, or YAML Ain’t Markup Language) is located at the top of your document and is enclosed by “—” lines.

YAML is where you can set the content that will appear at the beginning of your compiled document. For instance:

  • title: “Your title here” (make sure it is enclosed in quotes)
  • author: “The author’s name” (again, in quotes)
  • date: The date you want to display at the top of your document, enclosed in quotes. If you wish to learn more about other options, see https://quarto.org/docs/reference/dates.html.
  • output: Specifies the format of the compiled document. For this class, I recommend using html_document, as it offers the richest format. Your output will be a .html file, which you can save or share.

Here’s a simple example:

---
title: "This is my descriptive title"
author: "Horacio Lopez-Nicora"
date: "October 21, 2024"
format: html
editor: visual 
---

Quarto supports various format types, such as HTML, PDF, and Word documents. In this course, we will focus exclusively on HTML. The example below demonstrates how you can modify the YAML to include a table of contents (toc). The YAML provided below highlights several options available for HTML output.

---
title: "This is my descriptive title"
author: "Horacio Lopez-Nicora"
date: today
date-format: long
format:
  html:
    toc: true
---

A full list of HTML format options can be found at the HTML Options page on the quarto website.

4.2 Text

By default, a Quarto document opens in Visual Editor mode. This user-friendly visual interface resembles writing in programs like Word or Google Docs, offering options for clickable buttons such as Bold (or keyboard shortcut ⌘B), Italicize (or keyboard shortcut ⌘I), and adding bulleted lists, among others.

Alternatively, switching to Source Editor mode provides a text-based editor where these buttons are not available. In this mode, familiarity with Markdown syntax is necessary.

Tip

Markdown Syntax: see cheatsheet here:https://www.markdownguide.org/cheat-sheet/) or in RStudio Help > Markdown Quick Reference.

4.3 Code

Code chunks are sections of your Quarto document designated for executing code. To insert a new code chunk, you can:

  1. Use the keyboard shortcut Cmd + Option + I (Mac) or Ctrl + Alt + I (Windows).
  2. Type ```{r} to start the chunk and ``` to end it, placing your code in between.
  3. Use the “Add Chunk” command from the editor toolbar and select R.

Code chunks appear as follows:

You place your code on the empty line within the chunk. You can include multiple lines of code in a single chunk; however, if you find yourself needing to scroll through the chunk, it might be too lengthy.

  • The gear icon allows you to modify chunk options, which we will discuss in more detail later.
  • The triangle with a line below it executes all code chunks that precede the current one.
  • The play button runs the current chunk.

You can also include comments within a code chunk by using the # symbol to comment them out.

# A very interesting comment
Super_Code()
Warning

When you render your Quarto document, the process will execute all the code within it. This means that if your code contains errors or doesn’t function properly, your document will not be rendered.

In Quarto, you can use inline code to embed code directly within your document’s text. To apply this syntax, simply enclose the expression in backticks. For example:

The sum of 6 and 6 is 12. In this case, 12 was generated with the following inline code `r 6+6`.

4.3.1 Enhancing Your Code Chunks with Options

You can enhance your code chunks by adding options using #|. This provides R with further instructions on executing your code and compiling your document. HERE are some common examples.

{r}
#| eval: FALSE
#| echo: TRUE
#| code-fold: TRUE

6 + 6

This occurs after the code chunk is rendered.

Code 
6 + 6

4.4 Practice

Now, let’s edit our Quarto document.

  1. In your Quarto document’s YAML section, include a subtitle and specify a date format. Additionally, enable a table of contents for improved navigation.
  2. Make use of the Visual editor to draft text. Regularly switch between the visual and source editors to familiarize yourself with RMarkdown.
  3. Integrate code chunks while configuring them with the following options: execute the code but hide the code itself in the output.
Back to top