{holepunch} a {drake} and put it in a Binder

Matt Dray / 2019-08-25 / 3 min read
Categories: code tutorial
Tags: binder docker drake r reproducibility rstudio

A Drake meme, where Drake, the musician, reacts negatively to GitHub's 'clone or download' button and positively to the 'launch binder' repo badge.

tl;dr

Binder lets people explore your GitHub-based R code in a live, browser-based instance of RStudio – for free. Set-up for R projects is quick with {holepunch}.

I’ve used {holepunch} on my {drake} demo repo. Click the ‘launch binder’ badge in the repo’s README.

Icing on the {drake}

I wrote about how Will Landau’s excellent {drake} package could be used to minimise errors and speed up the production of statistical reports by the UK government. I put a demo of this in a GitHub repo.

There are two things I’d like:

  1. To improve trust further, citizens should be able to quickly open and explore the code behind a statistical report in the environment that the analyst was actually working in, with the correct R version and package dependencies.
  2. When I’m demonstrating the {drake} example, everyone in the room should have access to the same, consistent environment. This will minimise technical issues and ensure the code is being run in the intended environment.

Turns out that these issues can be solved with Binder. Point 1 is addressed by adding a special badge to your README. This helps solve Point 2, proven by Landau in his {learndrake} course-in-a-package repo.

But what is Binder?

In a Bind(er)

Binder is an open source project that makes it easier to share and explore the code from a GitHub repository.

The repo owner specifies an environment (e.g. R version and package dependencies) and people can click a badge in the README to launch the code in a live instance of RStudio. Magic.

Here’s what the Binder badge looks like in the README:

The README for the drake-egg-rap repo showing the Binder badge.

Click it to launch the Binder loading page:

The Binder launch page saying 'starting repository' with the name of GitHub repository.

That results in RStudio being launched in the browser with all the folders and files from the repo:

RStudio in a browser window, showing R's start-up text in the console pane and the contents of the home folder in the files pane.

Some caveats:

  • This may take a short while to load. You may need to retry the build or try a different browser if it fails to load at all.
  • It may not be available for free forever.
  • There’s a maximum repo size of a couple of gigabytes.

{holepunch}-drunk

But wait: Karthik Ram has made the {holepunch} package so that R users can set up Binder for their repo in a just a few lines of code.

Do read the docs, but after install.packages("holepunch") and library(holepunch):

  1. write_compendium_description() to create a DESCRIPTION file listing the repo’s dependencies (just like what you need for an R package)
  2. write_dockerfile() to set up a dockerfile (from The Rocker Project) that installs RStudio and an R version of your choice
  3. generate_badge() to get some code for a ‘launch binder’ badge that you can copy-paste to your repo’s README

Then you can push the changes to GitHub and the ‘launch binder’ badge will appear your README. Clicking it generates an RStudio instance with the specifications as per the DESCRIPTION and dockerfile.

So, not many steps to achieve something this cool!

Read Karl Broman’s blog post for another view from an R user and check out Karthik Ram’s rstudio::conf 2019 talk (see the slides or watch the video).