quarto-for-reporting

Quarto for Reproducible Publications

Jeremy Allen

These Slides!

2023-02-14

So what is Quarto?

Quarto® is an open-source scientific and technical publishing system built on Pandoc
Batteries included, shared syntax across output types and languages
Choose your own editor and your preferred data science language
RMarkdown still maintained, but majority of new features built into Quarto

So what is Quarto?

quarto is a language agnostic command line interface (CLI)

jeremyallen$ quarto --help

  Usage:   quarto 
  Version: 1.3.197

  Description:

    Quarto CLI

  Options:

    -h, --help     - Show this help.                            
    -V, --version  - Show the version number for this program.  

  Commands:

    render          [input] [args...]     - Render files or projects to various document types.        
    preview         [file] [args...]      - Render and preview a document or website project.          
    serve           [input]               - Serve a Shiny interactive document.                        
    create          [type] [commands...]  - Create a Quarto project or extension                       
    create-project  [dir]                 - Create a project for rendering multiple documents          
    convert         <input>               - Convert documents to alternate representations.            
    pandoc          [args...]             - Run the version of Pandoc embedded within Quarto.          
    run             [script] [args...]    - Run a TypeScript, R, Python, or Lua script.                
    add             <extension>           - Add an extension to this folder or project                 
    install         [target...]           - Installs an extension or global dependency.                
    publish         [provider] [path]     - Publish a document or project. Available providers include:
    check           [target]              - Verify correct functioning of Quarto installation.         
    help            [command]             - Show this help or the help of a sub-command.

RMarkdown for literate programming

Quarto for literate programming

diagram of converting a Qmd document via knitr/pandoc into markdown and then into output formats

Quarto for literate programming

diagram of converting a Quarto document via Jupyter/pandoc into markdown and then into output formats

diagram of converting a Jupyter notebook via pandoc into markdown and then into output formats

What does Quarto look like in the RStudio IDE?

Quarto - Visual Editor

A snippet of an RStudio window showing the options bar at the top of an RMarkdown document.

Format	Insert	Table

Static documents

A static document is your “daily driver” - has the power for a complex table of contents, figure alignment, control of ouptut/code, and other niceties
Useful as a lab notebook, scratchpad, or the final output for your team
Most powerful as the combination of written thoughts and observations along with source code

Parameters

You may have a set of parameters that are used to create different variations of a report. For example:

Showing results for a specific geographic location.
Running a report that covers a specific time period.
Running a single analysis multiple times for different assumptions.

Parameters

Python - Papermill style

#| tags: [parameters]
alpha = 0.1
ratio = 0.1

str(alpha)

R - YAML style

---
title: "My Document"
params:
  alpha: 0.1
  ratio: 0.1
---

str(params$alpha)

CLI/Terminal

quarto render doc.qmd -P alpha:0.2 -P ratio:0.3

Render with Parameters

---
title: "Penguins"
date: today
format: html
params:
  species: Adelie
---

```{r}
#| label: setup
#| include: false
library(tidyverse)
library(palmerpenguins)
penguin_filter <- penguins |>
  filter(species == params$species,
    !is.na(body_mass_g))
diff_rows <- nrow(penguins) - nrow(penguin_filter)
```

We have data about `r nrow(penguins)` penguins. Only
`r diff_rows` are classified as `r params$species`. 
The distribution of the `r params$species` penguins 
are shown below:

```{r}
#| echo: false
penguin_filter |>
  ggplot(aes(body_mass_g)) +
  geom_histogram(binwidth = 100)
```

A screenshot of the output report, displaying the title, date, information about the penguins and a basic histogram.

Render with Parameters

quarto render penguin-report.qmd -P species:Gentoo --output gentoo-report.html
quarto render penguin-report.ipynb -P species:Gentoo --output gentoo-report.html

render_fun <- function(penguin){
  quarto::quarto_render(
    input = "penguin-report.qmd",
    execute_params = list(species = penguin),
    output_file = glue::glue("{penguin}-report.html")
  )
}
unique(penguins$species) |>
  as.character() |> 
  purrr::walk(render_fun)

Output created: Adelie-report.html
Output created: Chinstrap-report.html
Output created: Gentoo-report.html

PDF Articles

format:
  pdf:
    template: mytemplate.tex

See more on Journal Articles at https://github.com/quarto-journals/

---
title: "My Document"
toc: true
format:
   acm-pdf: default
   acm-html: default
---

Screenshot of a rendered Quarto document to the Journal of Statistical Science format.

Take 5!

Enjoy the music :)

Then demo!

More PDF + LaTeX templates

Great work from the NFMS Open Science team on “Quarto titlepages”: https://nmfs-opensci.github.io/quarto_titlepages/

The tex templates were written by Eli Holmes and the lua filter along with changes to the Pandoc templates to allow themes was written by Mickaël Canouil. . . .

A screenshot of the titlepages Quarto output PDF. It has a logo, along with the title information and the affiliations of the authors.

Quarto resources

General Quarto

Quarto Gallery

Quarto can produce a wide variety of output formats.

Here are some examples:

https://quarto.org/docs/gallery/