Have you ever found a GitHub repository with an interesting R package? Probably yes.
Probably, it also happened that you didn’t have access or willingness to launch RStudio and try the code from the vignette.

Even if not, there are many lazy busy people who don’t want to don’t have time to do this. Users would like to have an easy and effortless introduction to the R package, at the same time package developers would like to encourage as many people as possible to try out their tools.

If only there was a way to share your code in an interactive computational environment that can be shared and used by many remote users…

Oh hey! There is something like this: BinderHub - the server technology that turns computational material (e.g. Jupyter Notebook) into interactive computational environments in the cloud.
You can just click on the image below to see an example of such interactive notebook.

It is also possible to start an RStudio session which I’ll show at the end of this post.

Example image

How to use it

I discovered Binder by the Christoph Molnar’s repository with iml package which is a great tool and I really recommend you to check it out.

Using these interactive notebooks is very convenient because all you have to do is just look for the badge like this one: and click on it.

Right now, there are two repositories with my research group’s packages which are using Binder: auditor and DALEX. I hope we’ll provide such interactive tutorials for most of our tools, but until then you can try to play with those two mentioned above.

Let’s learn more about the Binder.

How it works

It is best to let the authors describe Binder themselves. Below you can read a part of the Binder documentation.

Binder makes it simple to generate reproducible computing environments from a Git repository. Binder uses the BinderHub technology to generate a Docker image from this repository. The image will have all the components that you specify along with the Jupyter Notebooks inside. You will be able to share a URL with users that can immediately begin interacting with this environment via the cloud. Binder’s goal is to enable as many analytic workflows as possible.

Now let’s see how to build a Binder repository.

How to turn your GitHub repository into a collection of interactive notebooks

In the Binder documentation, you’ll find detailed and extended instructions. Here, I’ll show a minimal example of the basic configuration in three easy steps.

  1. You need a GitHub repository with at least one Jupyter notebook.
    If you don’t have Jupyter installed on your computer, you can create a notebook online. Just chose the Try Jupyter with R option on the Jupyter website. However, it may be difficult to load some of the packages, so I suggest using the Jupyter installed locally on your computer.

  2. Create configuration files in your GitHub repository.
    Those files specify the requirements for building a Binder repository. They may be placed in the repository’s root or in a binder/ folder.
    Here you’ll find a toy example with configuration files. In your repository you should have at least two of them:

    • runtime.txt with specified MRAN snapshot that is formatted like:

      r-<YYYY>-<MM>-<DD>
      

      The example file content:

      r-2018-06-01
      
    • install.R that will be executed during build and is used to install libraries. The example file content:

      install.packages("auditor")
      install.packages("DALEX")
      install.packages("randomForest")
      

      If your GitHub repository contains an R package and is integrated with Travis CI, don’t forget to exclude configuration files from the build by adding them to .Rbuildignore. Otherwise, you’ll get a warning and notes during the package check.

  3. Building and launching a Binder repository

Now, you’re ready to launch your Binder repository. To do this, you need to visit MyBinder.org.

Example image

On the MyBinder.org, in the How it works section, you will find clear instructions on how to build and launch a Binder repository.

In short, you should provide a URL or a GitHub repository name. Optionally, you can specify a path to a notebook file which will be opened in your browser after building. The building may take some time. It depends on the packages that need to be installed. Afterward, the binder will build a Docker image and then will automatically send you to a live Jupyter session connected to your repository.

Now you can finally generate a binder badge !

Bonus: Rstudio session

As I wrote at the beginning of this post, it is also possible to start an RStudio session using Binder. I’ll show two ways to do it.

Example image