Instructions for Writing R Tutorials

Flow

Each exercise should have a flow which requires that students hit the “Continue” button at least once.

• Begin with a Start which is a sentence or two of knowledge and/or the question itself. If the length of the Start text is longer than one or two lines, then do not place the question code chunk in the same part. Instead, the Start includes a triple hash, thereby creating the Continue button. If the length of the text is short enough that students are willing to read it (at most two sentences), you can include the exercise code chunk in the same part.

• Most of the time there is no need for a triple hash before the exercise code chunk.

• Do not expect students to read more than two sentences of text at a time. After two sentences, you almost always want to use a triple hash in order to create a Continue button so that students have a break. They won’t read more than two sentences without a break.

• There is a danger that students will just click the Continue button until they see a question and, only then, start reading. There is little we can do about that. However, we can take advantage of students’ tendency to read the sentence or two which proceeds the question fairly closely. This is a great place for teaching since students can’t skip it since they don’t know if it provides necessary context for answering the question.

• After the Start, come three code chunks:

  • The question code chunk is the location in which students will place their answers.
  • The hint code chunk includes any hints for the students. Hint code chunks are only available for code exercises. The code chunk name is the hint is always exactly the same as the one for the exercise code chunk, except with -hint-n attached at the end. The n is replaced by the number of the hint. Almost always, there is only one hint, so the suffix is -hint-1. We always set eval = FALSE in the hint code chunk since, often, the hint will not be legal R code.
  • The test code chunk has exactly the label as the one for the question code chunk, except with -test attached at the end. Test code chunks, like hint code chunks, are only used for code exercises. It always includes the include = FALSE code chunk option because we never want to show the code or the results to students. Instead, the purpose of the test code chunk is to ensure that the correct answer — that is, the code we want students to enter into the exercise code chunk — works.

• The three code chunks are always followed by a triple hash. We want students to pause after they have submitted their answers so that they are more likely to consider the output from their submission before moving on.

• The last part of an exercise is the end, our main opportunity to drop some knowledge. See Knowledge Drops for extensive discussion.

• The last part of the topic is another knowledge drop. It is not another exercise. It is just a knowledge drop after the last exercise which tries to take a broader overview. It is often separated from that last exercise by a simple ###. Again, this can’t be more than a sentence or two. But it should be more substantive than a simple “Good job.” Recall the 10,000 items which we want to mention. For example, if the topic has involved creating a scatter plot, then the last exercise will be putting the final touches on that scatter plot. The knowledge drop should be something about scatter plots in general, not a minor point about the particular scatter plot which the student has just created.

Question types

To create the exercise headers, you use three hashes. Make sure you number your exercises – ### Exercise 1, ### Exercise 2 and so on.

There are two main types of questions. First, we have normal coding questions. Students write code and press the Run Code button. Second, we have text questions which require students to either write prose or to copy/paste the results of running specific commands. Prose is needed for questions like “Explain the meaning of potential outcomes.” Copy/paste situations arise when students are instructed to do something like connect to Github or edit a qmd. We confirm that the students have completed these questions by having them issue a command like list.files() and then copy/pasting the command and the output. We often abbreviate those instruction using CP/CR, which stands for copy and paste the command and the result.

### Exercise 2

Start your code with `cces`. Use the pipe operator `|>` to add the 
function `filter()`, selecting the  rows where `state` is equal to 
"Massachusetts". To set something equal to a value in `filter()` 
use two equal signs: `==`.

```{r filter-2, exercise = TRUE}
```

```{r filter-2-hint-1, eval = FALSE}
cces |> 
  filter(state == "...")
```

```{r filter-2-test, include = FALSE}
cces |> 
  filter(state == "Massachusetts")
```
### 

`==` is used because it is **checking** whether the value of the 
variable on the left is equal to the value on the left. See 
[here](https://stat.ethz.ch/R-manual/R-devel/library/base/html/Comparison.html) 
for discussion of other relational operators in R.
A single equation symbol, `=`, is used to set something equal to 
something else. 

<button onclick = "transfer_code(this)">Copy previous code</button>

```{r ex-1-hint-1, eval = FALSE}
This is an example hint. Normally sentences like these 
would cause an error in R because it is not proper code. 
However, since we include eval = FALSE in the r-chunk, 
R ignores all errors!
```

```{r ex-1-hint-2, eval = FALSE}
... |> 
  filter(year = ...) |> 
  ...(flights)
```

### Exercise 6

Explain potential outcomes in about two sentences.

```{r definitions-6}
question_text(NULL,
    message = "This is where we place the correct answer. It will appear only after 
    students have submitted their own answers. Note that we do not need to wrap the 
    answer text by hand.",          
    answer(NULL, 
           correct = TRUE),
    allow_retry = FALSE,
    incorrect = NULL,
    rows = 6)
``` 

### Exercise 7

From the Console, run `list.files()`. CP/CR.

```{r file-creation-7}
  question_text(NULL,
    answer(NULL, correct = TRUE),
    allow_retry = TRUE,
    try_again_button = "Edit Answer",
    incorrect = NULL,
    rows = 3)
```

In the Console, run:

```
tutorial.helpers::show_file("_quarto.yml")
```

CP/CR.

Tips

Each coding exercise should always spit out something. Interactivity is good! Students should always look at what their code is producing. There are some situations in which students need to make assignments and which, because of this, will result in no output when the Run Code button is pressed. But:

• Do this as little as possible. Why not just make a pipe?

• When you do this, you will need to create the permanent object yourself because student work in an exercise code chunk has no lasting effects. Doing so is annoying and error prone.

• You can have the student not only do the assignment but also, as part of this same exercise, print out the object. This works well.

Follow a coding Style Guide, especially spaces around operators like ” = “. Use only one command per line in pipes and graphics, with proper indentation. Indent plotting commands after the call to ggplot().

Do not create an object in one question and then assume that it will be available in subsequent questions. It won’t be! Each question is independent of every other question. They live in separate R instances. The only exception (which we make use of) is that objects created in the initial setup chunk for the entire tutorial are available in all later questions, just the way that library() commands executed there do not need to be executed again.

Tutorials are knitted/run from the directory in which they are located. So, if you want to read in a file from a data/ directory, you write:

x <- read_csv("data/myfile.csv")

in an R code chunk, presumably in the global setup chunk. But, if you try to execute that line of code with Command + Return, it will fail because, by default, you are located in the main directory of your.package when you start working on your tutorials. Using setwd() will solve this problem.

> getwd()
[1] "/Users/davidkane/Desktop/projects/r4ds.tutorials"
> setwd("inst/tutorials/031-data-files/")
> getwd()
[1] "/Users/davidkane/Desktop/projects/r4ds.tutorials/inst/tutorials/031-data-files"
> 

Command + Return will now work because your R session is “located” in the same location as that from which the tutorial will be run when it is knitted.

Pipes

The most common type of code questions involve the step-by-step process of building a pipe, the final output of which is a nice looking graphic.

You want to first show the graphic that you will create by the end of the topic. You show it once at the start of the topic and once before the last exercise, as a reminder of what the graphic should look like so students do not need to scroll all the way back up.

You should put the code for the graph in the code chunk at the start of the topic. Save the code to an object. The name of the object should have a “_p” suffix, where the “p” stands for “plot.” This way, you only have to put the object name in the code chunk at the end of the topic rather than copying the code.

You then build up the graphic, line by line, over a series of exercises, providing hints along the way.

Knowledge Drops

The most difficult part of tutorial creation is writing the “knowledge drops,” the snippets of wisdom (and the associated links) which are used at the end of each exercise. These generally come in two categories: details about R functions/packages/websites and background information about the substative data science problem at hand.

Do not expect this to be easy! Good knowledge drops are hard. Make them short. Students will not read more than a sentence or two.

Perhaps the best place for a knowledge drop, especially for written questions, is at the start of the exercise. That is, instead of just asking the question immediately, provide a sentence or two of knowledge drops, even if this information is not really needed to answer the question. Students tend to read those sentences closely since they might be relevant to the question they need to answer.

Rhetorical questions (almost) always work poorly for knowledge drops.

A knowledge drop should not be a road sign. Example: “In the next section we will explore the data further.” Don’t waste time telling students what you expect to do next, or what you have just completed doing. Teach them something real!

See `?readr::locale` for [details](https://readr.tidyverse.org/articles/locales.html).

Addins

The tutorial.helpers package provides a collection of RStudio Addins which facilitate the creation and testing of tutorial packages. Read about them in the “Rstudio Addins” vignette. Three of the vignettes create new exercises. A fourth, “Format Tutorial Chunk Labels,” renumbers all the exercises in a tutorial if you add or remove an exercise. It also ensures consistency in code chunk labels. Highly recommended!

Data

If you need for an R object to be accessible in an exercise code chunk, create it in the initial global setup code chunk at the top of the tutorial.

Be wary code which downloads data from the web. This won’t work if the student does not have an internet connection when she creates the tutorial. Instead, save the code which downloaded the data and then place that object in an RDS file in the data directory. Here is an example from the “Wrangling Census data with tidyverse tools” tutorial from the tidycensus.tutorials package.

median_age <- get_acs(geography = "county",
                      variables = "B01002_001",
                      year = 2020)
write_rds(median_age, "data/median_age.rds")

median_age <- read_rds("data/median_age.rds")

The first two commands download data and save it to an RDS file in the data directory.

This code assumes that you are located in the same directory as the tutorial.Rmd file. You only run those commands once, and then you comment them out because you don’t want them re-run each time the tutorial is created. The read_rds() call is never commented out because we always need the median_age object.

When designing tutorials which use objects like median_age, we generally write two exercise code chunks. The first has the student run the same code as that which we used to create the object ourselves. This won’t work if the student is not connected to the web but, with luck, in that case they will get a sensible error message. The second question informs the students that we have, behind the scenes, assigned the result of the function to an R object. We then ask the student to just print out that object. We don’t have them do the assignment themselves, not least because we don’t like questions which don’t generate any output.

We use a similar approach with models which can take awhile to fit. Example:

fit_gauss <- brm(formula = biden ~ 1,
                data = poll_data,
                refresh = 0,
                silent = 2,
                seed = 9)
write_rds(fit_gauss, "data/fit_gauss.rds")

fit_gauss <- read_rds("data/fit_gauss.rds")

Again, this code only works if you are in the tutorial directory, not in the higher directory of the R project itself. Also, the first two commands are commented out, unless you are running them by hand to create the object.

What happens if the data is too large? See the “Arrow” tutorial in the r4ds.tutorials for an example. First, we generally switch away from code exercises and use written exercises. Students run the required commands and then copy/paste the command/response. Big downloads don’t work well in exercise code chunks. Second, we create small versions of this big data in the global setup chunk. This allows us to create test code chunks for most of the exercises which follow. These tests will run much more quickly with this smaller data. Also, for any package on CRAN, we need to keep the overall size of the package as small as possible.

Images

To add images to a tutorial, first make a directory called images in the folder that contains tutorial.Rmd. Store all images for that tutorial there. You can work with those files in all the usual ways.

Use include_graphics() to add the image into the document. Include this code in its own chunk, in the place where you want the image to appear in the tutorial.

```{r}
include_graphics("images/example.png")
```

include_graphics() is part of the knitr package, so you need library(knitr) in the setup code chunk. Note that you do not need to name these code chunks.

Because students will complete the tutorials using screens of very different widths, it is a good idea to put knitr::opts_chunk$set(out.width = '90%') in your setup code chunk. In this way, images will appear as a sensible size regardless of whether they are using a phone screen or a big monitor.

Files

Other files — most commonly text files or RDS files — are handled in a similar fashion to images. Create a directory called data in the same directory as the tutorial.Rmd, just as we do with images.

There are two main uses for files in data. First, they can be used at “compile time” (when the tutorial.Rmd is knit to html) for making plots or doing anything else. Second, and more importantly, they are available to students in the exercise code blocks during “run time” (when students are doing the tutorial).

Complex text

You sometimes want to include “complex” text in a tutorial. This is most common when trying to teach students how to use R code chunks and other strings which Rmarkdown wants to process in certain ways. You can sometimes get away by placing such text in environments surrounded by three, or even four, backticks. This works often, but not always. Comments characters like # are especially problematic. We also use the parsermd package behind the scenes. It does not work as well as one might like.

The “file” trick solves this problem. Create a txt file, example.txt, with the text which you want to appear in the tutorial. You can either leave it in the same directory as the tutorial.Rmd file or, probably better, place it in either the data or images directory. You then add this code chunk to your tutorial.

```{r file = "example.txt", echo = TRUE, eval = FALSE}
```

The file code chunk object loads the specified file. The other code chunk options ensure that the text is echoed but not evaluated.

Test before submitting a PR

Once you are done editing your tutorial, you need to make sure it works before you submit a pull request.

1. Click “Install and Restart” from the Build tab. Then, hit “Start Tutorial” in the Tutorial tab. This mimics the experience that users will have. This will catch some common errors, like having two code chunks with the same name. (I am not sure if this does more or less than the simple test as above.)

2. Do a full test, which means running R CMD check. Go to the top right window of RStudio. Click the Build pane and hit the “Check” button (with the green check mark). You will then see a bunch of code and tests running. Make sure it says “OK” next to “testthat”. You should always run this before submitting a pull request.

What to do if R CMD check fails

1. Read the error message at the bottom of the Build pane. You want to see “R CMD check succeeded.” If not, there is a problem. The error message will often provide a clue as to where in your code the error occurred.

2. If that error message is not detailed enough, go to the your.package.rcheck folder, which should be located in the same directory as your.package on your computer. This is a folder created by the R CMD check process, and it will be automatically deleted if the check process succeeds. If the process fails, the your.package.rcheck folder stays around so that you can examine it. The key file is testthat.Rout.fail, which should be in the tests directory. It has more details on what went wrong.

The most common source of errors is something wrong with the hint code chunks, which are not evaluated when you just Run Document. Make sure the eval = FALSE argument is set in the code chunk for all hints.

Difficult bugs

• The most common issue is that an author will use a package like ggthemes in their tutorial but then forget to include library(ggthemes) in the setup code chunk. This will not cause any error in checking because ggthemes is not actually used in the tutorial itself — unless it is included in a test code chunk, as it should be — so the tutorial knits without a problem. But then the student tries to type library(ggthemes) as an answer to an exercise and gets an error because the package has not been installed.

• Note that R CMD check does not seem to catch cases in which you library() a package in a tutorial but that package is not in DESCRIPTION. But such a discrepancy will cause an error on Github Actions because, there, you only have access to packages that have been installed as part of that test.

• Be careful of the way that Github is sloppy in how it deals with capitalization changes, especially when you change the name of a file. For example, you might first commit a file named Rproj.png. Later, you decide to change all file names for images to all lower case. So, you change the name of the file to rproj.png. Commit and push. Everything is great, right? No! Even if Github shows you the new file name it might still have that file as Rproj.png internally, with the capital “R”. This will cause errors when your run your checks on Github:

Error: Cannot find the file(s): "images/rproj.png"

But the file is there! You can see it! The tests work on your local machine. The easiest solution is to delete the file (and commit that change). And then change the name of the file to something else and use it.

• R CMD check will test that all tutorials have the default code chunks exactly as they are in the Helper Tutorial template. So, use the template. If either the “Information” or “Download answers” chunks are missing, R CMD check will return something like “Missing a component part from file /path/to/your/Rmd/file.Rmd”.