Producing Reports With Quarto
Last updated on 2024-11-19 | Edit this page
Overview
Questions
- How can I integrate software and reports?
Objectives
- Understand the value of writing reproducible reports
- Learn how to recognise and compile the basic components of an Quarto file
- Become familiar with R code chunks, and understand their purpose, structure and options
- Demonstrate the use of inline chunks for weaving R outputs into text blocks, for example when discussing the results of some calculations
- Be aware of alternative output formats to which a Quarto file can be exported
Data analysis reports
Data analysts tend to write a lot of reports, describing their analyses and results, for their collaborators or to document their work for future reference.
Many new users begin by first writing a single R script containing all of their work, and then share the analysis by emailing the script and various graphs as attachments. But this can be cumbersome, requiring a lengthy discussion to explain which attachment was which result.
Writing formal reports with Word or LaTeX can simplify this process by incorporating both the analysis report and output graphs into a single document. But tweaking formatting to make figures look correct and fixing obnoxious page breaks can be tedious and lead to a lengthy “whack-a-mole” game of fixing new mistakes resulting from a single formatting change.
Creating a report as a web page (which is an html file) using Quarto makes things easier. The report can be one long stream, so tall figures that wouldn’t ordinarily fit on one page can be kept at full size and easier to read, since the reader can simply keep scrolling. Additionally, the formatting of a Quarto document is simple and easy to modify, allowing you to spend more time on your analyses instead of writing reports.
Callout
You might also have heard about R Markdown as a literate
programming tool. In a lot of ways, Quarto is the next-generation
version of R Markdown with more advanced features and multi-language
support. However, at its core, Quarto still works the same as R Markdown
when it comes to R-based documents and R Markdown files
(.Rmd
) are still compatible with Quarto. Much of what we
cover in this episode is thus also valid for traditional R Markdown
files.
Literate programming
Ideally, such analysis reports are reproducible documents: If an error is discovered, or if some additional subjects are added to the data, you can just re-compile the report and get the new or corrected results rather than having to reconstruct figures, paste them into a Word document, and hand-edit various detailed results.
The key R package here is knitr
. It allows you
to create a document that is a mixture of text and chunks of code. When
the document is processed by knitr
, chunks of code will be
executed, and graphs or other results will be inserted into the final
document.
This sort of idea has been called “literate programming”.
When rendering a document, knitr
will execute the R code
in each chunk and creates a new markdown (.md
) document,
which will include both the regular text and output from the executed
code chunks. This markdown file is then converted to the final output
format with pandoc. This whole process
is handled for you by the Render button in the RStudio IDE.
Creating a Quarto document
Within RStudio, click
File → New File → Quarto document...
and you’ll get a
dialog box like this:
You can stick with the default (HTML output), but give it a title.
Basic components of R Markdown
The initial chunk of text (header) contains instructions for Quarto
to specify what kind of document will be created, and the options
chosen. You can use the header to give your document a title, author,
date, and tell it what type of output you want to produce. In this case,
we’re creating an html
document.
You can delete any of those fields if you don’t want them included. The double-quotes aren’t strictly necessary in this case. They’re mostly needed if you want to include a colon in the title.
RStudio creates the document with some example text to get you started. Note below that there are chunks like
{verbatim} ```{r} 1 + 1 ```
These are chunks of R code that will be executed by
knitr
and replaced by their results. More on this
later.
Markdown
Markdown is a system for writing web pages by marking up the text much as you would in an email rather than writing html code. The marked-up text gets converted to html, replacing the marks with the proper html code.
For now, let’s delete all of the stuff that’s there and write a bit of markdown.
You make things bold using two asterisks, like this:
**bold**
, and you make things italics by using
underscores, like this: _italics_
.
You can make a bulleted list by writing a list with hyphens or asterisks with a space between the list and other text, like this:
MARKDOWN
A list:
* bold with double-asterisks
* italics with underscores
* code-type font with backticks
or like this:
MARKDOWN
A second list:
- bold with double-asterisks
- italics with underscores
- code-type font with backticks
Each will appear as:
- bold with double-asterisks
- italics with underscores
- code-type font with backticks
You can use whatever method you prefer, but be consistent. This maintains the readability of your code.
You can make a numbered list by just using numbers. You can even use the same number over and over if you want:
This will appear as:
- bold with double-asterisks
- italics with underscores
- code-type font with backticks
You can make section headers of different sizes by initiating a line
with some number of #
symbols:
You compile the R Markdown document to an html webpage by clicking the “Render” button in the upper-left. Or using the keyboard shortcut Shift+Ctrl+K on Windows and Linux, or Shift+Cmd+K on Mac.
Challenge 1
Create a new Quarto document. Delete all of the R code chunks and write a bit of Markdown (some sections, some italicized text, and an itemized list).
Convert the document to a webpage.
In RStudio, select
File > New file > Quarto Document...
Delete the placeholder text and add the following:
MARKDOWN
# Introduction
## Background on Data
This report uses the *gapminder* dataset, which has columns that include:
* country
* continent
* year
* lifeExp
* pop
* gdpPercap
## Background on Methods
Then click the ‘Render’ button on the toolbar to generate an html document (webpage).
A bit more Markdown
You can make a hyperlink like this:
[Carpentries Home Page](https://carpentries.org/)
.
You can include an image file like this:
![The Carpentries Logo](https://carpentries.org/assets/img/TheCarpentries.svg)
You can do subscripts (e.g., F2) with F~2~
and superscripts (e.g., F2) with F^2^
.
If you know how to write equations in LaTeX, you can use
$ $
and $$ $$
to insert math equations, like
$E = mc^2$
and
$$y = \mu + \sum_{i=1}^p \beta_i x_i + \epsilon$$
which will show as
\[y = \mu + \sum_{i=1}^p \beta_i x_i + \epsilon\]
You can review Markdown syntax by navigating to the “Markdown Quick Reference” under the “Help” field in the toolbar at the top of RStudio.
R code chunks
The real power of Quarto comes from mixing markdown with chunks of code. When processed, the R code will be executed; if they produce figures, the figures will be inserted in the final document.
The main code chunks look like this:
{verbatim} ```{r} #| label: load_data gapminder <- read.csv("gapminder.csv") ```
That is, you place a chunk of R code between ```{r}
and
```
. You should give each chunk a unique name, by inserting
the line #| label: label_name
as they will help you to fix
errors and, if any graphs are produced, the file names are based on the
name of the code chunk that produced them. You can create code chunks
quickly in RStudio using the shortcuts
Ctrl+Alt+I on Windows and Linux, or
Cmd+Option+I on Mac.
In R Markdown, you add chunk labels by including them within the
```{r}
line like so:
{verbatim} ```{r label_data} gapminder <- read.csv("gapminder.csv") ```
Challenge 2
Add code chunks to:
- Load the ggplot2 package
- Read the gapminder data
- Create a plot
{verbatim} ```{r} #| label: libraries library(ggplot2) ```
{verbatim} ```{r} #| label: load-gapminder-data gapminder <- read.csv("gapminder.csv") ```
{verbatim} ```{r} #| label: make-plot plot(lifeExp ~ year, data = gapminder) ```
How things get compiled
When you press the “Render” button, the Quarto document is processed
by knitr
and a plain
Markdown document is produced (as well as, potentially, a set of figure
files): the R code is executed and replaced by both the input and the
output; if figures are produced, links to those figures are
included.
The Markdown and figure documents are then processed by the tool pandoc
, which converts the
Markdown file into an html file, with the figures embedded.
Chunk options
There are a variety of options to affect how the code chunks are treated. Here are some examples:
- Use
echo=FALSE
to avoid having the code itself shown. - Use
results="hide"
to avoid having any results printed. - Use
eval=FALSE
to have the code shown but not evaluated. - Use
warning=FALSE
andmessage=FALSE
to hide any warnings or messages produced. - Use
fig.height
andfig.width
to control the size of the figures produced (in inches).
So you might write:
{verbatim} ```{r} #| label: load_libraries #| echo: false #| message: false library(dplyr) library(ggplot2) ```
Often there will be particular options that you’ll want to use repeatedly; for this, you can set global chunk options in the files YAML header like so:
YAML
---
...
knitr:
opts_chunk:
message: false
warning: false
echo: false
results: "hide"
fig.path: "Figs/
fig.width: 11
---
The fig.path
option defines where the figures will be
saved. The /
here is really important; without it, the
figures would be saved in the standard place but just with names that
begin with Figs
.
If you have multiple R Markdown files in a common directory, you
might want to use fig.path
to define separate prefixes for
the figure file names, like fig.path="Figs/cleaning-"
and
fig.path="Figs/analysis-"
.
Challenge 3
Use chunk options to control the size of a figure and to hide the code.
{verbatim} ```{r} #| label: faitful-plot #| echo: false #| fig.width: 3 plot(faitful) ```
You can review all of the R
chunk options by navigating
to the “R Markdown Cheat Sheet” under the “Cheatsheets” section of the
“Help” field in the toolbar at the top of RStudio.
Inline R code
You can make every number in your report reproducible. Use
`r
and `
for an in-line code chunk, like so:
``r "r round(some_value, 2)"``
. The code will be executed
and replaced with the value of the result.
Don’t let these in-line chunks get split across lines.
Perhaps precede the paragraph with a larger code chunk that does
calculations and defines variables, with include=FALSE
for
that larger chunk (which is the same as echo=FALSE
and
results="hide"
).
Challenge 4
Try out a bit of in-line R code.
Here’s some inline code to determine that 2 + 2 =
r 2+2
:
{verbatim} Here's some inline code to determine that 2 + 2 = `r 2+2`:
Other output options
You can also convert R Markdown to a PDF or a Word document. Change
the format:
field in the YAML header to pdf
or
docx
. For an overview of all the available output formats,
see the Quarto
documentation
Parameterised reports
Literate programming with tools like Quarto and R Markdown is very powerful in that it allows you to generate analysis reports in a reproducible manner. This makes it very easy to update your work and alter the input parameters within the report You can take this one step further, by parametrising the reports themselves. This is very useful in a number of cases, for example:
- Running the same analysis on different datasets
- Generating multiple reports for different groups of the data (e.g. geographic location or time periods)
- Controlling the
knitr
options; e.g. you might want to show the code in some reports but not in others
Including parameters in a Quarto document
Including parameters in a Quarto document (or R Markdown, which
follows the same syntax) can be done by adding the params
field to they YAML header. This field can hold a list of multiple
parameters.
For example, imagine we want to analyse the life expectancy of
different countries, using the gapminder
dataset, but we
want a separate report for each country. To achieve this, we set the
YAML header for our Quarto document as follows:
YAML
---
title: "Life Expectancy Report"
format: html
execute:
echo: false
warning: false
message: false
params:
country: "Afghanistan"
---
We can then reference this parameter anywhere in the R code in our
report by accessing the params
object. To calculate the
life expectancy for just the country defined by the params
,
we can do:
`{verbatim}
{r} library(tidyverse) library(gapminder)
```{r}
life_expectancy <-
gapminder |>
select(country, year, lifeExp) |>
filter(country == params$country)
The last line in the code chunk above uses the `params` object to filter the `gapminder` dataset.
Note that we can also `params` in inline R code snippets. So we can generate a heading that will
change based on the country parameter:
````{verbatim}
## Life Expectancy in `r params$country`
```{r}
#| label: !expr paste0("life-expectancy-plot", params$country)
ggplot(life_expectancy, aes(year, lifeExp)) +
geom_line() +
theme_minimal()
```
In fact, we can even use this in the main document title in the YAML header, as it also accepts R code expressions:
Rendering Quarto documents from within R
Of course, manually editing the YAML header every time you want to
generate a report isn’t much better than manually editing the report
itself. The real power of parameterised reports is when we render them
programmatically. This can be done using the {quarto}
R
package, which provides the quarto_render()
function.
This function takes a Quarto file and any execution parameters as
input.
So to generate the life expectancy report for Afghanistan, we can write a script with the following code:
R
# render-report.R
library(quarto)
quarto_render("life_expectancy_report.qmd", execute_params = list(country = "Afghanistan"))
And now for the real magic, we can modify our script to render a
report for a list of countries of interest from the
gapminder
dataset.
{r} # render-all-reports.R library(quarto) countries <- c("Afghanistan", "Belgium", "India", "United Kingdom") for (country in countries) { quarto_render( input = "life_expectancy_report.qmd", output_file = paste0("life_expectancy_", country, ".html"), execute_params = list(country = country) ) }
After running this script, we should have the following files in our working directory:
.
├── life_expectancy_Afghanistan.html
├── life_expectancy_Belgium.html
├── life_expectancy_India.html
├── life_expectancy_United Kingdom.html
├── life_expectancy_report.qmd
└── life_expectancy_report_files
Callout
WARNING: although this will work and generate the correct output files, you might notice that each report will show the exact same plot, which is unexpected. This is an issue with the Quarto R package.
With R Markdown we don’t have this issue, to render we would use the following code:
R
rmarkdown::render(
input = "life_expectency_report.Rmd",
output_file = paste0("life_expectancy_", country, ".html"),
params = list(country = country)
)
Tip: Creating PDF documents
Creating .pdf documents may require installation of some extra
software. The R package tinytex
provides some tools to help
make this process easier for R users. With tinytex
installed, run tinytex::install_tinytex()
to install the
required software (you’ll only need to do this once) and then when you
knit to pdf tinytex
will automatically detect and install
any additional LaTeX packages that are needed to produce the pdf
document. Visit the tinytex
website for more information.
Tip: Visual markdown editing in RStudio
RStudio versions 1.4 and later include visual markdown editing mode.
In visual editing mode, markdown expressions (like
**bold words**
) are transformed to the formatted appearance
(bold words) as you type. This mode also includes a
toolbar at the top with basic formatting buttons, similar to what you
might see in common word processing software programs. You can turn
visual editing on and off by pressing the
button in the top right corner of your R Markdown document.
Resources
- Knitr in a knutshell tutorial
- Dynamic Documents with R and knitr (book)
- R Markdown documentation
- R Markdown cheat sheet
- Getting started with R Markdown
- R Markdown: The Definitive Guide (book by Rstudio team)
- Reproducible Reporting
- The Ecosystem of R Markdown
- Introducing Bookdown
Key Points
- Mix reporting written in R Markdown with software written in R.
- Specify chunk options to control formatting.
- Use
knitr
to convert these documents into PDF and other formats.