Introduction to Quarto
What are we trying to achieve?
We propose using Quarto based on the assertion that that code alone is not enough to ensure reproducibility. A complete copy of all code, and an example dataset, can be used to accurately reproduce a result - however, it does not convey the logic, the reasoning, the intent of the work*.
Quarto is a system for producing documents which contain all code, comments from the author, and embedded outputs. The system is easy to use and wraps around the code you will already be writing, with the aim of making this documentation part of your every day workflow.
*An often-told story is about a cook who used to cut the ends off the meatloaf, not knowing why other than it’s how their mother used to do it. The story goes first to the mother, who explains that she learned to cut the ends off the loaf from her mother, and then we learn from the grandmother that she used to use one tray for baking the meatloaf, and a shorter tray for serving - the ends were cut off to fit the serving tray.
An ideal system would capture:
all code involved in viewing, manipulating, and storing data.
a snapshot of the input format, so that we know what our data should look like going in.
the outcome (tables, figures, saved files), so that we can independently re-run the analysis and ensure we get the same result, and demonstrate the format of the outcome so that we can use the method on our own data.
the mindset and logic used at each step, so that we can understand why certain methods and thresholds were chosen and determine for ourselves whether to apply or modify those steps for our own analysis.
What is Quarto?
Quarto is a system that facilitates the easy creation of documents that wrap and store our code, the outputs, and notes. With a small bit of extra effort when writing our code, Quarto can generate pdfs, word docs, slideshow presentations, and websites. This website is built using Quarto. It is designed for scientific publishing, and works with multiple languages (R, Julia, Python) - the outcome from these code blocks can be easily embedded (e.g., if code produces a figure, that figure will appear in the document). Quarto itself uses “markdown language”, and will be familiar for anyone already using RMarkdown. Markdown is meant to be readable even before it’s published, which means our day-to-day working documents are not a chore to work with.
Simply, with Quarto, you will add small pieces of code to define headers, insert code blocks, embed links and figures. This code is then rendered into a document for distribution or storage.
This website was built with Quarto. As an example, it has clear structure, embedded images and code, and a format that was very easy to create and replicate across documents. The same content could be easily redirected into a pdf or even a slideshow with very little effort.
What is the purpose of Quarto?
Quarto exists to make publishing scientific documents easy, and to facilitate the creation of flexible, high quality outputs.
Having the ability to create one or more documents with all code, comments, and output together is highly beneficial. Compare this to having individual R scripts, figures saved to a folder, and a word document with notes.
What can we do with Quarto?
Lots! It’s worth noting that we write our document using Quarto’s markdown language, and this is then translated into the final document, and it’s very easy to switch the output types (e.g., the same working document can be used to produce a word doc, a pdf, and a slideshow). Beyond simple documents, Quarto is an easy way to create websites, blogs, dashboards, and books (even a PhD thesis).
Quarto places a premium on quality - the online community of people using quarto are creating stylistic, clear, well-designed documents that emphasise the importance of science communication.
As an example this book was created in Quarto, and by book I mean both the printed version and the website.
How does it work?
This visual comes directly from a Quarto workshop presented at posit::conf(2023) by Andrew Bray, Amelia McNamara, Emil Hvitfeldt, and Mouna Belaid. I highly recommend this workshop, which covers a lot of background detail and specifics that we won’t have time to go over.
In brief, we produce a .qmd file (a Quarto file), which will include some mix of text, code, and the markdown language required to format and control the file. The code can be R, Python, Julia, etc.,. The code is converted into output (e.g., figures are generated, sums calculated), and this is then converted into one or more output documents.
Isn’t this just RMarkdown?
If you are familiar with RMarkdown this will all look and sound familiar, and these systems both aim to capture information and improve reproducibility. In fact, if you have RMarkdown documents you can rename them as .qmd files and they will render.
However, note that RMarkdown is R-specific. Quarto is language agnostic and can be used by people who work in Python.
In addition, Quarto has a strong focus on output documents and you will have an easier time with formatting and making high quality documents.
Working in Quarto
We will start by creating some basic documents, building up our working knowledge of the quarto language.
Quarto is a part of RStudio and this is how we will be working with it today. There is a Quarto R package that can be run separately from RStudio, and there is a Quarto extension for VisualStudioCode.