How to use Quarto to create Open & Reproducible Presentations

Digital Research Academy Train the Trainer program

Source | Slides

Nick Bearman

nick@nickbearman.com

Unai Fischer Abaigar

Unai.FischerAbaigar@stat.uni-muenchen.de

Jan Simson

hi@simson.io

February 13, 2024

Outline

Summarise FAIR principles and reproducible research (Nick)
Talk about Quarto, one tool in your toolkit (Unai)
Make a presentation in Quarto (Nick & you)
Compare PowerPoint and Quarto (Jan)
Demo creating and updating slides in realtime using GitHub Actions (Jan)
Questions (you)

Our Target Audience

Familiar with FAIR principles and reproducible research
Not familiar with doing it in practice
Preaching to the choir

Learning objectives

You can create reproducible teaching materials collaboratively using tools like Quarto and Git(Hub)
You will do some of this today, and know where to go to develop your skills

What are FAIR Principles?

Findable

Descriptive metadata and persistent identifier (DOI)

Accessible

Data could be openly available OR access via authentication and if needed

Interoperable

Data needs to be integrated with other data and interoperate with applications or workflows (Open formats)

Reusable

Documentation and license (Open license - e.g. Creative Commons)

by Scriberia for The Turing Way community (CC-BY 4.0)

How does FAIR apply to teaching materials?

Findable/Accessible

Share your slides/materials on a data repository to receive a DOI and ensure long term preservation
Share your materials via a journal article
Share your materials in a training material registry

Interoperable

Use commonly used formats (PowerPoint / Word) or open formats such as Markdown or Quarto documents (PDF)
Use common terminology
Integrate with other resources where possible

Reusable

Add documentation
Add metadata
Share under an Open License such as CC-BY

What is Reproducibility?

“[…] when the same analysis steps performed on the same dataset […] produce the same answer.” (Turing Way)

by Scriberia for The Turing Way community (CC-BY 4.0)

How does reproducibility apply to teaching materials?

Comes close to the Interoperability and Reusable principles:

Integrating materials (minimise duplication)
Formatting
Software/code
Similar learning goals/objectives and outcomes

Practice what you preach!

By setting up your teaching materials in a reproducible manner, you demonstrate the value of reproducibility directly

Useful for others
Useful for future you when you teach this course again

FAIR and reproducible training materials are beneficial to you!

Information sheets saves time in sharing information
Clear communication (or you can update the information!)
Saves time in on-boarding/re-using materials
Preserved & Findable
Easy to share within and outside your team
Provides you and collaborators with credit (visibility, DOI, citations)

FAIR and reproducible training materials are beneficial to us!

FAIR and reproducible training materials are beneficial to Nick, Jan and Unai 😀
We used the Reproducible and FAIR Teaching Materials slides from the Aug 2023 Train the Trainer programme
Thank you very much to Esther Plomp and Lennart Wittkuhn 🙏 whose Quarto slides we used and developed!

Esther Plomp

e.plomp@tudelft.nl
estherplomp.github.io
GitHub
Mastodon

Lennart Wittkuhn

lennart.wittkuhn@uni-hamburg.de
lennartwittkuhn.com
GitHub
Mastodon

Outline

~~Summarise FAIR principles and reproducible research (Nick)~~
Talk about Quarto, one tool in your toolkit (Unai)
break
Show you how to make a presentation in Quarto (Nick)
Compare PowerPoint and Quarto (Jan)
Demo creating and updating slides in realtime using GitHub Actions (Jan)
Questions (you)

What is Quarto?

About Quarto

Quarto is a new, open-source, scientific and technical publishing system
Combine text and code to produce formatted documents
Publish reproducible and dynamic presentations, dashboards, websites, blogs, and books in HTML, PDF, MS Word, etc.
Multi-language support for R, Python, Julia, and more
Quarto extends RMarkdown and shares similarities with Juypter Notebooks.

Artwork from “Hello, Quarto” keynote by Julia Lowndes and Mine Çetinkaya-Rundel, presented at RStudio Conference 2022. Illustrated by Allison Horst.

Formats

Documents: HTML, PDF, MS Word, Open Office, ePub
Presentations: Revealjs, PowerPoint,
Wikis: MediaWiki, JiraWiki, …
Many templates exist for academic documents: quarto-journals
And much more: Jupyter, RTF, InDesign, …

How does Quarto work?

taken from What is Quarto - A Quick Intro FAQ

.qmd

qmd file

.ipynb

jupyter notebook

Tools

$ quarto render hello.qmd --to doxc

A .qmd (and .rmd) file

---
title: "My document"
format: html
---
. . .
# Introduction

*Hello Quarto!*

```{r}
summary(cars)
```

Rendered Output

YAML header

---
title: "My document"
author: John Doe
date: today

format:
  html:
    toc: true
engine: knitr

execute:
  echo: false

params:
  year: 2023
  country: "Germany"
  alpha: 0.05

# bibliography: references.bib
---

Rich set of rendering options for Pandoc, Quarto and Knitr

Markdown text

Syntax	Output
`Italic`	Italic
`Bold`	Bold
`~~strikethrough~~`	~~strikethrough~~
`[Link](url)`	Link
`i\hbar \frac{\partial \Psi}{\partial t} = -\frac{\hbar^2}{2m} \nabla^2 \Psi + V(\mathbf{r},t) \Psi`	\(i\hbar \frac{\partial \Psi}{\partial t} = -\frac{\hbar^2}{2m} \nabla^2 \Psi + V(\mathbf{r},t) \Psi\)

Code chunks

data(iris)

plot(iris$Sepal.Length, iris$Sepal.Width, 
     main = "Scatter Plot of Sepal Length vs Sepal Width",
     xlab = "Sepal Length (cm)",
     ylab = "Sepal Width (cm)",
     pch = 16, col = iris$Species)

Code chunks

```{r}
#| label: "iris-plot"
#| echo: TRUE
#| fig-format: svg
#| cache: TRUEs

data(iris)

plot(iris$Sepal.Length, iris$Sepal.Width, 
     main = "Scatter Plot of Sepal Length vs Sepal Width",
     xlab = "Sepal Length (cm)",
     ylab = "Sepal Width (cm)",
     pch = 16, col = iris$Species)

```

defaults to knitr engine (you can override the engine with engine: jupyter)

```{python}
#| label: fig-polar
#| fig-cap: "A line plot on a polar axis"

import numpy as np
import matplotlib.pyplot as plt

r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(
  subplot_kw = {'projection': 'polar'} 
)
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()
```

defaults to jupyter engine

You can use Python and R code together using the reticulate package

Quarto Showcase

Fragments

Fade in

Fade out

Highlight red

Fade in, then out

Slide up while fading in

Hello…

…World”

Quarto Showcase

viewof bill_length_min = Inputs.range(
  [32, 50], 
  {value: 35, step: 1, label: "Bill length (min):"}
)
viewof islands = Inputs.checkbox(
  ["Torgersen", "Biscoe", "Dream"], 
  { value: ["Torgersen", "Biscoe"], 
    label: "Islands:"
  }
)

Plot
Data

Plot.rectY(filtered, 
  Plot.binX(
    {y: "count"}, 
    {x: "body_mass_g", fill: "species", thresholds: 20}
  ))
  .plot({
    facet: {
      data: filtered,
      x: "sex",
      y: "species",
      marginRight: 80
    },
    marks: [
      Plot.frame(),
    ]
  }
)

Inputs.table(filtered)

data = FileAttachment("palmer-penguins.csv").csv({ typed: true })

filtered = data.filter(function(penguin) {
  return bill_length_min < penguin.bill_length_mm &&
         islands.includes(penguin.island);
})

Outline

~~Summarise FAIR principles and reproducible research (Nick)~~
~~Talk about Quarto, one tool in your toolkit (Unai)~~
break
Show you how to make a presentation in Quarto (Nick)
Compare PowerPoint and Quarto (Jan)
Demo creating and updating slides in realtime using GitHub Actions (Jan)
Questions (you)

Posit.cloud

We will be using Posit.cloud (Rstudio.cloud) after the break
If you don’t have an account, please set one up in the break
I will be around if you have questions
Poll - who has used R or RStudio before (even just a little bit)? Yes | No

During the Break:

Go to https://login.posit.cloud/
Click Sign Up
fill out form
Click Sign Up
Choose Posit Cloud
verify email in your inbox

click Continue
Click New Project -> New RStudio Project
It should look like the image in the top right!

08:00

Creating a Quarto slidedeck

I will do a short demo (~4 min) about creating and updating a Quarto slide deck in RStudio Cloud. You do not need to follow along.
Then I will split the group into breakout rooms (3-4 per room) and you can try it yourselves (for about 15 min).
Instructions are on the next slides

Demo 1

This is your RStudio window:

Demo 2

Choose: File > New File > Quarto Presentation…

give it a title, e.g. “Presentation”
click Create
this is your presentation

Demo 3

We are in Visual mode - you can type in and see changes in real time.
Slide list is on the right.
To add a slide, type in some text.
Set it to Header 2 - you will see it appear in the list.
Can do Visual mode or Source mode.

You can make changes in either and both will update.

Demo 4

To see the slides we need to Render
This converts the Quarto code to slides you can look and and share (in HTML, you can also export as PDF).
Before we do this, we have an issue:

Click Install to install the library.
Then click
Slides will open in a new window.

Now try on your own!

Any questions before we start?
Then I will split the group into breakout rooms (3-4 per room) and you can try it yourselves. You have ~15 min.
Try some of the codes Unai introduced
Check out these links for more ideas:
- https://quarto.org/docs/get-started/hello/rstudio.html
  - https://quarto.org/docs/presentations/
You can do this on RStudio Cloud or your own copy of RStudio
- You will need to download and install Quarto CLI:
- https://quarto.org/docs/get-started/
- Can also run in VS Code, Jupyter, Neovim or Text Editor

15:00

When to use Quarto?

Strengths & Weaknesses of Quarto for teaching

Strengths 💪

Consistency in Output
- Focus on content
Support for (Explicit) Version Control (e.g. git)
Great for Code (in Slides)
Automation / Generated Contents
Interactivity

Weaknesses 😢

Harder to do fine layouting
- No WYSIWYG
New Syntax to learn
Software Maturity

Key Benefit: (Explicit) Version Control

Going back through time
Great for collaboration
Allow sharing and adaptation
- Just like this presentation
Allows automation

Demo: Course Alumni 🎉

Let’s check out these slides right here
Course Alumni
- Anandhi
- Elen
- Fritjof
- Heidi
- Helene
- Sarah
- Sven
- Tina
- Vinodh
- Yeganeh

Additional Resources

The Turing Way handbook to reproducible, ethical and collaborative data science
Richard McElreath (2020). Science as amateur software development. YouTube
Quarto
- Quarto Documentation
- Quarto for Academics by Mine Çetinkaya-Rundel
Version Control
- Version Control Book
- https://github.com/git-guides

Thank you! 🙏

💻 Slides: Slides are publicly available at github.com/jansim/dra-reproducible-materials

📦 Software: Reproducible slides build with Quarto and deployed to GitHub Pages using GitHub Actions (details in the Quarto docs)

Source: Source code is available at github.com/jansim/dra-reproducible-materials

🖲️ DOI: (generated using GitHub + Zenodo, see GitHub docs)

License: Creative Commons Attribution 4.0 International (CC BY 4.0)

💬 Contact: We welcome any feedback via email or GitHub issues. Thank you!