RMarkdown and Quarto – the basics

This work is licensed under a Creative Commons Attribution 4.0 International License.

Please contact indrek.seppo@gmail.com for source code or missing datasets.

Introduction

I am going to give you an overview of RMarkdown and its next generation – Quarto. Why take a look at both if I said that Quarto is the next generation? Because Quarto is so new that I have noticed that RStudio has some stupid bugs related to some of the beginner-friendly functionality.

We will go through the basics in traditional RMarkdown and then move on to see what are the main differences in Quarto. Do not worry, the differences are minuscule.

So why do we need rmarkdown/quarto at all? What is the promise?

RMarkdown and Quarto serve several key purposes:

• Reproducibility: By combining code, data, and text, they enable anyone to reproduce and understand your analyses.
• Consistency: They ensure reports maintain a standard look, eliminating the need for manual formatting.
• Automation: They allow automatic report generation, ideal for producing periodic reports based on updated data.
• Collaboration: Being text-based, these files can be easily shared and version-controlled, facilitating collaborative work.

You will be more efficient using them. Sometimes the data changes, no problem – you just run the code again and you have all the illustartions, tables and numbers updated in 20 seconds. Sometimes you want to make multiple reports that have same structure (or you do monthly reports etc) – very well – you just create one template and run it with different data.

Prerequisites

We will need (preferably the latest versions of) R, RStudio and Quarto. These can be downloaded from:

• R for Windows: https://cran.r-project.org/bin/windows/base/
• R for OS X https://cran.r-project.org/bin/macosx/
• RStudio for Windows, OS X and Linux: https://posit.co/download/rstudio-desktop/
• Quarto for Windows, OS X and Linux: https://quarto.org/docs/download/

All of these are free to use and open source.

In addition to that we need LaTeX environment for full experience (to generate pdfs). For this please run this in your RStudio:

install.packages("tinytex")
tinytex::install_tinytex()

Creating a project and downloading data

It is always advisable to create a new project if you start working on a new topic in RStudio. So lets create it: File -> New Project -> New Directory -> New Project. Now set the name of the project and Create project. This creates a new directory into your filesystem, where all the project related files will be, from where R searches for files to load and to where it saves the results.

Lets now download some play-data into this folder. Create a new R script, read the data into R and then save it like this:

library(tidyverse)
piaac <- read_csv("http://www.ut.ee/~iseppo/piaacENG.csv")
write_csv(piaac, "piaac.csv")

You should now see in the files pane, that you have a new file in this directory called piaac.csv. The data itself is not so important right now, but it comes from Programme for the International Assessment of Adult Competencies (PIAAC) run by OECD – it measures adults numeracy and literacy skills and has a lot of additional data about everyone in the sample. The nice thing about it is that it is freely available. I have only included some variables here, and this particular data comes from Estonia (there are many more countries in the dataset). It is a bit outdated, but the new wave is running right now and we do not have this data yet.

RMarkdown

The basics of markdown

RMarkdown is a tool for integrating R code, text, and output into one document. It uses Markdown syntax for text formatting, and R code chunks that can be run to produce results and graphs in the same document.

Markdown is a lightweight document language, which can be translated to different types of outputs – html, pdf, doc etc¹. While there is no single markdown standard, it is pretty similar in wherever you encounter it, it is by no way R-specific.

Let’s create our first RMarkdown document: File -> New File -> RMarkdown. Give it a title, author and a date and create it.

Here are some basic Markdown syntax:

• Headers: You use the # sign. One # for the main header, ## for subheader, ### for sub-subheader, etc.
• Bold: Enclose text with two asterisks or underscores, like **bold** or __bold__.
• Italic: Enclose text with one asterisk or underscore, like *italic* or _italic_.
• Lists: Use -, +, or * to create an unordered list, and numbers to create an ordered list.
• Links: Use [] for the clickable text and () for the URL. [Google](https://www.google.com/)
• Images: Similar to links but with an ! at the front. ![Alt text](URL)
• Footnotes: use ^[Footnote text.].

You need to remember to add two linebreaks (so creating one empty line) to actually end a paragraph, start a list etc.

After you have added some content, click Knit on the top toolbar. It will show you the document in new window. If you want it to be sown in Viewer pane on the right, then click on a gear next to the Knit button and select Preview in Viewer Pane.

Adding R code

To include an R codechunk you can click on the greenish “c” on the toolbar and choose R from there. Note that you can also include Python, D3, SQL and other code chunkcs. Lets try and add a new code chunk.

First lets load the libraries and the data:

library(tidyverse)

piaac <- read_csv("piaac.csv")

And knit it.

You will see that both the code and the output is included in the document. Do you want it? Probably not (in some rarer cases – like when preparing study materials – you do). To control what is going to be shown you can click on the gear on the top right corner of the code chunk. A chunk options menu opens. From there you can select wether warnings and messages will be shown (in final document you probably do not want it), and from the dropdown whether it should show output only, code and output, nothing (but the code will be run) or that it should not run the code at all. You can also name the code chunk (good for debugging later on!).

Chunk options

Let’s try them – remove the warnings and messages from our code chunks and make it run, and don’t show anything.

Notice that the header of the code chunk changes, it now says echo = FALSE etc. So you can write this yourself aswell.

What if you want all the chunks to not be visible by default? You can put the following chunk in the beginning of your code:

knitr::opts_chunk$set(
    message = FALSE,
    warning = FALSE
    )

Let`s do some basic calculations and add it to the text.

mean_wage <- mean(piaac$Income, na.rm = TRUE)

For inline code, use single backticks and start the line with r, let’s try it:

The average wage was `r mean_wage`.

Ok, you probably want to round it. You can write any R code in the inline code chunk as well:

The average wage was`r round(mean_wage, -1)` 

You can add tables using knitr::kable(). For example:

piaac %>%
  group_by(Education) %>%
  summarize(wage = mean(Income, na.rm = TRUE)) %>%
  knitr::kable()

Education	wage
Basic	869.7741
Higher	1014.8716
Secondary	790.9698

Or you can add images. Let’s see how our mathematical abilities change over the age.

piaac %>%
  ggplot(aes(x = age, Numeracy)) +
  geom_smooth()

Oh dear! No good news here. You can add captions, change the size etc of the pictures in the header of the code chunk.

```{r fig.cap="The relationship of age and numeracy", fig.height=3}

And this is pretty much what you need to know about RMarkdown. You can do a lot with this knowledge. You can create nice looking html or pdf reports, you can create dashboards.

To create a pdf from this you need to click on the tiny triangle next to the knit button and select knit to pdf. Or you can create a docx file. Note that running the knit to pdf first time might take a bit of time – the LaTeX engine needs to download necessary addons.

There are a number of packages providing different templates. I recommend you to check out rticles if you are from academy. tufte (and tint, a slightly altered version of tufte) for nice looking reports, vitae if you want a banger cv, flexdashboard for dashboard development. There is also a package called bookdown which adds a lot of functionality like being able to do crossreferences (Figure 1 etc) and you can write and publish entire books with it. It creates both publication/print ready pdfs of your books and html versions. E-books as well. Check out bookdown.org.

Quarto

Let’s create a new quarto document by File -> New File -> Quarto document. Everything is almost the same. In fact you can just copy and paste the previous content into a quarto document, it is backwards compatible.

Footnotes

1. Some of the syntax can be output-specific though – you would generate a page break differently when opting for pdf-output than doc.