Getting Started with Quarto for Data Science Reports

Quarto
Tutorial
Reproducibility
A beginner’s guide to creating beautiful, reproducible reports using Quarto in your data science workflow.
Author

Antoine Lucas

Published

July 10, 2024

Why Quarto is worth learning

Quarto is the tool I reach for when an analysis needs to be more than a notebook and less than a full application. It lets you keep narrative, code, figures, and output in one plain-text document that can render to HTML, PDF, Word, slides, or an entire website.

That combination matters for data work because it solves a common problem cleanly: the code that produced the result and the text that explains the result live in the same file.

Your first useful document

Create a file called report.qmd:

---
title: "Exploratory Fuel Efficiency Report"
author: "Antoine Lucas"
format: html
execute:
  echo: true
  warning: false
date: today
format: html
---

## Question

How does vehicle weight relate to fuel efficiency in the `mtcars` dataset?

```{r}
library(ggplot2)
ggplot(mtcars, aes(x = wt, y = mpg)) +
  geom_point() +
  geom_smooth(method = "lm", se = FALSE, color = "steelblue") +
  labs(
    title = "Heavier cars tend to have lower fuel efficiency",
    x = "Weight (1000 lbs)",
    y = "Miles per gallon"
  )
```

That is enough for a real first report: a title, a short question, and a code chunk that produces an interpretable figure.

Render it

quarto render report.qmd

You now have an HTML report that can be shared, versioned, and rerun.

The pieces that matter

YAML header

The header between the --- lines controls document-level behavior:

  • title, author, and date are document metadata
  • format: html chooses the output format
  • execute: sets chunk defaults for the whole document

Code chunks

Code chunks are where Quarto becomes useful instead of just pretty Markdown. In R, they look like this:

#| echo: true      # Show the code
#| eval: true      # Run the code
#| warning: false  # Hide warnings
#| fig-width: 8    # Figure width
#| fig-height: 6   # Figure height

These options let you decide what the reader sees and what the document executes.

Cross-references

Once you start writing longer reports, cross-references save time and reduce broken prose. Instead of writing “the chart below”, label the figure and refer to it directly:

See @fig-scatter for the visualization.

```{r}
#| label: fig-scatter
#| fig-cap: "Scatter plot of weight vs mpg"
ggplot(mtcars, aes(x = wt, y = mpg)) +
  geom_point()

```

Quarto handles the numbering for you.

Callouts that carry meaning

Callouts are useful when they add interpretation or caution, not when they are decorative. For example:

Note

If the document is going to be rerun by someone else, explain the data source and any preprocessing assumptions close to the code that depends on them.

Warning

Do not use Quarto as a substitute for version control. The document is reproducible only if the code, input data, and environment are also under control.

When Quarto is the right choice

Quarto is a strong default when:

  1. You need a report, not just exploration.
  2. The narrative around the analysis matters.
  3. The output needs to be reviewed or rerun later.
  4. You want one source file that works with Git.

For pure exploration, a notebook may still be faster. For anything that becomes a deliverable, Quarto usually ages better.

Common first mistakes

  • Treating the document as presentation only and hiding too much code.
  • Using absolute file paths that only work on one machine.
  • Forgetting that the environment matters as much as the .qmd file.
  • Jumping to complex websites and books before writing one good report.

Conclusion

The best way to learn Quarto is not by memorizing every option. It is by writing one small report that answers one real question and renders cleanly from start to finish. Once that feels natural, features like cross-references, citations, websites, and PDFs start to make sense.

Resources

Back to top