Working in Quarto

Integrating code and text

The classic way of working in R is to write your code in a script file. This is still a very common way of working, and it has many advantages. But today there are also great alternatives, that make it possible to integrate your code directly in your reporting.

In fact, the book that you are currently reading is written in one such alternatives, called Quarto. Quarto is a literate programming tool, which means that it allows you to write your code and your text in the same document. Any results and visualizations that you generate in your code can also be directly included in the output document. This is not only convenient, but also makes your analysis more transparent and reproducible. If you ever need to update your analysis, you can just rerun the code and the document will automatically update, including any tables, figures and statistial results that you generated.

And despite all those features, it really isn’t that different from writing an R script. In some ways it is even a more convenient way of working.

In some courses in this program, you will be asked to write your assignments in Quarto. This section therefore provides a brief introduction to working in Quarto.

Creating a Quarto file

You can create and work with Quarto directly in RStudio. For assignments, you will often be given a template Quarto file, but here we’ll create one from scratch. To create a new Quarto file in RStudio, go to the menu bar and select File > New File > Quarto document.

You’ll get a menu where you can select some options, such as whether you want the output to be created in HTML, PDF or Word. We’ll stick with the default HTML, because this doesn’t require any additional software to be installed. For now, the only thing you should change is the Title. Just name it something like My First Quarto Document, and click Create.

The new file will open in the editor, and you’ll see that it already contains some text and code, that also doubles as a quick tutorial. Roughly speaking, there are three general components.

1. The Header

At the top of the file there is a header, which is enclosed by three dashes ---. Here you can specify some general settings for the document, such as the title, the author, and the output format. The default is:

---
title: "My First Quarto Document"
format: html
editor: visual
---

This means that the title of the document is “My First Quarto Document”, the output format is HTML, and the editor is the visual editor. You can add many more options to the header, but for now we’ll stick with the basics.

The Quarto editor can be source or visual. In visual mode, everything looks a bit more pretty. It doesn’t yet look as pretty as when you render the document (which we’ll show you in a bit), but it’s a bit easier to read. Also, in the toolbar you get some buttons to make text bold or italics, add codeblocks, insert images, create tables, etc.

In source mode, everything is just in plain text. Behind the scenes, Quarto uses a format called Markdown to format the text. Markdown is a type of markup language (like HTML). What this means is that any formatting that you do (e.g., bold, tables, lists) is done by writing the text in a specific way. For example, to make a word bold, you write it between two asterisks **like this**.

Working in source mode can be convenient if you’re already familiar with Markdown. If not, we recommend sticking with visual mode for now, and maybe forever.

2. The textual content

After the header, you can start writing your text. This works like a light version of Word. You can add heading, lists, tables, images, and more.

3. The code chunks

At some point you see a code chunk, which looks like:

{r}
1 + 1

Inside these code chunks you can write R code. When you render the document, the code will be executed, and the output will be shown in the document.

While working on the document you can also run the code chunks separately (i.e. without rendering). You can do this like you would do in an R script, by selectin the code you want to run and hitting Run (or Ctrl/Cmd + Enter). But there is also a convenient option to run the entire code chunk at once by clicking on the run current chunk button in the top right of the code chunk. Here you also find a button to run all the chunks above the current one.

To add a new block, you can click on the Insert button in the toolbar, and select Executable Cell -> R.

Rendering the document

When you’re done writing your document, or if you want to see a preview, you can render the document by clicking the Render button in the toolbar (or hitting Ctrl/Cmd + Shift + K). Try it now! If you did not yet save your Quarto file, R will first ask you to save it. You should then give it a name with the .qmd (Quarto Markdown) extension, for example my-first-quarto-document.qmd. This should produce an HTML file that opens in your browser (unless you changed something and broke it).

There is one big challenge when working with Quarto, which is also a blessing in disguise. If there is ANY error in your code, the entire document will not render. This can be frustrating, especially if you need to hand in an assignment in a few minutes. So whenever you’re working with Quarty, make sure to frequently render your document while you’re working on it, to catch any errors early on. It is much easier to trace back an error if you only made a few changes since the last time you rendered the document. If you only render the document at the end, you might have to go through the entire document to find the error. (though the error messages will tell you where to look)

So why is this a blessing in disguise? It forces you to write your code in a way that is clean and well-structured. When working in an R script, a common mistake to make is that some pieces of code depend on code that is further down in the script. For example, if you use a certain column on line 10, but you only create that column on line 20. This might not pose a problem while you’re working on it, but it will bite you when for whatever reason you need to rerun the entire script. Quarto forces you to write your code in a way that if you run the entire script from scratch, it will work.

Some tips and warnings

Turn on 'Render on save'

In the toolbar you can turn on Render on Save. This way, any time you save the document, it will try to render. Now make sure to save often (get used to using Ctrl/Cmd + s). This way you can catch any rendering errors early on.

The working directory is the folder where the Quarto file is located

A Quarto file will always use it’s own location as the working directory This is actually quite convenient. Just make sure to put your Quarto file in the same directory as your data, and you’re good to go.

Use code block parameters

You can add parameters to the code chunks. For example, the following code chunk will only show the code, but not the output:

{r, results=FALSE}
1 + 1

Following this same notation, you can set the following parameters:

  • {r, results=F}: show the code, but not the output
  • {r, eval=F}: show the code, but do not run it
  • {r, echo=F}: do not show the code, but show the output
  • {r, message=F}: do not show any messages that are generated by the code. This can for instance hide the message that is printed when you run library(tidyverse).
  • {r, warning=F}: do not show any warnings that are generated by the code. This is more dangerous than hiding messages, but if you are sure that the warning is harmless, you can use this to make the document cleaner.
  • {r, message=F, warning=F}: separate multiple parameters with a comma.
  • {r, cache=T}: cache the output. This way, if you render the document again, but the code chunk did not change, it will not rerun the code. If you have any code that takes a long time to run, this allows you to still render the document quickly (which is especially useful if you have Render on Save turned on). Just make sure to turn cache of before rendering the final version, to be sure that everything is up to date.
Back to top