How to make an interactive tutorial to teach R?

Learning R online

There is a lot of amazing tutorials out there which can be accessed for free on coursera or udermy platforms for example or using blogs and online books. It is also very easy to create your own tutorial using {blogdown} or {bookdown} for example. A great talk entitled “How to Get Your Materials Online With R Markdown” recently introduced the different possibilities to share your own tutorial online (here are the video and the slides). However, few of these solutions are satisfying the first criteria. The ability to let the learners running the code by themselves usually imply that the learner has to run the code on a machine with the code and IDE required already installed.

One of these online learning platform is different, it allows the learner to watch a video or to read some slides and then to run the code via some exercises. I’ve learnt a lot from this platform but the access of the tutorials is not free and therefore not suitable for students.

Interactive tutorials R packages

The community around R has developed some amazing tools to create interactive tutorials which allow learners to run their own code (see here for example). There are maybe more of them but I am thinking of the {learnr} and {RTutor} packages (the {swirl} package also creates tutorials but these have to be used inside an IDE).

The {RTutor} package by Sebastian Kranz is showing the basics of interactivity. Wildly used for multiple tutorials (see GitHub README for list), it has paved the way for most recent alternatives. Here is a recent use of RTutor:

• Problem Set: Estimating CO2 Reduction Costs

The {learnr} package by Schloerke, Allaire, and Borges (2020) is amazing. To be more familiar with the possibilities of {learnr}, you can have a look at the following {learnr} tutorial examples provided by RStudio ( here is the link to their code):

• Hello, Tutorial!
• Tutorial Quiz Questions in learnr
• Slidly demo
• Set Up
• Data basics
• Filter observations
• Create new variables
• Summarise Tables

Another tutorial for sortable questions has been created by Andrie de Vries.

I think the R Set Up {learnr} is incredibly useful in a remote teaching context.

The RStudio education team have recently developed a suite of impressive interactive R tutorials called Primers based on their RStudio Cloud framework. I strongly recomand any R beginner to have a look at all these tutorials.

RStudio has currently developed 6 of these primers and plan to build even more of them.

{learnr} helps to create very neat interactive tutorials from a .Rmd file. Because I love Rmarkdown, I have created some of them already for my students:

• WaRm Up!
• Data Transformation
• Data Visualisation
• Linear Regression

The R community is also creating plenty more {learnr} tutorials, here is a list of the ones that I know of:

• Data basics by J.J. Allaire
• Less Volume, More Creativity Plots and More by Randy Pruim
• Getting to Know infer by Simon P. Couch
• Exploring missing values in naniar

It is also possible to integrate the {learnr} package into a blogdown website and to create beautiful visualisation such as the giraffe project to learn statistics.

I have never used the {RTutor} package but I’m assuming it has a lot of similarities with the {learnr} package as indicated in this blog post.

The {learnr} package is very nice but it has a major problem, the learners need to have their own and unique shiny session. To run a .Rmd file using the {learnr} package, this Rmarkdown has to be deployed on a shiny server and I currently know only two solutions to host a shiny app:

Scale Docker containers with Binder

I recently came across the post of by Florencia d’Andrea explaining how to create an interactive tutorial with Binder, a free service which creates a scalable docker R environment attached to a github/gitlab repository. According to binder, the limit is 100 users simultaneously with is perfect for teaching!

In fact, I was already aware of online tutorial using this setup without knowing how they worked:

• Generalized Additive Models in R by Noam Ross
• Supervised Machine Learning Case Studies in R by Julia Silge
• R-Bootcamp by Ted Laderas and Jessica Minnier
• Introduction to R by Quantargo

By following Florencia’s it is possible to create an interactive R tutorial for free very easily! The procedure described by Florencia and the three interactive tutorials examples as well as mine, are using the framework developed by Ines Montani called Juniper which will make the interface between the Binder docker R environment back end and the tutorial front end. Speaking of front end, Ines is providing a very fancy template using node.js and being deployed with Gatsby. At this point I’m throwing computer science jargon but my understanding of them is very limited. The most important is that it is working very well!

It’s not a perfect solution, see this blog post describing pros and cons for this solution, however it is working and for free.

Interactive {blogdown} using ThebeLab’s Framework

Even if Juniper’s framework is amazing, the content published is based on markdown files. I have nothing against markdown files but I do love Rmarkdown and I really missed them while publishing the tutorials. For this reason I googled “blogdown” + “binder” and found two very interesting discussions:

• The first that I found was initiated here in a question about the interactivity of bookdown documents. Someone came across the activity of ThebeLab which is providing interfaces to binder for python code (see examples here and here. This question was answered by Christophe Dervieux saying that binder was not supporting R at this time. Christophe definitely made some progress when he shared in this tweet his success in creating an interactive .Rmd
• The second discussion was on gitter.com initiated by Achintya Rao saying that he successfully managed to create an interactive blogdown.

After being in contact with Achintya and by seeing Christophe’s code, it is possible to identify the essential component to make magic happened:

1. The blogdown theme or the .Rmd file need to include a code linking it to the repository connected to the binder docker R environment and to the package thebelab which is interacting between both.

In Christophe’s code, this html code is included directly in the .Rmd file:

<!-- Some stuff from thebelab required for the magic -->
<!-- Configure and load Thebe !-->
<script type="text/x-thebe-config">
  {
    requestKernel: true,
    binderOptions: {
      repo: 'github_username/github_reponame,
    },
    kernelOptions: {
      name: "R",
      kernelName: "ir",
    },
  }
</script>

<!-- script for thebelab -->
<script src="https://unpkg.com/thebelab@latest/lib/index.js"></script>

Whereas for Achintya’s blogdown, the following code is included in a specific file ./themes/hugo-lithium/layouts/partials/head_custom.html:

<!-- Configure and load Thebe !-->
<script type="text/x-thebe-config">
    {
        bootstrap: false,
        requestKernel: true,
        binderOptions: {
            repo: 'github_username/github_reponame,
            ref: 'master',
            repoProvider: 'github',
        },
        kernelOptions: {
            name: 'ir',
        }
    }
</script>
<script src="https://unpkg.com/thebelab@0.4.0/lib/index.js"></script>

2. Both document are including a button to activate the code.

In Christophe’s code the button code and its action on the bootstrapThebe function are directly included in the Rmd file:

# ad a button
htmltools::tags$button(
  id = "activateButton",
  style="width: 100px; height: 50px; font-size: 1.5em;", 
  "Activate"
)

# js chunk
// thebelab js script
var bootstrapThebe = function() {
    thebelab.bootstrap();
}
document.querySelector("#activateButton").addEventListener('click', bootstrapThebe)

For Achintya’s blogdown, the code to create the button is included in a specific file ./themes/hugo-lithium/layouts/shortcodes/code.html and the code to trigger the bootstrapThebe is included in a specific file ./themes/hugo-lithium/layouts/partials/code.html. But to link these html files with the Rmd, each blogdown blog post have to include the following code:

knitr::opts_chunk$set(collapse = TRUE, 
                      attr.source="data-executable='true'",
                      eval = FALSE)

Adding the link to the repository connected to binder

I have hidden it to make it more generic and explicit but Christophe used the demo repo connected to binder https://github.com/binder-examples/r whereas Achintya has linked his blogdown to a repository hosted on his github.

In fact, the necessity of connecting a repository to binder and to indicate the link to this repository is also used in Juniper in a very similar way. However, instead of having a separated repository, Ines was connecting a branch of the same repository used for the deployment. From my github beginner experience, I think a distinct repository is easier to manage.

The necessity of having a distinct branch or repository is explained by Ines as follow in the readme of her template: “The reason they’re different is that binder forces a Docker container rebuild when a branch is updated. So, if we served our container out of master, it would rebuild every time we modified a chapter.md or an exercise.”

To build this binder docker image from a repository it is super easy, you just need two files on the root of the repository:

• a R script which contains all the package to install in order to run the code in your interactive chunks
• a text file containing YYYY-MM-DD snapshot at MRAN that will be used for installing libraries. See here for details. The you just need to go to binder.org fill your repository url and branch (if not master) and this is it!

You can have a look at this blogdown test containing interactive code chunks here (this blogdown works in the same way as Achintya’s so but it is hosted on my github repository and uses a binder docker image connected to my github repository as well).

clicking the below button will also launch the kernel and that could take some times to strat. Be patient…

Here is a chunk, not evaluated on purpose by Rmarkdown, and to be executed interactively, directly in this document.

print("Hello")

Next steps

For the moment, thanks to Achintya and Christophe’s work, I have a blog test will 2 code chunks that are interactive. The next move will be to convert my Juniper-mardown-node.js tutorial to a thebelab –rmarkdown-blogdown.

Another interesting part would be to integrate a code evaluation system like {gradethis} for example. I’m also wondering if {learnr} would work as well!