From 794417473efb07a644e2897eb9b9f09b4b379f78 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Wed, 21 Aug 2024 11:07:14 +0000 Subject: [PATCH] site deploy Auto-generated via {sandpaper} Source : 40998d1394eb252a3dee20851b689e5fb0c2704b Branch : md-outputs Author : GitHub Actions Time : 2024-08-21 11:06:35 +0000 Message : markdown source builds Auto-generated via {sandpaper} Source : 580a4d9561a679e5c93c712fdd0946bd6f9d311a Branch : main Author : quirksahern Time : 2024-08-21 11:05:20 +0000 Message : Merge pull request #19 from UCL-ARC/milanmlft/quarto-episode Update RMarkdown episode to use Quarto and add section on parametrised reports --- 01-rstudio-intro.html | 4 +- 02-project-intro.html | 6 +- 03-seeking-help.html | 10 +- 04-data-structures-part1.html | 34 +- 05-data-structures-part2.html | 12 +- 06-filedir.html | 14 +- 07-basics.html | 4 +- 08-setup.html | 4 +- 09-create.html | 8 +- 10-changes.html | 4 +- 11-history.html | 12 +- 12-ignore.html | 4 +- 13-supplemental-rstudio.html | 4 +- 14-data-subsetting.html | 4 +- 15-plot-ggplot2.html | 4 +- 16-writing-data.html | 4 +- 17-github.html | 12 +- 18-collab.html | 6 +- 19-conflict.html | 8 +- 20-dplyr.html | 4 +- 21-tidyr.html | 18 +- 22-quarto.html | 1245 +++++++++++++++++++++ 23-statistics.html | 12 +- 27-wrap-up.html | 4 +- 404.html | 6 +- CODE_OF_CONDUCT.html | 4 +- LICENSE.html | 4 +- aio.html | 575 ++++++---- config.yaml | 94 +- discuss.html | 4 +- fig/New_Quarto_Document.png | Bin 0 -> 55936 bytes images.html | 21 +- index.html | 6 +- instructor-notes.html | 6 +- instructor/01-rstudio-intro.html | 4 +- instructor/02-project-intro.html | 6 +- instructor/03-seeking-help.html | 10 +- instructor/04-data-structures-part1.html | 34 +- instructor/05-data-structures-part2.html | 12 +- instructor/06-filedir.html | 16 +- instructor/07-basics.html | 4 +- instructor/08-setup.html | 4 +- instructor/09-create.html | 8 +- instructor/10-changes.html | 4 +- instructor/11-history.html | 12 +- instructor/12-ignore.html | 4 +- instructor/13-supplemental-rstudio.html | 4 +- instructor/14-data-subsetting.html | 4 +- instructor/15-plot-ggplot2.html | 4 +- instructor/16-writing-data.html | 4 +- instructor/17-github.html | 12 +- instructor/18-collab.html | 6 +- instructor/19-conflict.html | 8 +- instructor/20-dplyr.html | 4 +- instructor/21-tidyr.html | 18 +- instructor/22-quarto.html | 1247 ++++++++++++++++++++++ instructor/23-statistics.html | 12 +- instructor/27-wrap-up.html | 4 +- instructor/404.html | 6 +- instructor/CODE_OF_CONDUCT.html | 4 +- instructor/LICENSE.html | 4 +- instructor/aio.html | 577 ++++++---- instructor/discuss.html | 4 +- instructor/images.html | 21 +- instructor/index.html | 8 +- instructor/instructor-notes.html | 8 +- instructor/key-points.html | 8 +- instructor/profiles.html | 6 +- instructor/reference.html | 4 +- key-points.html | 8 +- md5sum.txt | 4 +- pkgdown.yml | 2 +- profiles.html | 6 +- reference.html | 4 +- sitemap.xml | 6 + 75 files changed, 3582 insertions(+), 704 deletions(-) create mode 100644 22-quarto.html create mode 100644 fig/New_Quarto_Document.png create mode 100644 instructor/22-quarto.html diff --git a/01-rstudio-intro.html b/01-rstudio-intro.html index d6f2da6ef..7bff97c2f 100644 --- a/01-rstudio-intro.html +++ b/01-rstudio-intro.html @@ -407,7 +407,7 @@

@@ -1566,7 +1566,7 @@

Key Points +
+ R for AMR Epidemiology +
+ +
+
+ + + + + +
+
+

Producing Reports With Quarto

+

Last updated on 2024-08-21 | + + 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:

+
Screenshot of the New Quarto Document dialogue box in RStudio

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.

+
+

YAML +

+
---
+title: "My Quarto document"
+author: "John Doe"
+format: html
+editor: visual
+---
+
+

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:

+
+

MARKDOWN +

+
1. bold with double-asterisks
+1. italics with underscores
+1. code-type font with backticks
+
+

This will appear as:

+
  1. bold with double-asterisks
    2. +
  2. italics with underscores
    3. +
  3. code-type font with backticks
    4. +

You can make section headers of different sizes by initiating a line +with some number of # symbols:

+
+

MARKDOWN +

+
# Title
+
+## Main section
+
+### Sub-section
+
+#### Sub-sub section
+
+

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.

+
Schematic of the Quarto rendering process

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 and message=FALSE to +hide any warnings or messages produced.
    • +
  • Use fig.height and fig.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:

+
+

YAML +

+
---
+title: "Life Expectancy Report for `r params$country`"
+...
+
+
+
+

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 Icon for turning on and off the visual editing mode in RStudio, which looks like a pair of compasses +button in the top right corner of your R Markdown document.

+
+
+
+
+

Resources +

+
+
+ +
+
+

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.
    • +
+
+
+
+
+ + +
+
+ + + diff --git a/23-statistics.html b/23-statistics.html index 34cf1b57d..1a77acf1d 100644 --- a/23-statistics.html +++ b/23-statistics.html @@ -385,7 +385,7 @@

@@ -465,12 +465,12 @@