14  Quarto

14.1 General

14.1.1 YAML formats

Comprehensive guide to Quarto

14.1.2 Chunk options

Chunk options are now specified inside the r backtics, with the following syntax:

#| echo: false
#| warning: false

To specify these options globally, they need to be added to the _quarto.yml file, with these lines:

execute:
   echo: false
   warning: false

14.1.3 Figures

To be included in the quarto figure environment, a figure must have a label that starts with fig-. You can specify the caption as well as the output height/width (in inches) as follows:

```{r}
#| label: fig-1
#| fig-cap: "A Basic Barplot Figure"
#| fig-height: 6
#| fig-width: 6

ggplot(data, aes(x=name, y=value)) + 
  geom_bar(stat = "identity")
```

To display a code-generated figure without the caption, the label CANNOT start with fig-.You must also remove the #| fig-cap: option from the chunk, and explicitly include a height and/or width specification, this time using out-width and out-height:

```{r}
#| label: a-fig-1
#| out-width: 6in
#| out-height: 6in

ggplot(data, aes(x=name, y=value)) + 
  geom_bar(stat = "identity")
```

14.1.4 Tables

14.1.4.1 HTML

Plain knitr::kable() renders a nicely striped table in HTML:

Make Model Miles Per Gallon Cylinders Gears
Mazda RX4 21.0 6 4
Mazda RX4 21.0 6 4
Datsun 710 22.8 4 4
Hornet 4 21.4 6 3
Hornet Sportabout 18.7 8 3

However, when you call kableExtra, it does away with the nice striping and spacing and you then have to define that explicitly!

Make Model Miles Per Gallon Cylinders Gears
Mazda RX4 21.0 6 4
Mazda RX4 21.0 6 4
Datsun 710 22.8 4 4
Hornet 4 21.4 6 3
Hornet Sportabout 18.7 8 3

Note the table above, although the code is identical to the first table, has lost all formatting thanks to invoking kableExtra. The table below re-produces that via kable_styling (with additional features such as floating around text, and footnotes; although it seems the float doesn’t actually work!).

Make Model Miles Per Gallon Cylinders Gears
Mazda RX4 21.0 6 4
Mazda RX4 21.0 6 4
Datsun 710 22.8 4 4
Hornet 4 21.4 6 3
Hornet Sportabout 18.7 8 3
Note:
Here is a general comments of the table.
1 Footnote 1;
2 Footnote 2;
a Footnote A;
b Footnote B;
* Footnote Symbol 1;
† Footnote Symbol 2

Additional HTML-only features of kableExtra are documented here

14.1.4.2 PDF

If using the typst APAish manuscript extension, note that Quarto 1.4XXX uses an older version of Typst without good table support. That should be fixed in the 1.5 release.

The documentation for producing LaTeX tables in kableExtra is here

The following two tables demonstrate a complex table of the type used in the PDF ema and burden papers (here replicated with a far simpler dataset). This first table is the table code as extracted directly from the manuscript, with no additional formatting. It displays not unlike an HTML table:

Iris
N %
Setosa
large NA NA
small 50 0.3
Versicolor
large 43 0.3
small 7 0.0
Virginica
large 50 0.3
small NA NA
Note:
N = 75

In LaTeX, this table displays quite differently. Below, the same code has been modified to reproduce exactly the look of the table as it appears in the PDF manuscript. That is, the code in the chunk above produces the output below when rendered with knitr to PDF; but rendering that output to HTML requires the additions in the chunk below:

  • bootstrap_options = "none" added to kable_styling removes the default horizontal lines, under each row, but then font size and table width must now be specified.
  • pack_rows() adds horizontal lines in HTML but not LaTeX; those must be removed with the label_row_css option .
  • Finally, column width is specified, and horizontal lines around the column headers and before the footnote, are added with row_spec()’s extra_css option.
Iris
N %
Setosa
large
small 50 0.3
Versicolor
large 43 0.3
small 7 0.0
Virginica
large 50 0.3
small
Note:
N = 75

14.1.4.3 Useful Table Options and features

To be sure tables display with NA cells as blanks (instead of “NA”) include this before your first table:

options(knitr.kable.NA = "")

kableExtra has a function is collapse_rows, yet that seems to be persistently broken

row_spec() has a parameter, hline_after, which, ostensibly, should create a horizontal line under that row, right? Apparently it only works on LaTeX although this is undocumented. Apparently the solution is to add row_spec(X, extra_css = "border-bottom: 1px solid")) (where x is the rownum; 0 for the header, nrow(df) for the last row)

Similarly, to supress hlines on headers created by pack_rows(), you need to add extra_css = "border-bottom: none" into the pack_rows() command.

14.1.5 Rendering

For rendering books and slides, we have written a bash script to handle setting the _quarto.yml file and then rendering the full project or a single file.

  • call the function from the terminal: ./render.sh filename.qmd book
  • the first parameter can be the name of the qmd file or all to render all units (only used for books, not slides)
  • the second parameter can be book, slides or slides_wide

14.1.5.1 Full book/website rendering

For books and websites, which have many .qmd documents linked together, you would render the full book by calling quarto::quarto_render() to render all documents in the active project directory.

For books and websites, if anything changes in the .yml file (such as addition or deletion of a chapter), you MUST re-render the entire directory in this manner, otherwise the added/deleted chapter will not be rendered correctly.

14.1.5.2 Rendering other formats and targets

You can specify render targets and document render ordering more specifically in project metadata, see https://quarto.org/docs/projects/quarto-projects.html#render-targets

14.1.5.3 PDF

You can specify rendering to PDF format by adding the following to your .yml file:

format: pdf: documentclass: book

You can then explictly render just the PDF format by specifying both the output format and the filename in the call to quarto_render:

quarto::quarto_render(output_format = “pdf”,output_file = “dwt.pdf”)

14.1.5.3.1 PDF Fonts

To specify a font you add the following to the YAML:

If using Xelatex:
mainfont : FontName # for document text
sansfont : FontName # for H1-H6 text
monofont : FontName # for code chunk text

If using pdflatex:
fontfamily : FontName # for document text

Where FontName is the name of your desired system font. To find available system fonts, run, systemfonts::system_fonts() and look for the name of the font (not the name of the font .tff file). For example, if you wish to use Arial font, your FontName should be “ArialMT”, rather than “arial” or “Arial”.

14.2 Documents

We use Quarto documents for two purposes - reproducible analyses and submitted papers. We will generally render analysis doc to html and papers to pdf. The Quarto Guide provides more detail on on creating pdf and html

These documents are styled primarily using Markdown. The Quarto Guide provides more detail on markdown basics

14.3 Journal Articles

14.3.1 Templates

Quarto does have a system for applying journal article templates to quarto docs, see this reference page

The list of available templates is still somewhat small, but extending them seems doable.

Related reference links for creating an AJP template:

14.3.2 Bibliographies

To add a bibliography with a citation style, add the following lines to the _quarto.yml or the .qmd file:

bibliography: references.bib
csl: name_of_csl_file.csl

For a typst APAish manuscript your yaml will look like this to use the built-in typst citation style:

bibliography: references.bib
bibliographystyle: apa

Or download a local copy of the desired .csl file:
bibliography: references.bib
bibliographystyle: name_of_csl_file.csl

At the moment, this extension doesn’t support linking to the CSL repo (below).

Note, we will typically call our csl files from the official Citation Style Language Repo; which simply requires the URL of the raw file from github.

See docs_arc for specifics about commonly-used ARC csl files.

The Quarto Guide provides more detail about how to work with citations and footnotes. As with markdown, the format is [@citekey1; @citekey2] — citations go inside square brackets and are separated by semicolons

14.4 Reproducible Analyses

14.5 Presentations

We use Quarto to make revealjs slide decks for presentations. The Quarto Guide provides extensive documentation and sample slides. You can begin with the overview of presentations across formats (Quarto can also render powerpoint and other formats). Follow this with a revealjs overview and then the revealjs reference chapter. The Quarto Guide also provides a chapter on presenter tools.

Divs (:::) and spans([]) are used extensively in presentations. An introduction to their use is provided in the markdown basics chapter. The Pandoc manual provides more detail.

In a project, presentations should be located in subfolder that starts with an underscore, ie. _presentations, to prevent those files from being rendered during the project render.

14.6 Books and Websites

Information on setting up a book: https://quarto.org/docs/books/

Information on setting up a website: https://quarto.org/docs/websites/

Information on setting up Github Pages to publish a book/website on commit: https://quarto.org/docs/publishing/github-pages.html#render-to-docs

The difference between a book and a website in quarto is the syntax in the _quarto.yml file. Books have chapters, websites have sections; there are also a few differences in the types of metadata options you can specify (for example, books have titles and authors, websites do not). The main visible difference in the published output is that book chapters are numbered, while website sections are not.

14.7 Publishing

You can publish documents, books, and presentations to a variety of places.

14.7.1 Presentations and Documents

Our preferred location for presentations (and Quarto Docs) is Quarto Pub. This site is public and free. To use it, you need to set up an account first.

To publish a presentation (or other Quarto doc) to Quarto Pub, you should first log in on your default browsers. You should next go to the Terminal tab in the RStudio IDE. Navigate to the folder that contains your presentation. Then type quarto publish quarto-pub. If this is the first time you are publishing at Quarto Pub on that computer, you will need to authorize it. Follow the prompts in the web browser and then in the terminal to complete the publication process. This authorization is saved in a file called _publish.yml, which will be accessed for future updates to the presentation.

See additional instructions in the Quarto guide if necessary.

14.7.2 Books and Websites

We have chosen to use Github Pages to publish several of our books. See this link for detailed information on setting up your repo to have a Github Page and to use Github Actions to publish.

Basically, any commit which includes changed html files tells Github Actions to re-build the book. The publishing workflow therefore consists of a) rendering locally, and b) committing the newly-rendered documents via github desktop. It usually takes <2 minutes for Github Actions to build and deploy the updated pages

14.8 Terminal Commands

  • quarto publish quarto-pub to publish a presentation or document to Quarto Pub
  • quarto render filename.qmd --to pdf
  • quarto render filename.qmd --to html
  • quarto render docname.qmd -o outputname.html
  • quarto render docname.qmd -P pv1:1 -P pv2:5
  • /opt/quarto/"${QUARTO_VERSION}"/bin/quarto check to check installation details

14.9 Latex and Quarto

Formatting of a PDF rendered from Quarto can be finely controlled with the addition of LaTeX commands. See this Quarto reference as well as some examples below:

14.9.1 Inline Commands

Certain latex commands can be placed in qmd files as plaintext (on their own line, with surrounding blank lines), for example: \newpage starts a new page, \hline adds a horizontal line.

14.9.2 Chunk Commands

Multiline commands can be wrapped in latex code chunks:

14.9.3 YAML

\raggedright added to the include-in-header YAML command, ensures lines are flush with the left margin and ragged on the right margin (vs justified where text is stretched to ensure both margins are flush)

We wuse the following in the YAML header to set up a html document to render as a single file with a TOC.

format: 
  html: 
    embed-resources: true
    toc: true 
    toc_depth: 4

14.9.4 Packages

\usepackage{wrapfig} - allow text wrapping \usepackage{float} - allow use of float options such as H (use UPPERCASE to preserve floats) \usepackage{caption} - allows supression of automatic caption numbering \usepackage{lscape} - allows insertion of a landscape oriented page \usepackage{enumitem} - allows fine-grain control over list styling

14.9.5 Re-render and freeze

https://quarto.org/docs/projects/code-execution.html

14.10 Using Parameters

You define parameters in the YAML using the syntax below

  • You can assign initial values to the parameters. These values will be used by default if you do not replace them with new values from the command line when you render the script.
  • You can update these values with new values you pass in when you render the script (see below).
  • If you only provide a subset of updated parameter values when you render the document, the default values will be used for the remaining parameters.
params:
  pv1: 5
  pv2: 10

In some instances, I prefer to assign the values from the params list to individual variables

  • Code is shorter when using these variables
  • I can update them interactively if I want to use different values (the params list is read-only)

First set the parameters in the YAML as above. Then put this code chunk right at the top of the script. If you edit this code chunk to assign new values interactively, make sure you comment it out when you save the final script!

pv1 <- params$pv1
pv2 <- params$pv2
# pv1 <- 5 # Use this line to interactively assign new value
# pv2 <- 10 # use this line to interactively assign new value

14.10.1 Using parameter values

When you use params in the YAML, a list named params is created.

  • You can then use this list as normal with no further code needed to establish the values.
params$pv1 + params$pv2
  • You can also access these values using inline r statements. See example below. I strongly recommend using this in the title of your document so that you can confirm that you correctly updated the parameter values when you rendered! e.g.,
title: "Demo of quarto document with pv1 = `r params$pv1` and  pv2 = `r params$pv2`."
  • Or if you assigned the parameter values to variables as I recommended, you can just use those variables as you normally would. They will start with the values assigned to associated parameters (in YAML or input from command line)

14.10.2 Passing parameter values at command line

I prefer to render quarto documents in the terminal.

  • You can indicate the output filename (otherwise, the output file name is set to the input filename with a different extension).
  • You can also pass in values to the parameters, which is typically why we use parameters in the first place

Use the following syntax to render quarto documents at command line.

  • use -P to provide a parameter value. No space between parameter name and value. If you provide values for only a subset of parameters, defaults will be used for other parameters
  • use -o to specify filename (defaults to input filename if not provided).
quarto render docname.qmd -o outputname.html  -P pv1:1 -P pv2:5

14.11 Manuscript Projects

As of 2024 our preferred method for creating reproducible analysis is to have a quarto project for each study.

A project allows you to connect a website, presentations (both slidesets and posters), and PDFs/word documents to a set of analysis notebooks (formerly our ana_.Rmd files). That way, code across all output formats can be updated simultaneously from a single location. Plots and charts can also be produced from these notebooks, which can them be used across multiple output document formats.

Please note that most of the documentation on John’s Data Wrangling quarto page was written when we were creating each format type as a standalone. This information is still valid for that workflow. Differences related to projects will be noted in the appropriate section on that page.

Here are steps to set up a manuscript project:

  1. Create study repo for project on github in John’s account (call it study_NAME)
  2. Add collaborators to the repo
  3. Clone the repo to your computer
  4. Create manuscript project files in the repo. In the terminal (in github folder above new repo) type quarto create project manuscript and then indicate the name of the repo folder when asked
  5. Add a gh-pages branch to the repo. Do this in terminal with these commands
  • git switch --orphan gh-pages
  • git commit --allow-empty -m "Initial commit on orphan branch"
  • git push -u origin gh-pages
  1. Set up github to publish website from the gh-pages branch. Go to settings, pages, and select the gh-pages and /root as the branch to publish from. The website will be published at https://jjcurtin.github.io/study_NAME

14.12 Quarto Templates

All of the following templates are quarto files for use in creating lab-related documentation

  • Simple Quarto Template. This simple template allows you to set margins/font and to switch from HTML to PDF output.

14.12.1 YAML files

Including these YAML files in a blank .qmd document sets up output for either HTML or PDF, tailored to ARC standards with respect to margins, font, etc.

TBD (CONTENTS NEED TO BE ADDED TO THESE FILES)

14.12.2 Manuscripts

14.12.2.1 APA

.qmd template. This is based on the template at this repo. Our version is currently under development to try and load assets from our lab_support repo rather than installing the extention files locally.

14.12.2.2 CSL files

Below are the YAML code of a couple that we use frequently (linked to the primary CSL repo)

NIH Grant Proposals:
csl: https://raw.githubusercontent.com/citation-style-language/styles/master/national-library-of-medicine-grant-proposals.csl

Elsevier (Vancouver substyle):
csl: https://raw.githubusercontent.com/citation-style-language/styles-distribution/f8524f9b9df60e94e98f824f242a1fb27cc9fc59/elsevier-vancouver.csl

APA 7th Edition:
csl: https://raw.githubusercontent.com/citation-style-language/styles/master/apa.csl

Note: the apa quarto template in the lab_support repo calls its own version of the apa.csl from within its ex_apa support folder.

14.13 letterhead

Letterhead: .qmd template. See Susan or John for assistance in personalizing this for other lab members.