Automatizing RMarkdown and Quarto, parametrized reports

Author

Indrek Seppo

Published

June 1, 2023

This work is licensed under a Creative Commons Attribution 4.0 International License.

Please contact indrek.seppo@gmail.com for source code or missing datasets.

Prerequisites

We will need (preferably the latest versions of) R, RStudio and Quarto1. These can be downloaded from:

All of these are free to use and open source.

In addition to that we need LaTeX environment for full experience (to generate pdfs). For this please run this in your RStudio (you do not need to do it if you alread have a LaTeX distribution like TinyTeX installed):

install.packages("tinytex")
tinytex::install_tinytex()

We are also going to use packages like tidyverse, quarto (and rmarkdown, if you want to automatize rmarkdown reports).

Introduction

RMarkdown and it’s next generation incarnation Quarto are amazing in automatizing reporting. Today we are going to look at parametrized reports and – if time permits – some features of Quarto (almost all of it would also be compatible with RMarkdown, if you haven’t moved to Quarto yet2).

Creating a project and downloading data

It is always advisable to create a new project if you start working on a new topic in RStudio. So lets create it: File -> New Project -> New Directory -> New Project. Now set the name of the project and Create project. This creates a new directory into your filesystem, where all the project related files will be, from where R searches for files to load and to where it saves the results.

Lets now download some play-data into this folder. Create a new R script, read the data into R and then save it like this:

library(tidyverse)
piaac <- read_csv("http://www.ut.ee/~iseppo/piaacENG.csv")
write_csv(piaac, "piaac.csv")

You should now see in the files pane, that you have a new file in this directory called piaac.csv. The data itself is not so important right now, but it comes from Programme for the International Assessment of Adult Competencies (PIAAC) run by OECD – it measures adults numeracy and literacy skills and has a lot of additional data about everyone in the sample. The nice thing about it is that it is freely available. I have only included some variables here, and this particular data comes from Estonia (there are many more countries in the dataset). It is a bit outdated, but the new wave is running right now and we do not have this data yet.

Creating a toy report

Lets first create a basic parametrized report including a paragraph of text, a graph and a table.

Create a new Quarto document using File -> New File -> Quarto document. Lets give the document a name - I will just ame it as My Report and add the author. Save it for example as myreport.qmd and render it using the Render button on the toolbar to see that everything works.

It will probably open in new window for you (if you haven’t changed the default settings). I prefer to have it rendered in the Viewer pane inside RStudio. For this you have to click on the gears icon next to the Render-button and select Preview in Viewer Pane.

Now lets clear everything apart of the YAML header (everything from line 7) and write our own toy report from scratch, adding the following code:


# Report of Services

```{r}
library(tidyverse)
```

```{r}
piaac <- read_csv("piaac.csv") %>%
  filter(studyarea == "Services")
```

```{r}
#|fig-cap: Age-earning profile of Services

ggplot(piaac, aes(x = age, y = Income)) +
  geom_smooth()

```

We see that the code is also visible. Wr probably do not want this. There are two ways to get rid of it:

One is to add the following in the code chunk:

#|echo: false

The other way is to go and change the YAML (and this will now be default for all the chunks):

execute:
  echo: false

Lets add some basics, like a sentence regarding the average wage:

```{r}
av_wage <- mean(piaac$Income, na.rm = TRUE)
```


The average wage for studyarea Services was `r av_wage`.

Now render the report to see how it looks.

Let’s parametrize it!

Lets add a single parameter to the report. For this you need to add the following to the YAML header:

params:
  studyarea: "Services"

You can now access this parameter like this:

params$studyarea

So all we have to do now is to change Services everywhere to params$studyarea.

We can now run this with different parameters. For example we can change the studyarea to be “General programmes”. Or we can include the parameter in the command line:

quarto render myreport.qmd -P studyarea:General Programmes

This is still not what we want, we want to automatically create the report for all of the studyareas. Lets load in package called quarto. and use the quarto_render() function from there.

quarto::quarto_render(
    input = "myreport.qmd",
    execute_params = list(
        studyarea = "General Programmes"
    )
)

Now lets add the output_file parameter.

And then lets run a for cycle to go over all the possible studyareas.

Footnotes

  1. Note that a version of quarto already comes with RStudio but I recommend you to upgrade to the latest version anyway.↩︎

  2. But note that Quarto is backwards compatible, so you should be able to compile your RMarkdown files with Quarto as well.↩︎