1 Why Quarto

The goal of this section is to briefly discuss why we want to learn Quarto, the benefits, and the barriers to using it.

1.1 Overview

Teaching 3 minutes
Exercises 5 minutes

1.2 Questions

What is the value in a reproducible report?
What is Markdown?
Can I combine my software and my writing?

1.3 Objectives

Learn how to use Markdown
Think about why you want to use Markdown

Your Turn

Why are we here Form small groups of 2-4 with your neighbours and discuss how you expect learning Quarto might benefit you.

1.4 Reproducibility is a problem

It is unfortunately a common, seemingly evergreen problem that a lot of people cannot reproduce scientific work. This might appear to be a “current” problem, but it has indeed been a problem throughout a lot of scientific history. To illustrate this, here’s a nice article by Rich FitzJohn, Reproducible research is still a challenge, which was written 10 years ago, in 2014, and provides a list of the challenges and lessons learned in making research reproducible. The list is still relevant. This problem isn’t completely solved. But, we can make it easier to solve, to get further.

Reproducibility isn’t just something that impacts a few people, and it’s not cheap. A 2010 estimate stated that in the biomedical industry, in the USA, irreproducibility (not being able to reproduce a given piece of work) costs $28 Billion dollars annually ¹. That was one country, one field, and one year.

So what can we do about it?

1.5 Literate programming is a partial solution

The idea of literate programming shines some light on this dark area of science. This is an idea from Donald Knuth where you combine your text with your code output to create a document. This is a blend of your literature (text), and your programming (code), to create something that you can read from top to bottom. Imagine your paper - the introduction, methods, results, discussion, and conclusion, and all the bits of code that make each section. With Quarto, you can see all the pieces of your data analysis all together.

Some history: Quarto, Rmarkdown, Sweave

Literate programming was a popular idea, and it has had some interesting discussion and contributions over the years. Notably, in the R ecosystem, the Sweave, (The S language + weaving together text and code) program provided a way to write text and code together. As with any technology, there were some speedbumps with using Sweave, and some of the reasons we are not teaching it now is because:

It uses a form of LaTeX, which provides great flexibility at the cost of complexity.
Printing figures involves additional work
There isn’t a way to save (cache) your work. Every analysis has to be repeated from start to finish. This was time consuming.

1.6 Markdown as a new player to legibility

In 2004, John Gruber, of daring fireball created Markdown, a simple way to create text that rendered into an HTML webpage. The core idea was that you could write plain text (not text inside a MS Word/WordPerfect/Pages/Proprietary Format Document), and it would look readable, then get rendered into HTML.

The idea took off.

1.6.1 A brief example of markdown

- bullet list
- bullet list
- bullet list

1. numbered list
2. numbered list
3. numbered list

__bold__, **bold**, _italic_, *italic*

> quote of something profound


```r
# computer code goes in three back ticks
1 + 1
2 + 2
image(volcano)
```

Would be converted to:

bullet list
bullet list
bullet list

numbered list
numbered list
numbered list

bold, bold, italic, italic

quote of something profound

# computer code goes in three back ticks
1 + 1

[1] 2

2 + 2

[1] 4

image(volcano)

With very little marking up, we can create rich text, that actually resembles the text that we want to see.

Some other nice features of Markdown include:

Feature	Markdown \| rendered
superscript	`2^nd^` \| 2^nd
subscript	`CO~2~` \| CO₂
strikethrough	`~~mistake~~` \| ~~mistake~~
links	`[text](https://quarto.org/)` \| text
links	`<https://quarto.org/>` \| https://quarto.org/)
images	`![alternative text](link-to-image)` \| (cannot render in a table)

For more examples and details of using markdown in Quarto, see the official Quarto “Markdown Basics” documentation.

2 What about Rmarkdown?

Issues around Sweave led to the development of knitr, and subsequently Rmarkdown, which used the knitr engine. You could run more than R code in rmarkdown, in fact there are over 60 engines available, from awk and bash, to haskell, perl, php, sql, scala, stata, javascript, python, julia, and even C.

Through rmarkdown there were many approaches to document processing, such as bookdown for books, blogdown for blogs and websites, xaringan for slide decks.

However, there are a few points of friction:

You need to call it from R to use it. No problem for R users, but what if you use python? Or Julia? Or javascript? If you are a python user, using R to use python just might not be in your workflow.
There are great packages that provide extensions, such as blogdown for blogs, bookdown for books, and xaringan for slides. Each of these systems is an iteration towards something awesome, and it’s only natural they might be a little bit different. Overall, there are differences between these systems that might cause stumbles.
Quarto, instead of being an R package, is a separate piece of software, that you can call from the command line (terminal). This means other pieces of software can use it to create their own literate programming documents. Well, that’s my understanding.

Here are some diagrams to illustrate this point:

Rmarkdown can talk to Python, but it works from within R

In rmarkdown, we are working in rmarkdown, and that uses knitr to talk to R and handle the document generation:

But with Quarto, we have this general interface, where Quarto can talk to different programming languages. Not pictured, but the “R engine” is in fact, knitr:

Your Turn

Learn to use Markdown In your small groups, spend five minutes working through this brief online Markdown tutorial

3 Quarto helps complete the solution to the reproducibility problem

So, how do we combine this with our R code, into a literate programming environment?

Quarto provides an environment where you can write your complete analysis. It weaves your text, and code, and its output together into a single document.

For example, look at the following report:

How did we generate it?

---
title: "Exploring gapminder"
author: "Nicholas Tierney"
format: html
---

```{r}
#| label: library
library(tidyverse)
library(broom)
```

```{r}
#| label: data-read-in
data <- read_csv(here::here("data/oz_gapminder.csv"))
```


# Introduction

let's look at the lifespan

```{r}
#| label: hist-life-exp
hist(data$lifeExp)
```


Let's fit a simple linear model of the effect of year on life expectancy

```{r}
#| label: example-lm
fit <- lm(lifeExp ~ year, data = data)
fit
```


And let's look at the coefficient table:

```{r}
#| label: coef-table
library(broom)
fit_coef <- tidy(fit)
knitr::kable(fit_coef,
             caption = "A table of the coefficients")
```

The effect of year on life expectancy is `{r}  fit_coef$estimate[2]`.

We render this code and it creates this report!

It has a plot, it has a table, we even refer to some of the values in the text - the last line of the report looks at the effect of year.

But what if the data changes? At the moment we are looking at only Australia - say we get the full dataset, what happens then?

Say you’d created your report by hand in microsoft word, and with a graphical user interface software, you would need to:

Go back to the GUI, re run the analysis
Import the results into Excel
Create your graph
Copy the graph into Word
Copy the results of the coefficients into the text
Copy the results of the coefficient table into the text.

This is painful.

And what if someone wants to know exactly how you did your analysis?

This process isn’t exactly sharable.

But if you did it in Quarto?

Just update the data, and render the document again, and get an updated document:

The results are updated!

And we just pointed it to some different data. Then re-rendered it.

That’s it.

That is why we use Quarto

3.1 Summary

In this section we’ve learned about:

What the value is in a reproducible report
What is Markdown
How to combine software and writing
How to use Markdown

3.2 Learning more

Posit’s Quarto cheatsheet

The article, Freedman, 2010, Heard via Garret Grolemund’s great talk ↩︎