Quarto documents in RStudio

Creating your first reproducible document

Author

Affiliation

Dr. Irene Vrbik

University of British Columbia Okanagan

Outline

• Today we will be going through a demo on how to create a reproducible quarto document in RStudio.
• I will record the lecture so that you may rewatch/return to it when completing your assignments.
• If you do not have a laptop to bring do class, I still encourage you to attend, follow along, and ask questions.

What you’ll need

Download and install the latest release of R	🔗 Download R
Download and install the latest release of RStudio	🔗 Download RStudio
Download and install the latest release of Quarto	🔗 Download Quarto

Introduction to Quarto and Reproducibility

What is Quarto?

• Quarto is an open-source scientific and technical publishing system.
• It extends R Markdown to support:
  • Multi-language reporting (e.g., R, Python, Julia).
  • Enhanced project workflows.
  • Publishing to diverse formats (HTML, PDF, Word, presentations).

Why Reproducibility Matters

Reproducibility here refers to the ability to:

1. Generate consistent outputs from the same code,
2. Allow others to replicate the exact results, and
3. Ensure the integrity of your analysis when sharing or revisiting your work.

Benefits of reproducible documentation:

• Ensures transparency: Results can be verified by others.
• Promotes consistency: Avoids errors in manual recalculations.
• Critical in:
  • Academic research.
  • Industry reports.
  • Collaborative projects.

In STAT 205 I will be expecting that your assignments be created in Quarto and that you submit a rendered HTML file to Canvas (see my example on Canvas).

Setting Seeds

In an example below, there is a code chunk that relies on random numbers. You will notice that every time you render the HTML document, a new set of random numbers will appear. If you would like your document to be reproducible¹ you will need to set a seed. A “seed” refers to a starting point for the random number generator (RNG). The same seed will always produce the same sequence of random numbers, making your results predictable and reproducible. Setting a seed guarantees that the random numbers generated in your document will be the same every time someone runs it. The function for doing this in R is set.seed().

set.seed(2024)
# randomly selects a (real) number between -10 and 20
x <- runif(1, min = -10, max=20)
# randomly selects a (integer) number between 1 and 6
y <- sample(1:6, size = 1)
print(c(x,y))

[1] 15.10828  5.00000

The seed we used above is the current year, 2024. Picking the seed is somewhat arbitrary (I often just pound the keyboard randomly or sample a number from 1 to a million² but you should try to avoid reusing the same seed over and over. Now every time we render the HTML document or someone else runs the same code, x will be 15.1082762 and y will be 5. So, if you copy and paste this code into your quarto document, you should get the identical numbers. Note that changing the seed value will result in a different pair of numbers (but we should still get the same ones each time).

Quarto Documents

There are a number tools that support quarto (e.g. VS code, Jupyter), but we will be using RStudio.

Navigating RStudio

Navigating RStudio involves moving between different panes, tabs, and tools within the IDE. Here are the key elements and actions to help you navigate RStudio:

RStudio is divided into several panels, including the Source Editor, Console, Environment, and Files. You can navigate between these panels by clicking on the corresponding tabs located at the top-left corner of the IDE.

RStudio uses tabs for open documents and other views. You can switch between open files and views by clicking on the corresponding tabs at the top of the Source Editor or other panes. Note: you can change the appearance and layout of your panels in the RStudio Preferences.

1. Source Editor:

   • The Source Editor is where you write and edit your R scripts or Markdown documents. You can navigate through your code using standard keyboard shortcuts such as arrow keys, and you can also use the mouse to click and move the cursor.

2. Console:

   • The Console is where you can interactively run R code. You can type commands directly into the console, and the output will be displayed there. You can navigate through the command history using the up and down arrow keys.

3. Environment and History:

   • The Environment pane shows the variables and their values in your R workspace. The History pane displays a history of the commands you’ve executed. Both panes are accessible from the top-right corner of RStudio.

4. File, Plots, Help and Viewer: (tabbed)

   • The Files pane, allows you to navigate through your project files and directories. You can click on files to open them in the Source Editor or use the Files pane to manage your project files.

   • The Plots pane displays plots generated by your R code.

   • The Viewer pane is used for displaying rendered content (default is an HMTL file).

Creating a Quarto Document

Quarto (qmd files) are a versatile document format that allows you to integrate narrative text, R code, and the results of code execution into a single document. In Rstudio navigate to File > New File > Quarto Document. Give your document a title select and you will get a newly create Quarto document Untitled.qmd that looks something like this:

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

This is called a YAML (which stands for “yet another markup language”). Quarto allows for different format types (e.g. HTML, PDF, or word document). For this course we will be sticking with HTML. The example belown demonstrates how you can edit the YAML to include a table of contents (toc) YAML below highlights a few of the options available for HTML output.

---
title: "My document"
subtitle: "Demo for STAT 205"
date: today
format:
  html:
    toc: true
    html-math-method: mathjax
---

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

Editor mode

By default this is will open in Visual editor mode. This is a user-friend visual interface that will feel similar to writing in something like Word or Google docs in that we have options clickable buttons Bold (or keyboard shortcut (⌘B)), Italicize (or keyboard shortcut (⌘I)), add bulleted lists, etc.

Alternatively, if you move into Source editor mode, you will have a text-based editor and loose those buttons. This mode will require knowledge of the Markdown syntax.

Markdown Syntax

see cheatsheet here: https://www.markdownguide.org/cheat-sheet/) or in RStudio Help > Markdown Quick Reference. Here are some common elements:

Element	Markdown Syntax
Heading	# H1 (level 1 header) ## H2 (level 2 header) ### H3 (level 3 header)
Bold	**bold text**
Italic	*italicized text* or_italicized text_
Blockquote	> blockquote
Ordered List	1. First item2. Second item3. Third item
Unordered List	- First item- Second item- Third item
Code	`code`
Horizontal Rule	---
Link	[title](https://www.example.com)
Image	

Note

I find both modes useful and find myself switching between the two.

Now you can begin writing text and format with Markdown syntax or the RStudio Visual Markdown Editor.

Embedding content

Embed Code

You can add R codes chunks in the Source Editor by using three backticks followed by the language name (in this case, {r} for R). End the code chunk with three more backticks.

```{r}
# your code goes here
```

Tip

You can quickly insert chunks into your R Markdown file with the keyboard shortcut Cmd + Option + I (Windows Ctrl + Alt + I) or by clicking the button.

Here is an example of a simple R chunk:

head(iris)

  Sepal.Length Sepal.Width Petal.Length Petal.Width Species
1          5.1         3.5          1.4         0.2  setosa
2          4.9         3.0          1.4         0.2  setosa
3          4.7         3.2          1.3         0.2  setosa
4          4.6         3.1          1.5         0.2  setosa
5          5.0         3.6          1.4         0.2  setosa
6          5.4         3.9          1.7         0.4  setosa

Chunk options

There are a variety of code chunk options; see more here: RStudio lesson and Yihui’s website. I have summarized the ones I most commonly use below:

code chunk options

Option	Description
echo	Whether to display the source code in the output document. Besides TRUE/FALSE, which shows/hides the source code, we can also use a numeric vector to choose which R expression(s) to echo in a chunk, e.g., echo = 2:3 means to echo only the 2nd and 3rd expressions, and echo = -4 means to exclude the 4th expression.
eval	Whether to evaluate the code chunk. It can also be a numeric vector to choose which R expression(s) to evaluate, e.g., eval = c(1, 3, 4) will evaluate the first, third, and fourth expressions, and eval = -(4:5) will evaluate all expressions except the fourth and fifth.
include	Whether to include the chunk output in the output document. If FALSE, nothing will be written into the output document, but the code is still evaluated and plot files are generated if there are any plots in the chunk, so you can manually insert figures later.
label	used to assign a label or identifier to the code chunk
fig-width	Used to control the width of figures (plots, images, etc.) generated by code chunks. This (coupled with fig.height) allows you to adjust the size of the figures in your document.
fig-height	Used to control the height of figures (plots, images, etc.) generated by code chunks. This (coupled with fig.height) allows you to adjust the size of the figures in your document.
fig-cap	A character string to be used as a figure caption.
out-width	used to control the width of output figures, such as plots or images, generated by code chunks. This option allows you to adjust the display width of the figures in your document.
warning	Specifies whether the warning messages generated during the execution of the code chunk should be displayed in the document output.
message	Whether the messages produced by the code chunk are displayed in the document output (e.g. helpful to suppress verbose package libraries)

Here is a simple example:

```{r}
#| echo: false
#| label: iris-scatterplot
#| fig-cap: "A simple scatter plot of the iris data set."

plot(iris[,1:2])
```

which gets rendered to (notice how the source code is hidden):

A simple scatter plot of the iris data set.

Inline code

In Quarto, you can use the inline code syntax to embed code within the text of your document. The syntax for inline code, is to enclose within the expression . For instance

The mean of Sepal length of in the `iris` data is: `r mean(iris$Sepal.Length)`

renders to: The mean of Sepal length of in the iris data is: 5.8433333.

Tables

You can create tables in your Quarto document very easily in the Visual editor. Simply navigate to the Editor panel and select the Table < Insert Table. Fill in the desired rows and columns (along with optional caption) in the pop-up window.

Table caption: This is the default table alignment.

Col1	Col2	Col3
one	2	3
four	5	6
7	eight	nine

Use Visual Mode when making tables

While you can create tables in the Source mode using Markdown syntax, I find the Visual mode to be much easier to work with.

To align the cells in a different way right click on the table and select the appropriate choice from the Align column menu.

Table caption: We have right-aligned Col1, kept the default (left-alignment) for Col2, and centered the cells of Col3.

Col1	Col2	Col3
one	2	3
four	5	6
7	eight	nine

Latex Equations

Quarto supports the use of LaTeX equations. Equations must be writing in “math mode”. In Quarto documents, you enter matho mode with an opening and closing dollar sign $ (used for in-line equations), or by opening and closing with two dollar signs the $$...$$. The later will display the centered mathematical equation on it’s own line.

For example $x + y = z$ renders to \(x + y = z\). And $$x + y = z$$ renders to \[x + y = z\]

Notably, you can using inline R code within latex equations. For instance, let’s assign some random numbers to \(x\) and \(y\).

# randomly selects a (real) number between -10 and 20
x <- runif(1, min = -10, max=20)
# randomly selects a (integer) number between 1 and 6
y <- sample(1:6, size = 1)

Based on the random numbers above what is \(x + y\) = ?

**Answer**: $`r x` + `r y` = `r x+y`$

which renders to:

Answer: \(10.4108998 + 4 = 14.4108998\)

Format and rounding

If you don’t want to keep all of the decimal places, you can round the numbers using round() or utilize the format() function. For example

$`r round(x,2)` + `r y` = `r round(x+y, 2)`$

renders to: \(10.41 + 4 = 14.41\)

Understanding Paths in Quarto

In Quarto documents, paths are used to reference files (e.g., datasets, images, scripts) relative to the location of your .qmd file or project structure. Proper path management is crucial for making your document portable, reproducible, and organized.

There are two types of Paths in Quarto:

1. Relative paths (Recommended for reproducibility) Relative paths reference files based on the location of your .qmd document. Example structure:

   my-project/
   ├── my-document.qmd
   ├── data/
   │   └── dataset.csv
   └── images/
       └── plot.png

   In your .qmd file, you might have something like:

   # Read a CSV from the 'data' folder
   dataset <- read.csv("data/dataset.csv")
   
   # Display an image from the 'images' folder
   knitr::include_graphics("images/plot.png")

   Important

   Important Note: Quarto uses the directory where the .qmd is located as the working directory by default. So there is no need to use setwd() as you would have done with an R script.

2. Absolute Paths (Not Recommended) Absolute paths reference files using their full path on your computer. Example:

   # breaks when shared
   dataset <- read.csv("C:/Users/YourName/Documents/data/dataset.csv")

   Notice how this method is tied to your system, so they break if the document is moved or shared (i.e. they are not portable). For this reason using relative paths (which is easily portable between machines) is the recommended workflow.

Organizing Files in Quarto Projects

To maintain a clean and reproducible structure, organize your project files consistently:

stat205/
├── assignments/
│   ├── assignment1-studentID.qmd
│   ├── assignment2-studentID.qmd
│   ├── data/
│   │   ├── dataset1.csv
│   │   └── dataset2.csv
│   ├── figures/
│   │   ├── figure1.png
│   │   └── figure2.png
├── notes/
│   ├── lecture1.qmd
│   ├── lecture2.qmd
│   └── resources/
│       ├── reference1.pdf
│       └── reference2.pdf

Rendering Documents

Use the render button ( Render) located in the Source Editor panel or the or use the keyboard shortcut (⇧⌘K).

Tip

I like to click the “Render on Save” (located to the left of the ( Render) button, so that my document automatically render whenever I save the file (which is constantly).

In addition to rendering the complete document to view the results of code chunks, you can also run each code chunk interactively in the RStudio editor by clicking the icon or keyboard shortcut (⇧⌘⏎). RStudio executes the code and displays the results either inline within your file or in the Console, depending on your preference

Navigating through long files

In RStudio, the “Outline” pane in the top provides a convenient way to to view the document’s structure, navigate between sections, and quickly jump to different parts of the document. If the “Outline” pane is not visible, you can open it by going to the top-right corner of the Source Editor pane (this button looks like a small document icon with lines) or by using the keyboard shortcut Ctrl + Shift + O (Windows/Linux) or Cmd + Shift + O (Mac).

In addition, you can quickly navigate to different sections and code chunks using the “Chunk Navigation” feature. This feature is available as a clickable navigation menu located at the bottom-left corn of your Source Editor.

Workflow

1. Open a new .Rmd file in the RStudio IDE by going to File > New File > R Markdown.

2. Embed code in chunks. Run code by line, by chunk, or all at once.

3. Write text and add tables, figures, images, and citations. Format with Markdown syntax or the RStudio Visual Markdown Editor.

4. Set output format(s) and options in the YAML header. Customize themes or add parameters to execute or add interactivity with Shiny.

5. Save and render the whole document. Knit periodically to preview your work as you write.

6. Share your work!

Resources

1. Tutorial: Hello, Quarto: https://rstudio.github.io/cheatsheets/html/quarto.html#overview

2. Get started with Quarto | Mine Çetinkaya-Rundel Posit PBC YouTube Channel https://www.youtube.com/watch?v=_f3latmOhew&t=711s

3. Quarto Cheatsheet: https://rstudio.github.io/cheatsheets/html/quarto.html

4. RMarkdown cheatsheet: https://rstudio.github.io/cheatsheets/html/rmarkdown.html

5. Markdown cheatsheet: https://www.markdownguide.org/cheat-sheet/

6. Markdown basics: https://quarto.org/docs/authoring/markdown-basics.html

7. Code chunk options: https://rmarkdown.rstudio.com/lesson-3.html, https://yihui.org/knitr/options/

Footnotes

1. Reproducibility in this context means that the output of the code in your document will be identical every time the document is rendered, regardless of when or where it is run

2. I use sample(1000000,1) to sample 1 random number from 1 to a million.