Introduction to literate programming and setting up Quarto

David Schoch

GESIS

2023-06-19

“Let us change our traditional attitude to the construction of programs. Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.” [Donald Knuth]

Literate Programming
Mixing a document formatting language and a programming language.

Why use literate programming?

• Enhanced Readability
  Emphasizes clear and coherent documentation alongside the code

• Improved Documentation
  Documentation is an integral part of the program

• Code Reusability
  Simpler to extract and adapt code components for use in other projects

• Education and Learning
  can serve as an effective educational tool

Why use literate programming as an academic?

Convenience

Reproducibility

Convenience

common academic workflow:

• write paper in Word, LaTeX, …
  (changing format is tideous)

• analysis with some software package, “copy” results to paper
  (changing data/code means manually changing tables/figures)

• make presentation with PowerPoint, LaTeX, …

literate programing can unify writing and analysis
(and Quarto also presenting!)

Reproducibility

(simplified view)

• complete and self-contained paper that includes both code and documentation

• no need to publish code and data separately

History

(focusing on R/Python ecosystems)

Sweave - Early R and Latex integration (2002)
Pandoc - convert between different document formats (2006)
knitr - convenient extension to Sweave (2012)
RMarkdown - knitr extension based on Pandoc (~2014)
Jupyter Notebooks - anything with a jupyter kernel (~2014)
Quarto - Next generation RMarkdown (~2022)

What is Quarto?

open-source scientific and technical publishing system built on Pandoc

Quarto is a command line interface (CLI) that renders plain text formats (.qmd, .rmd, .md) OR mixed formats (.ipynb/Jupyter notebook) into static documents (Word, PDF, HTML,…), websites, presentations, books and much more!

“The concept is to make a major, long term investment in reproducible research, while keeping it compatible with existing formats and adaptable to the various environments users work in.”

Working with Quarto

Quarto is independent of R and RStudio

You can use your favorite editor:

• RStudio

• VS Code

• Jupyter Lab

• Neovim

• any other text editor + terminal

Best support for RStudio and VS Code

How Quarto works

• knitr or jupyter evaluate code and return an md file

• Quarto applies Lua filters + CSS/LaTeX and Pandoc converts to a final ouput format

Quarto vs RMarkdown

RMarkdown grew into a large ecosystem, with varying syntax.

Basic: html_document, pdf_document, word_document
Beamer: beamer_presentation
PowerPoint: powerpoint_presentation
HTML Slides: xaringan, ioslides, revealjs
Advanced layouts: tufte
Websites: blogdown, distill, pagedown
Books: bookdown
Journal Articles: rticles

Quarto supports (most of) these out of the box

Should I switch?

Yes:

• “Batteries included”, shared syntax

• Choose your own editor and your preferred language

• Better accessibility and richer features out of the box

• More enhancements overtime

No:

• RMarkdown will still be maintained

• If you cherish your workflow

need convincing?

Interactive Documents
Shiny, Observable JS, widgets

Extensions
shortcodes, filters, journal articles, custom formats, revealjs Examples

Publishing
quarto publish (e.g. Github pages) with continuous integration

Setting up Quarto