Exercise: Conversion

Overview

In this exercise, we’ll learn how to transform an existing static RMarkdown or Quarto document into an interactive one. We’ll walk through the process step by step, starting with obtaining the tutorial documents and ending with rendering the interactive version.

Just as before, we’ll focus on using the quarto-webr extension. As the documents contain specific R code and cell options, we do not advise trying to make a 1-to-1 substitution with quarto-pyodide; though, the conversion process remains the same.

Step-by-step

Overview

For this exercise, we’ll use the publicly available “Start” tidymodels tutorial documents. You can see the tutorials here:

As an alternative, you can consider using existing lesson material from Data Science Course in a Box (Source) by Mine Çetinkaya-Rundel.

Step into a Quarto Project

First, ensure you’re inside a Quarto Project within RStudio or VS Code. If you need help with this, refer back to our first exercise for help in creating a Quarto project or revisiting an existing Quarto project. Alternatively, please feel free to raise your hand.

Install the Quarto Extension

For new Quarto projects, please make sure to install the Quarto extension into the project by typing into Terminal:

quarto add coatless/quarto-webr

Obtaining a copy of the file

To begin, download a copy of the tutorial file locally. Inside the R console, run:

doc_url = "https://raw.githubusercontent.com/tidymodels/tidymodels.org/main/start/recipes/index.qmd"
download.file(doc_url, "recipes.qmd")

This code chunk will download the source of the “Preprocess your data with recipes” tutorial page.

Convert Chunk Options to Hashpipe Options

Note

As the original recipes tutorial is written to take advantage of Quarto, this step is redundant and can be skipped.

When converting from an RMarkdown document (.Rmd) to a Quarto Document (.qmd) for the first time, use knitr’s convert_chunk_header() function:

knitr::convert_chunk_header(
  "recipes.Rmd", output = "recipes.qmd",
  type = "yaml"
)

This step converts RMarkdown style-chunk options to Quarto’s hashpipe style specification, e.g. 

```{r, echo = FALSE, fig.width: 10}
```

switches to:

```{r}
#| echo: false
#| fig.width: 10
```

Modify the document header

Next, please modify the document header to include engine: knitr and the filters statement.

---
title: "Preprocess your data with recipes"
description: | 
  Prepare data for modeling with modular preprocessing steps.
engine: knitr
filters:
  - webr
---

Setup R Packages Required

For the next step, identify what R packages are required by the tutorial.

We recommend placing all R packages under the document-level option packages. By using the packages key, the document’s interactive cells will not unlock until all packages are downloaded and installed. Please make sure to remove individual install.packages() statements in existing cells.

Moreover, the extension will load all R packages specified in this manner before unlocking interactive code cells. You may wish to disable this option by supplying: autoload-packages: false.

Set Global Cell Options

One other useful feature is to specify any option you find yourself repeating consistently under the document-level option cell-options.

For this case, we would recommend setting autorun: true to run cells by default.

Convert Cells

Please convert cells by switching the designation from {r} to {webr-r}. This can be accomplished by using find and replace.

If using RStudio, this operation can be performed by either:

  • By menu:
    • Edit -> Find and Replace
  • Keyboard shortcut:
    • macOS: Cmd + F
    • Windows: Ctrl + F

Find and replace open in RStudio

For VS Code, the same operation can be done using:

  • By menu:
    • Edit -> Replace in Files
  • Keyboard shortcut:
    • macOS: Shift + Cmd + H
    • Windows: Shift + Ctrl + H

Find and replace open in VS Code

Aside

You can display both interactive and pre-run versions side-by-side using panel tabsets with Tabset Groups to automatically toggle between versions on the page. For example, the following creates a tabset that includes a {webr-r} version and an {r} code cell version.

::: {.panel-tabset group="programming-demo"}
#### Interactive Code

```{webr-r}
#| autorun: true
1 + 1
```
#### Pre-run code

```{r}
1 + 1
```
:::
1 + 1
[1] 2

Remove unnecessary code cells

The existing tutorial has a few additional code cells that call an R script that isn’t available within the project. You can safely remove the setup cell and you can modify the final code cell to use sessionInfo() instead of their custom version.

Render the document

Finally, render the document to view the interactive version.