Skip to contents

Tutorial Helper Functions

About this package

tutorial.helpers provides functions and RStudio Addins to help you write R tutorials, especially if you follow my advice about the best way to do so. This approach is currently used in two packages: primer.tutorials and r4ds.tutorials.

Installation

To install the package from CRAN:

install.packages("tutorial.helpers")

You can install the development version from GitHub with:

remotes::install_github("PPBDS/tutorial.helpers")

Useful tools

Download answers

The most useful tool is the download answers trick. In your tutorial, simply include library(tutorial.helpers) in the setup R code chunk and then insert this empty code chunk at the end.

```{r download-answers, child = system.file("child_documents/download_answers.Rmd", package = "tutorial.helpers")}
```

This will ask the student to provide an estimate of how long the tutorial took to complete. It will then provide the ability to download the student’s answers in three different formats: html, pdf and rds. Students submit these files to their instructors, who can then confirm that the work was completed and look for any patterns in student (mis)understandings.

Testing

There are three exported functions for checking the tutorials in your package. See the testing vignette for details on their use.

We recommend including this child document at the start of each tutorial:

```{r info-section, child = system.file("child_documents/info_section.Rmd", package = "tutorial.helpers")}
```

This will insert questions asking for the student’s name and email address.

We also recommend including this at the beginning of your tutorial:

```{r copy-code-chunk, child = system.file("child_documents/copy_button.Rmd", package = "tutorial.helpers")}
```

This allows you to place a button in an exercise which will allow students to copy over all the code from the previous exercise. Use:

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

This is handy for students when a series of exercises requires them to build up a long pipe, line-by-line.

We recommend ending the tutorial with the download-answers child document, as discussed above.

```{r download-answers, child = system.file("child_documents/download_answers.Rmd", package = "tutorial.helpers")}
```

Addins

In order to access the addins, load the package. See the addins vignette for details about their use.

Getting Started with Tutorials

The package includes a tutorial, “Getting Started with Tutorials,” which provides an introduction to tutorials for beginning students. You should require your students to complete this tutorial if you are using tutorial.packages to create your own tutorials. The tutorial is also available on shinyapps.io (number of users is limited) and Posit Cloud (requires (free) Posit Cloud account).