Introduction to Quarto in R

Kamarul Imran Musa
drki.musa@gmail.com

Universiti Sains Malaysia

2025-10-09

What is Quarto?

  • A unified authoring framework for data science
  • Combines code, results, and prose
  • Next-generation version of R Markdown
  • Supports multiple programming languages (R, Python, Julia)
  • Creates reproducible documents

Why Use Quarto?

Three main purposes:

  1. Communicate to decision-makers (focus on conclusions)
  2. Collaborate with other data scientists (share code and reasoning)
  3. Environment for doing data science (modern lab notebook)

Quarto Workflow

Basic Document Structure

Three main components:

  1. YAML header (metadata and settings)
  2. Code chunks (executable R code)
  3. Markdown text (formatted prose)

YAML Header Example

---
title: "My Analysis"
author: "Data Scientist"
date: 2025-10-08
format: html
editor: visual
---

Sets document-wide options and metadata

Code Chunks

Insert with:

  • Keyboard: Cmd/Ctrl + Alt + I
  • Menu: Insert button
  • Manually: ```{r} and ```
```{r}
#| label: example-chunk
#| echo: true
#| eval: true

library(tidyverse)
summary(mpg)
```
library(tidyverse)
summary(mpg)
 manufacturer          model               displ            year     
 Length:234         Length:234         Min.   :1.600   Min.   :1999  
 Class :character   Class :character   1st Qu.:2.400   1st Qu.:1999  
 Mode  :character   Mode  :character   Median :3.300   Median :2004  
                                       Mean   :3.472   Mean   :2004  
                                       3rd Qu.:4.600   3rd Qu.:2008  
                                       Max.   :7.000   Max.   :2008  
      cyl           trans               drv                 cty       
 Min.   :4.000   Length:234         Length:234         Min.   : 9.00  
 1st Qu.:4.000   Class :character   Class :character   1st Qu.:14.00  
 Median :6.000   Mode  :character   Mode  :character   Median :17.00  
 Mean   :5.889                                         Mean   :16.86  
 3rd Qu.:8.000                                         3rd Qu.:19.00  
 Max.   :8.000                                         Max.   :35.00  
      hwy             fl               class          
 Min.   :12.00   Length:234         Length:234        
 1st Qu.:18.00   Class :character   Class :character  
 Median :24.00   Mode  :character   Mode  :character  
 Mean   :23.44                                        
 3rd Qu.:27.00                                        
 Max.   :44.00

Chunk Options

Common options using #| syntax:

  • label: - name your chunk
  • echo: false - hide code
  • eval: false - don’t run code
  • include: false - run but hide everything
  • warning: false - suppress warnings
  • message: false - suppress messages

Visual vs Source Editor

Visual Editor:

  • WYSIWYM interface (like Google Docs)
  • Easy for beginners
  • Insert menu and shortcuts (⌘ / or Ctrl /)

Source Editor:

  • Plain markdown
  • More control
  • Better for debugging

Rendering Documents

Three ways to render:

  1. Click Render button
  2. Keyboard: Cmd/Ctrl + Shift + K
  3. Console: quarto::quarto_render("file.qmd")

Creates HTML, PDF, Word, or other formats

Figure Sizing

Recommended settings:

  • fig-width controls R figure size
  • out-width controls output display size
  • fig-asp sets aspect ratio (golden ratio)

Multiple Plots

Use layout-ncol for side-by-side plots:

Tables

Basic table with knitr::kable():

First 5 columns of mtcars
mpg cyl disp hp drat
Mazda RX4 21.0 6 160 110 3.90
Mazda RX4 Wag 21.0 6 160 110 3.90
Datsun 710 22.8 4 108 93 3.85
Hornet 4 Drive 21.4 6 258 110 3.08
Hornet Sportabout 18.7 8 360 175 3.15
Valiant 18.1 6 225 105 2.76

For advanced tables: gt, kableExtra, reactable

Inline Code

Embed R results directly in text:

We analyzed 53940 diamonds.
Only 126 exceeded 2.5 carats.

Output: “We analyzed 53,940 diamonds. Only 126 exceeded 2.5 carats.”

Global Options

Set options for all chunks:

---
title: "My Report"
execute:
  echo: false
  warning: false
  message: false
---

Output Formats

Change format in YAML:

  • format: html - Web pages
  • format: pdf - PDF documents
  • format: docx - MS Word
  • format: revealjs - Presentations (like this!)

Caching

Speed up rendering for slow computations:

Use with caution - only reruns when code changes!

Citations & Bibliography

Add citations in visual editor:

  • Insert > Citation
  • Automatically creates bibliography.bib
  • Cite with [@author2024]
  • Customize style with CSL files
bibliography: references.bib
csl: apa.csl

Best Practices

  1. Use descriptive chunk labels
  2. Set cache: true for slow computations
  3. Name notebooks clearly with dates
  4. Document your thinking process
  5. Make it reproducible
  6. Use version control (Git/GitHub)

Troubleshooting Tips

Common issues:

  • Duplicated chunk labels - ensure unique names
  • Working directory - Quarto uses document location
  • Missing packages - document with sessionInfo()
  • Run all chunks to test interactively
  • Set error: true to debug

Next Steps

  • Practice with simple documents
  • Explore Quarto documentation: quarto.org
  • Try different output formats
  • Learn more about:
    • Cross-references
    • Advanced layouts
    • Publishing options
    • Quarto websites and books

Thank You!

Resources:

Questions?