Introduction to Quarto

1 Introduction

This is a Quarto file. When you execute code within a Quarto file, the results appear beneath the code. Within R Studio, try executing the following chunk by clicking the Run button within the chunk (the green triangle on the right-hand side) or by placing your cursor inside it and pressing Ctrl+Shift+Enter.

plot(cars) #cars is a built-in dataset available in R.

You can add a new chunk by clicking the Insert Chunk button on the toolbar (the green box with the c) or by pressing Ctrl+Alt+I.

To produce a complete report containing all commentary, code and output, click the Render button in the toolbar across the top of R Studio (look for the blue arrow). This will create a HTML file, which should open automatically and also appear in the folder where you have saved this Quarto file.

1.1 How to Format Text

The visual editor in RStudio provides a WYSIWYM interface for adjusting the content of your report. This includes formatting your text similar to how you would in MS Word, i.e. you can underline text, put words in bold font or italics, add bullet points, insert images, etc… While the visual editor displays your content with your desired formatting, if you choose the source editor, then you can see your content in plain Markdown language. You can switch back and forth between the visual and source editors to view and edit your content using either tool.

If you are editing text in the source editor, then the following summarises how to apply various formatting:

Putting the hashtag symbol “#” followed by a space creates a new section. Use “##” for a second level heading and “###” for a third level heading.

Putting a pair of asterisks around a word causes the word to be printed in italics.

Putting a pair of double asterisks around a word causes the word to be printed in bold.

You can use single dashes to create bullet points, for example:

  • This is the first bullet point.
  • This is the second bullet point.

If you want to use numbered bullet points, then you use the following:

  1. This is the first numbered bullet point.
  2. This is the second numbered bullet point.

If you wish to include a hyperlink with a name as opposed to the actual website address, then write what you want to call the hyperlink inside square brackets and then include the link in round brackets directly after, for example RTE News.

You can also include .png image files in your Quarto file. This is similar to how you include a hyperlink, except you put an exclamation point at the start. The caption for the image goes in the square brackets and then the name of the .png file goes in the round brackets. Note that the .png file must be saved in the same location as where you have saved this Quarto file.

Isn’t R great?!?

2 Combining Code, Output and Commentary

Quarto is very popular with data analysts because you can combine your R code, output and commentary into one document. In this example, we will import the food_freq_quest.csv dataset, create some graphs and add our commentary.

REMEMBER:

  • When creating a Quarto file, all necessary files such as .csv files, images, etc… must be saved in the same folder as the Quarto file. Setting the working directory does not work when using Quarto.
  • When carrying out your analysis, all R code must be included in an R code chunk. All of your commentary and interpretation goes outside the R code chunk.

2.1 Import Data

The dataset we will use in this section is the food_freq_quest.csv dataset, which includes the following dietary variables for 42 female aesthetic athletes:

  • Level: amateur or professional.
  • Group: control, rhythmic gymnast, artistic gymnast or ballet dancer.
  • Intake: calorie intake.
  • Body Mass: body mass in kg.

First we will use the code in the following chunk to load the tidyverse package and then import our dataset.

library(tidyverse)

food <- read_csv("food_freq_quest.csv")

Within R Studio, look at the Quarto file and notice that we used message = F and warning = F in the chunk option area. Render the file with and without these bits of code to see what it does. With Quarto, it is good practice to prevent messages and warnings from appearing in the output HTML document. This is usually achieved by adding message = F and warning = F to the R chunk option area.

See Section 29.5 from R for Data Science for more information on chunk options. For example, if you only want the output and not the code to appear in the HTML file, then add echo = FALSE to the chunk option area. This is useful when writing reports aimed at people who don’t want/need to see the underlying R code. For example, coaches, players, etc…

2.2 Scatterplot

First we’ll create a scatterplot of intake versus bodymass. We can see there is a somewhat linear relationship between an athlete’s bodymass and their calorie intake.

ggplot(data = food) + 
    geom_point(mapping = aes(x = intake, y = bodymass))

2.3 Barchart

The following R chunk produces a barchart showing the number of athletes in each combination of group and level.

ggplot(data = food) + 
    geom_bar(mapping = aes(x = group, fill = level), position = "dodge")

2.4 Table

The following chunk creates a table showing the mean calorie intake for each athlete group. We can see that Artistic Gymnasts have the highest calorie intake.

table1 <- food %>%
            group_by(group) %>%
            summarise(mean_intake = mean(intake)) %>%
            arrange(mean_intake)

table1
# A tibble: 4 × 2
  group            mean_intake
  <chr>                  <dbl>
1 Rhythmic Gymnast       1648.
2 Ballet Dancer          1727.
3 Control                1855.
4 Artistic Gymnast       1948.

Notice that table1 appears in the HTML file in the same format as when it appears in the console window. However, we can make the table look a lot nicer by using a function called kable() from the knitr package and setting the following parameters:

  • col.names is used to rename the column headings.

  • digits is used to specify the number of decimal places that each column should be rounded to. Here we have set digits = c(0,2), which will round the first column to have 0 decimal places (which makes sense because the first column contains text) and will round the second column to have 2 decimal places.

  • align is used to specify the alignment of each column. Here we use “lr”, which means the first column should be left-aligned and the second column should be right-aligned (text columns should always be left-aligned and numerical columns should always be right-aligned).

  • caption is used to give the table a caption.

#Here we use "::" to tell R that we want to use the kable() function from the knitr package.
#This is sometimes needed if there are two functions with the same name.
knitr::kable(table1, 
             digits = c(0,2), 
             align = "lr",    
             col.names = c("Athlete Group", "Mean Calorie Intake"),
             caption = "Average Calorie Intake by Athlete Group")
Average Calorie Intake by Athlete Group
Athlete Group Mean Calorie Intake
Rhythmic Gymnast 1647.85
Ballet Dancer 1727.18
Control 1854.82
Artistic Gymnast 1947.86

2.4.1 Even Better Table Formatting with kableExtra

If rendering to HTML, then the table can sometimes appear “squashed” making it difficult to read each individual column or can appear too spread out. However, we can use functions from the kableExtra package to apply further formatting. For example, if rendering to HTML, then we can tell Quarto the table should not be the width of the screen by (i) telling Quarto to not process the table by adding table.attr = ‘data-quarto-disable-processing = “true”’ within the kable() function (Quarto has a special processing method that we don’t want to apply here) and (ii) adding kable_styling(full_width = F) using %>%.

#install.packages("kableExtra") #If necessary, then first install kableExtra.

library(kableExtra)

knitr::kable(table1, 
             digits = c(0,2), 
             align = "lr", 
             col.names = c("Athlete Group", "Mean Calorie Intake"),
             caption = "Average Calorie Intake by Athlete Group",
             table.attr = 'data-quarto-disable-processing = "true"') %>% 
  kable_styling(full_width = F)
Average Calorie Intake by Athlete Group
Athlete Group Mean Calorie Intake
Rhythmic Gymnast 1647.85
Ballet Dancer 1727.18
Control 1854.82
Artistic Gymnast 1947.86

To format rows in different ways, you can use the row_spec() function. Similarly, you can use the column_spec() function to format the columns in different ways.

knitr::kable(table1, 
             digits = c(0,2), 
             align = "lr", 
             col.names = c("Athlete Group", "Mean Calorie Intake"),
             caption = "Average Calorie Intake by Athlete Group",
             table.attr = 'data-quarto-disable-processing = "true"') %>% 
  kable_styling(full_width = F) %>%
    row_spec(0, bold = TRUE, color = "white", background = "black") %>%
    column_spec(1, underline = TRUE, italic = TRUE, bold = TRUE, color = "red")
Average Calorie Intake by Athlete Group
Athlete Group Mean Calorie Intake
Rhythmic Gymnast 1647.85
Ballet Dancer 1727.18
Control 1854.82
Artistic Gymnast 1947.86

3 Publishing Your Report

There are many ways to publish documents created using Quarto, which are discussed at this link. The following gives instructions on how to publish your report using two options: RPubs and Quarto Pub.

3.1 RPubs

  1. Create a free account with RPubs and make sure you are logged into your RPubs account.
  2. Open the Quarto file that you want to publish within RStudio.
  3. Across the top of R Studio, look for a blue icon beside the green “Add Chunk” and “Run” buttons.
    • Click the drop-down and select “Publish Document”.
    • A box will appear asking where you want to publish your report. Choose “RPubs”. Then click “Publish”.
    • Your default internet browser will open a page, asking you to confirm various details such as the title and description of your report. After entering these details, click “Continue”.
  4. Your report should now be available to view within RPubs.

3.2 Quarto Pub

  1. Create a free account with Quarto Pub.
  2. Open the Quarto file that you want to publish within RStudio.
  3. In the bottom left of RStudio, click the Terminal tab and copy and paste in the following code: quarto publish quarto-pub
  4. You will be asked to authorise your account and to choose the name you want to use for the published file.
  5. RStudio will then render your file and make it available within your Quarto Pub account. You will then be able to share a hyperlink to your file with relevant stakeholders.

4 Further Reading

To learn more about Quarto, please see the following resources: