From edae5826d42c8a2bc4395ef65cc112f46cd7a019 Mon Sep 17 00:00:00 2001 From: Milan Malfait <38256462+milanmlft@users.noreply.github.com> Date: Tue, 20 Aug 2024 10:31:43 +0100 Subject: [PATCH 1/5] Rename RMarkdown episode -> Quarto --- config.yaml | 2 +- episodes/{22-knitr-markdown.Rmd => 22-quarto.Rmd} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename episodes/{22-knitr-markdown.Rmd => 22-quarto.Rmd} (100%) diff --git a/config.yaml b/config.yaml index 55e40ba14..ecbc3a32e 100644 --- a/config.yaml +++ b/config.yaml @@ -84,7 +84,7 @@ episodes: - 20-dplyr.Rmd - 21-tidyr.Rmd # basic stats -- 22-knitr-markdown.Rmd +- 22-quarto.Rmd - 23-statistics.Rmd # 23-regression # 24-logregression diff --git a/episodes/22-knitr-markdown.Rmd b/episodes/22-quarto.Rmd similarity index 100% rename from episodes/22-knitr-markdown.Rmd rename to episodes/22-quarto.Rmd From a709d791e1630e8b56c776010f975cecd44c11b3 Mon Sep 17 00:00:00 2001 From: Milan Malfait <38256462+milanmlft@users.noreply.github.com> Date: Tue, 20 Aug 2024 12:55:51 +0100 Subject: [PATCH 2/5] Update reporting episode to use `quarto` instead of R Markdown --- episodes/22-quarto.Rmd | 259 ++++++++++++++------------- episodes/fig/New_Quarto_Document.png | Bin 0 -> 55936 bytes 2 files changed, 137 insertions(+), 122 deletions(-) create mode 100644 episodes/fig/New_Quarto_Document.png diff --git a/episodes/22-quarto.Rmd b/episodes/22-quarto.Rmd index deb8e1288..7e7a9fd22 100644 --- a/episodes/22-quarto.Rmd +++ b/episodes/22-quarto.Rmd @@ -1,5 +1,5 @@ --- -title: Producing Reports With knitr +title: Producing Reports With Quarto teaching: 60 exercises: 15 source: Rmd @@ -8,10 +8,10 @@ source: Rmd ::::::::::::::::::::::::::::::::::::::: objectives - Understand the value of writing reproducible reports -- Learn how to recognise and compile the basic components of an R Markdown file +- 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 an R Markdown file can be exported +- Be aware of alternative output formats to which a Quarto file can be exported :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -41,11 +41,23 @@ 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 R Markdown makes things easier. +Creating a report as a web page (which is an html file) using [Quarto](https://quarto.org/docs/get-started/hello/rstudio.html) +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 and R Markdown document is simple and easy to modify, allowing you to spend -more time on your analyses instead of writing reports. +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](https://rmarkdown.rstudio.com/) as a literate +programming tool. In a lot of ways, Quarto is the +[next-generation version of R Markdown](https://quarto.org/docs/faq/rmarkdown.html) +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 @@ -62,30 +74,32 @@ be executed, and graphs or other results will be inserted into the final documen This sort of idea has been called "literate programming". -`knitr` allows you to mix basically any type of text with code from different programming languages, but we recommend that you use `R Markdown`, which mixes Markdown -with R. [Markdown](https://www.markdownguide.org/) is a light-weight mark-up language for creating web -pages. +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](http://pandoc.org/). This whole process is handled for you +by the *Render* button in the RStudio IDE. -## Creating an R Markdown file +## Creating a Quarto document -Within RStudio, click File → New File → R Markdown and +Within RStudio, click `File → New File → Quarto document...` and you'll get a dialog box like this: -![](fig/New_R_Markdown.png){alt='Screenshot of the New R Markdown file dialogue box in RStudio'} +![](fig/New_Quarto_Document.png){alt='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 R 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. +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: "Initial R Markdown document" -author: "Karl Broman" -date: "April 23, 2015" -output: html_document +title: "My Quarto document" +author: "John Doe" +format: html +editor: visual --- ``` @@ -96,11 +110,11 @@ 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 -
-```{r}
-summary(cars)
-```
-
+````{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. @@ -122,7 +136,7 @@ and you make things *italics* by using underscores, like this: 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 @@ -132,7 +146,7 @@ A list: or like this: -``` +```markdown A second list: - bold with double-asterisks @@ -152,7 +166,7 @@ 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 @@ -167,21 +181,26 @@ This will appear as: 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 "Knit" button in the upper-left. +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 ## Challenge 1 -Create a new R Markdown document. Delete all of the R code chunks +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). @@ -191,11 +210,11 @@ Convert the document to a webpage. ## Solution to Challenge 1 -In RStudio, select File > New file > R Markdown... +In RStudio, select `File > New file > Quarto Document...` Delete the placeholder text and add the following: -``` +```markdown # Introduction ## Background on Data @@ -213,8 +232,7 @@ This report uses the *gapminder* dataset, which has columns that include: ``` -Then click the 'Knit' button on the toolbar to generate an html document (webpage). - +Then click the 'Render' button on the toolbar to generate an html document (webpage). ::::::::::::::::::::::::: @@ -239,31 +257,50 @@ If you know how to write equations in $$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 Markdown comes from -mixing markdown with chunks of code. This is R Markdown. When +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: -
-```{r load_data}
+````{verbatim}
+```{r}
+#| label: load_data
 gapminder <- read.csv("gapminder.csv")
-```
-
+``` +```` -That is, you place a chunk of R code between \`\`\`{r chunk\_name} +That is, you place a chunk of R code between \`\`\`{r} and \`\`\`. You should give each chunk -a unique name, as they will help you to fix errors and, if any graphs are +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. +Ctrl\+Alt\+I on Windows and Linux, +or Cmd\+Option\+I on Mac. + +::: spoiler +### Code chunk options in R Markdown +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 @@ -279,31 +316,33 @@ Add code chunks to: ## Solution to Challenge 2 -
-```{r load-ggplot2}
-library("ggplot2")
-```
-
+````{verbatim} +```{r} +#| label: libraries +library(ggplot2) +``` +```` -
-```{r read-gapminder-data}
+````{verbatim}
+```{r}
+#| label: load-gapminder-data
 gapminder <- read.csv("gapminder.csv")
-```
-
+``` +```` -
-```{r make-plot}
+````{verbatim}
+```{r}
+#| label: make-plot
 plot(lifeExp ~ year, data = gapminder)
-```
-
- +``` +```` ::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::::::::::::::: ## How things get compiled -When you press the "Knit" button, the R Markdown document is +When you press the "Render" button, the Quarto document is processed by [`knitr`](https://yihui.name/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 @@ -313,38 +352,7 @@ The Markdown and figure documents are then processed by the tool [`pandoc`](https://pandoc.org/), which converts the Markdown file into an html file, with the figures embedded. -```{r rmd_to_html_fig, fig.width=8, fig.height=3, fig.align="left", echo=FALSE} -par(mar=rep(0, 4), bty="n", cex=1.5) -plot(0, 0, type="n", xlab="", ylab="", xaxt="n", yaxt="n", - xlim=c(0, 100), ylim=c(0, 100)) -xw <- 10 -yh <- 35 -xm <- 12 -ym <- 50 -rect(xm-xw/2, ym-yh/2, xm+xw/2, ym+yh/2, lwd=2) -text(xm, ym, ".Rmd") - -xm <- 50 -ym <- 80 -rect(xm-xw/2, ym-yh/2, xm+xw/2, ym+yh/2, lwd=2) -text(xm, ym, ".md") -xm <- 50; ym <- 25 -for(i in c(2, 0, -2)) - rect(xm-xw/2+i, ym-yh/2+i, xm+xw/2+i, ym+yh/2+i, lwd=2, - border="black", col="white") -text(xm-2, ym-2, "figs/") - -xm <- 100-12 -ym <- 50 -rect(xm-xw/2, ym-yh/2, xm+xw/2, ym+yh/2, lwd=2) -text(xm, ym, ".html") - -arrows(22, 50, 38, 50, lwd=2, col="slateblue", len=0.1) -text((22+38)/2, 60, "knitr", col="darkslateblue", cex=1.3) - -arrows(62, 50, 78, 50, lwd=2, col="slateblue", len=0.1) -text((62+78)/2, 60, "pandoc", col="darkslateblue", cex=1.3) -``` +![](https://quarto.org/docs/get-started/hello/images/rstudio-qmd-how-it-works.png){alt='Schematic of the Quarto rendering process'} ## Chunk options @@ -361,22 +369,32 @@ treated. Here are some examples: So you might write: -
-```{r load_libraries, echo=FALSE, message=FALSE}
-library("dplyr")
-library("ggplot2")
-```
-
+````{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, like so: +repeatedly; for this, you can set *global* chunk options in the files YAML header like so: -
-```{r global_options, echo=FALSE}
-knitr::opts_chunk$set(fig.path="Figs/", message=FALSE, warning=FALSE,
-                      echo=FALSE, results="hide", fig.width=11)
-```
-
+```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 @@ -397,12 +415,14 @@ code. ## Solution to Challenge 3 -
-```{r echo = FALSE, fig.width = 3}
-plot(faithful)
-```
-
- +````{verbatim} +```{r} +#| label: faitful-plot +#| echo: false +#| fig.width: 3 +plot(faitful) +``` +```` ::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -424,14 +444,6 @@ 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"`). -Rounding can produce differences in output in such situations. You may want -`2.0`, but `round(2.03, 1)` will give just `2`. - -The -[`myround`](https://github.com/kbroman/broman/blob/master/R/myround.R) -function in the [R/broman](https://github.com/kbroman/broman) package handles -this. - ::::::::::::::::::::::::::::::::::::::: challenge ## Challenge 4 @@ -442,18 +454,21 @@ Try out a bit of in-line R code. ## Solution to Challenge 4 -Here's some inline code to determine that 2 + 2 = ```r 2+2```. +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. Click the -little triangle next to the "Knit" button to get a drop-down -menu. Or you could put `pdf_document` or `word_document` in the initial header -of the file. +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](https://quarto.org/docs/output-formats/all-formats.html) ::::::::::::::::::::::::::::::::::::::::: callout diff --git a/episodes/fig/New_Quarto_Document.png b/episodes/fig/New_Quarto_Document.png new file mode 100644 index 0000000000000000000000000000000000000000..c744655ea7c8f3fad32e33154050e1f7d992fc95 GIT binary patch literal 55936 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 Date: Tue, 20 Aug 2024 18:09:46 +0100 Subject: [PATCH 3/5] Add section on parametrised reports --- episodes/22-quarto.Rmd | 139 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) diff --git a/episodes/22-quarto.Rmd b/episodes/22-quarto.Rmd index 7e7a9fd22..5c670addb 100644 --- a/episodes/22-quarto.Rmd +++ b/episodes/22-quarto.Rmd @@ -470,6 +470,145 @@ 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](https://quarto.org/docs/output-formats/all-formats.html) +## 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](https://github.com/quarto-dev/quarto-r), 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) +quart_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](https://github.com/quarto-dev/quarto-r/issues/205) 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) +) +``` + +::: + ::::::::::::::::::::::::::::::::::::::::: callout ## Tip: Creating PDF documents From 85991fc1b7cea64f205bb3175cdf2b92a543ab86 Mon Sep 17 00:00:00 2001 From: Milan Malfait <38256462+milanmlft@users.noreply.github.com> Date: Tue, 20 Aug 2024 18:14:52 +0100 Subject: [PATCH 4/5] Make quarto episode regular markdown --- config.yaml | 94 ++++++++++----------- episodes/{22-quarto.Rmd => 22-quarto.md} | 2 - renv/profiles/lesson-requirements/renv.lock | 2 +- 3 files changed, 48 insertions(+), 50 deletions(-) rename episodes/{22-quarto.Rmd => 22-quarto.md} (99%) diff --git a/config.yaml b/config.yaml index ecbc3a32e..6aff2efbc 100644 --- a/config.yaml +++ b/config.yaml @@ -1,3 +1,4 @@ +--- #------------------------------------------------------------ # Values for this lesson. #------------------------------------------------------------ @@ -8,32 +9,32 @@ # lc: Library Carpentry # cp: Carpentries (to use for instructor training for instance) # incubator: The Carpentries Incubator -carpentry: 'swc' +carpentry: "swc" # Overall title for pages. -title: 'R for AMR Epidemiology' +title: "R for AMR Epidemiology" # Date the lesson was created (YYYY-MM-DD, this is empty by default) -created: '2015-04-18' +created: "2015-04-18" # Comma-separated list of keywords for the lesson -keywords: 'software, data, lesson, The Carpentries' +keywords: "software, data, lesson, The Carpentries" # Life cycle stage of the lesson # possible values: pre-alpha, alpha, beta, stable -life_cycle: 'stable' +life_cycle: "stable" # License of the lesson materials (recommended CC-BY 4.0) -license: 'CC-BY 4.0' +license: "CC-BY 4.0" # Link to the source repository for this lesson -source: 'https://github.com/UCL-ARC/r-amr-epidemiology' +source: "https://github.com/UCL-ARC/r-amr-epidemiology" # Default branch of your lesson -branch: 'main' +branch: "main" # Who to contact if there are any issues -contact: 'ARC.Education@ucl.ac.uk' +contact: "ARC.Education@ucl.ac.uk" # Navigation ------------------------------------------------ # @@ -58,55 +59,54 @@ contact: 'ARC.Education@ucl.ac.uk' # - another-learner.md # Order of episodes in your lesson -episodes: -- 01-rstudio-intro.Rmd -- 02-project-intro.Rmd -- 03-seeking-help.Rmd -- 04-data-structures-part1.Rmd -- 05-data-structures-part2.Rmd -- 06-filedir.md -- 07-basics.md -- 08-setup.md -- 09-create.md -- 10-changes.md -- 11-history.md -- 12-ignore.md -- 13-supplemental-rstudio.md -- 14-data-subsetting.Rmd -# - 07-control-flow.Rmd -- 15-plot-ggplot2.Rmd -# - 09-vectorization.Rmd -# - 10-functions.Rmd -- 16-writing-data.Rmd -- 17-github.md -- 18-collab.md -- 19-conflict.md -- 20-dplyr.Rmd -- 21-tidyr.Rmd -# basic stats -- 22-quarto.Rmd -- 23-statistics.Rmd -# 23-regression -# 24-logregression -# 25-broom -# 26-r-sql -- 27-wrap-up.Rmd +episodes: + - 01-rstudio-intro.Rmd + - 02-project-intro.Rmd + - 03-seeking-help.Rmd + - 04-data-structures-part1.Rmd + - 05-data-structures-part2.Rmd + - 06-filedir.md + - 07-basics.md + - 08-setup.md + - 09-create.md + - 10-changes.md + - 11-history.md + - 12-ignore.md + - 13-supplemental-rstudio.md + - 14-data-subsetting.Rmd + # - 07-control-flow.Rmd + - 15-plot-ggplot2.Rmd + # - 09-vectorization.Rmd + # - 10-functions.Rmd + - 16-writing-data.Rmd + - 17-github.md + - 18-collab.md + - 19-conflict.md + - 20-dplyr.Rmd + - 21-tidyr.Rmd + # basic stats + - 22-quarto.md + - 23-statistics.Rmd + # 23-regression + # 24-logregression + # 25-broom + # 26-r-sql + - 27-wrap-up.Rmd # Information for Learners -learners: +learners: # Information for Instructors -instructors: +instructors: # Learner Profiles -profiles: +profiles: # Customisation --------------------------------------------- # # This space below is where custom yaml items (e.g. pinning # sandpaper and varnish versions) should live - -url: 'https://UCL-ARC.github.io/R-AMR-Epidemiology' +url: "https://UCL-ARC.github.io/R-AMR-Epidemiology" analytics: carpentries lang: en diff --git a/episodes/22-quarto.Rmd b/episodes/22-quarto.md similarity index 99% rename from episodes/22-quarto.Rmd rename to episodes/22-quarto.md index 5c670addb..bc7080310 100644 --- a/episodes/22-quarto.Rmd +++ b/episodes/22-quarto.md @@ -21,8 +21,6 @@ source: Rmd :::::::::::::::::::::::::::::::::::::::::::::::::: -```{r chunk_options, include=FALSE} -``` ## Data analysis reports diff --git a/renv/profiles/lesson-requirements/renv.lock b/renv/profiles/lesson-requirements/renv.lock index 785b93e0a..2fde3baa5 100644 --- a/renv/profiles/lesson-requirements/renv.lock +++ b/renv/profiles/lesson-requirements/renv.lock @@ -1272,7 +1272,7 @@ "Package": "stringi", "Version": "1.8.4", "Source": "Repository", - "Repository": "RSPM", + "Repository": "carpentries", "Requirements": [ "R", "stats", From f356d533ce0a23fc2b03f46f564df06e5c5a5283 Mon Sep 17 00:00:00 2001 From: Milan Malfait <38256462+milanmlft@users.noreply.github.com> Date: Tue, 20 Aug 2024 18:18:19 +0100 Subject: [PATCH 5/5] Fix typo --- episodes/22-quarto.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/episodes/22-quarto.md b/episodes/22-quarto.md index bc7080310..a04b52df6 100644 --- a/episodes/22-quarto.md +++ b/episodes/22-quarto.md @@ -559,7 +559,7 @@ code: ```r # render-report.R library(quarto) -quart_render("life_expectancy_report.qmd", execute_params = list(country = "Afghanistan")) +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