Day 3: Report writing with Quarto

Analyse. Share. Reproduce.

Paul Moloney https://bfanson.github.io/2024DADAworkshop/ (Arthur Rylah Institute)https://www.ari.vic.gov.au/
2024-09-18

REMINDER TO US: START RECORDING!!!

Show code 
# just reading in some information for this webpage
ds_richness <- readRDS('data/ards_richness.rds') %>% filter(!is.na(native)) %>%
  mutate(visit = as.numeric(str_sub(survey_id, start = -1)) - 1)
tb_mod_spp <- readRDS('results/tb_mod_spp.rds')
pred_spp <- readRDS('results/pred_spp.rds')

Day’s objectives

Key packages

Project folder for today

For background information on the dataset, see dataset summary

Workflow

Reminder of our workflow…

The pitch

So, you need to analyse some data and report on the results, including tables, figures and references?

Then maybe Quarto is for you!!!!

Why would I want to use something like Quarto?

The benefits of using something like Quarto is around closing the circle in your workflow when it comes to analysing data and producing documents with that data.

Quarto allows you to seamlessly integrate work from difference like R, Python, SQL, Latex and many other sources within the one notebook interface. It has the functionality to incorporate citations and change referencing systems easily. From one notebook, you can produce a Word document or a website.

The outputs could be documents (Word, PDF, HTML) presentations (PowerPoint, Beamer, Revealjs), websites, books/manuscripts or interactive displays (Shiny, widgets).

Your final output can contain formatted tables, figures, pictures, footnotes, citations, cross-references, all updated once the code is compiled. As part of your workflow, you can update reports easily, potentially with nothing more than updating the data and clicking the render button1.

What to expect when creating a report with Quarto

For those that are used to using Word and PowerPoint to create all their work documents, using a computational document can be a bit daunting. However, our goal today is to break the ice with using a mark-up language to creating a document. With Quarto and RStudio that task is a little easier.

Don’t panic

The first (and main) difference you will notice when you open a Quarto document is that there is weird coding bits here and there. Unlike Word and PowerPoint, Quarto is not WYSIWYG (What You See Is What You Get). We will use the Visual option that makes it a bit more like WYSIWYG, but not completely, as certain parts will only be converted once you render the file. To get the final version we need to compile the file.

Workflow within Quarto

For each project where you want to create a document you follow a similar pattern.

  1. Open a file that uses the .qmd extension.
  2. Write the content with using the Quarto syntax.
  3. Embed R (or other) code that creates the output that you want to include in the report.
  4. Render the code, transforming the code into a slideshow, pdf, html or Word file.

Creating a document using Quarto

Starting a new Quarto document

The first thing that you want to do is open/create your project in RStudio. Then choose File > New file > Quarto document… from the menu to create a new .qmd file. You will need to chose what sort of document you want to create. The one we will create is “Document” (Figure 1). This will create a Quarto script that includes some text and examples of how to create the document that you want.

Show code 
knitr::include_graphics("figures/open_quarto.png")
Screenshot of the pop-up window you need to use to create your Quarto script.

Figure 1: Screenshot of the pop-up window you need to use to create your Quarto script.

The first thing you will notice (see Figure 2) is that unlike a Word document there is code and different coloured text, but this is not what the rendered document will look like, this is just the code to create the document. You will notice at the top of the page that there is some colourful text with names like “title” and “format” in between lines with three dashed. This is called the YAML and it sets the style and format of your document. The default YAML is written for us in the template. For the moment, change the title to something other than “untitled” and under that let’s add “author: Your Name” with your actual name (rather than Your Name). Now press the Render button and it will render your document, with your new title and you as the author. Have a look at the html document produced and see the sort of things that can be included from R and Quarto.

Show code 
knitr::include_graphics("figures/initial_quarto.png")
Screenshot of the initial Quarto script.

Figure 2: Screenshot of the initial Quarto script.

Working with a pre-existing .qmd

Rather than working on this template let us break down the parts of the code by opening the file “wetland grazing.qmd”. There is a lot of code, but this is basically a finished document (in terms of most coding anyway). After the YAML (which has more in it than before, which we will cover later) there is what we call a “chunk” of code. This is where we use our R code to edit data, run models and generally do all our R stuff. The first chunk is usually where we set-up the R environment by loading libraries and set defaults for the chunks.

The structure of a chunk is that inside the braces (“{ }”) you start with “r” (if it is an R chunk). Directly under that are usually the options you want for this chunk. Common options are:

Common options for code chunks
Name Description
echo Whether to display the code along with its results (default is TRUE)
include Whether to display the results of the code (default is TRUE)
warning Whether to display warnings (default is TRUE)
cache Whether to cache results for future renders (saves the results and uses them for later renders without re-evaluating them, default is FALSE). Can be useful if a chunk take a long to run, but can mean that if the data elsewhere is changed, it won’t be reflected in this chunk.
fig-width Width in inches for plots created in the chunk (default is 7”)
fig-height Height in inches for plots created in the chunk (default is 7”)
fig-cap The caption to be associated with this figure
tab-cap The caption to be associated with this table
label The name used to reference this chunk

NB: If you want to be able to cross-reference your tables and figures etc, you need to follow the naming conventions, otherwise it will not be able to find the label and the cross-reference won’t show up.

Creating tables

To create a table in Quarto there are two main methods.

Native to Quarto

You can insert a table using the Insert > Table… option through the menu. You can select the dimensions of the table, if you want headers and if you want a caption. It then constructs that table, similar to a blank table in Word. You would then need to populate that table by hand. Maybe copy and paste will work, but the whole point of using something like Quarto is to not have to copy and paste data. The “Common options for code chunks” was constructed that way.

⭐ ☆ ☆ ☆ ☆

Native to R

Alternatively, you could insert an R chunk, and import a table that way from your data. If you leave it at that you will have a very basic table entered that looks like the one below.

Show code 
data.frame(Here = rpois(5, 3), There = rpois(5, 5))
  Here There
1    4     3
2    2     3
3    3     4
4    1     4
5    2     3

If you want to produce a table that is ready to publish, then you could use a package like flextable or gt to get it looking nicer, with lots of options. The table below is an example of an ARI style table using flextable. If you are wanting to reference your tables, you will need to label them with the prefix “tbl-”

Show code 
imp_spp <- (tb_mod_spp$conf.low*tb_mod_spp$conf.high > 0) & (tb_mod_spp$effect == 'fixed')
tb_mod_spp %>%
  select(-component) %>%
  mutate(across(where(is.numeric), ~ round(.x, 3)),
         effect = str_to_sentence(effect),
         effect = str_replace(effect, 'Ran_pars', 'Random')) %>% flextable() %>%
  set_header_labels(values = c('Effect', 'Grouping', 'Parameter', 'Estimate', 'S.E.', 'Lower', 'Upper')) %>%
  add_header_row(colwidths = c(5, 2), values = c("", "95% Credible bound")) %>%
  align( j=4:7, align='right', part='body' ) %>%
  bold(i = imp_spp) %>%
  ari_theme()

Figures

Inserting pictures

You can insert a picture by using the Insert > Figure/Image… just like you would in Word. You can add a caption at that stage. To give it a label/ID select the “Attributes” button and type in a unique name that starts with “fig-” so that it know its a figure.

Creating figures

If you want to construct a plot (say using ggplot2) you can do that via an R chunk. Insert the R chunk from the menu (Insert > Code Cell > R) and crate your figure from scratch. Use the code chunk to set the label so you can reference it later.

Including citations

Citations can be inserted using the menu Insert > Citation…. That will give you a pop-up window that will link to your Zotero account and other public reference source. If you start typing in the some information about the citation you are after, it will then search your reference list or search externally if you select that option. Selected citations will appear at the bottom of the pop-up window. Once you have the citations you are after, press Insert and they will be inserted into the notebook, as well as added to the .bib file for this project.

Alternatively, once you have some citations or your Zotero links, it you type “@” it will pop-up a window to search for citations from your list.

When you render the document, your citations (saved in the .bib file) will be sent to pandoc and any style you have selected will be applied. In the YAML you will see a line for the cls and the bibliography. Unless you want to attach a specific reference library, you shouldn’t need to change that file name. The cls on the other hand can be changed easily to change the referencing style of the document.

Inserting footnotes

It is easy to insert a footnote, just use the menu to Insert > Footnote. It will insert a number for the footnote and give a subtle pop-up for you to enter the text for that footnote. If you want to change the footnote, just click the number again.

Dynamic text

You can insert dynamic text into your writing in-line, by pressing “`” (shift+tilda) followed by r then your calculation followed by another “`”. This can be very useful when writing reports and you need to reference a statistic. If it changed, you don’t need to go back and edit it, it will update it automatically when you render it again.

Templates

If you want to customize the appearance of output into Word, Pandoc supports a special type of template called a reference document. To make Quarto use a specific reference document, it needs to be included in the YAML.

Creating your own template

To create a new reference doc based on the Pandoc default, execute the following command:

$ quarto pandoc -o custom-reference-doc.docx
–print-default-data-file reference.docx

Then, open custom-reference-doc.docx in MS Word and modify styles as you wish. You can open the Styles pane from the HOME tab in the MS Word toolbar. When you move the cursor to a specific element in the document, an item in the styles list will be highlighted. If you want to modify the style of any type of element, you can click the drop-down menu on the highlighted item. After you finish modifying the styles, you can save the document and use it as the template for future Word documents.

  1. We are in no way liable for your words not matching the analysis output if the data changes↩︎