5 Quarto

5.1 Using Quarto

For general info on using quarto, visit John’s Data Wrangling quarto page.

5.2 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:

Create study repo for project on github in John’s account (call it study_NAME)
Add collaborators to the repo
Clone the repo to your computer
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
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

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

5.3 Checking installation details

/opt/quarto/"${QUARTO_VERSION}"/bin/quarto check in the terminal

5.4 Assigning values to 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

For a variety of reasons, 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

5.5 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

[1] 15

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)

5.6 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

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