README.md

In karthik/holepunch: Configure Your R Project for 'binderhub'

Hole punch

What this package does

holepunch will read the contents of your R project on GitHub, create a DESCRIPTION file with all dependencies, write a Dockerfile, add a badge to your README, and build a Docker image. Once these 4 steps are complete, any reader can click the badge and within minutes, be dropped into a free, live, RStudio server. Here they can run your scripts and notebooks and see how everything works.

Motivation

Binder is an open source project that can take ~~any~~ most GitHub repos of notebooks (R or Jupyter) and turn them into a free, live instance that not only has all dependencies ready to go but also provides Jupyter or Rstudio server to run the code on. The instances are small and should not be used to demonstrate resource intensive computation. However they are ideal for reproducing papers/figures/examples and make a great addition to any public analysis project that is being hosted on GitHub.

Why this is awesome

• You can launch a free instance of Rstudio server from any of your projects on GitHub. The instance will have all of your dependencies and version of R installed and ready to go!
• Easily allow anyone (up to 100 simultaneous users) to replicate or modify your analysis
• Free

Limitations

• The server has limited memory so you cannot load large datasets or run big computations
• Binder is meant for interactive and ephemeral interactive coding so an instance will die after 10 minutes of inactivity.
• An instance cannot be kept alive for more than 12 hours

Installation

remotes::install_github("karthik/holepunch")
# Please report any installation problems in the issues

Setting up your project as a compendium (recommended)

If you are unfamiliar with the idea of research compendia, I highly recommend reading this paper by Marwick et al:

Marwick B, Boettiger C, Mullen L. 2018. Packaging data analytical work reproducibly using R (and friends) PeerJ Preprints 6:e3192v2 https://doi.org/10.7287/peerj.preprints.3192v2

and also looking through my presentation at RStudio::conf 2019 where I talk about this in detail.

library(holepunch)
write_compendium_description(package = "Your compendium name", 
                             description = "Your compendium description")
# to write a description, with dependencies. Be sure to fill in placeholder text

write_dockerfile(maintainer = "your_name") 
# To write a Dockerfile. It will automatically pick the date of the last 
# modified file, match it to that version of R and add it here. You can 
# override this by passing r_date to some arbitrary date
# (but one for which a R version exists).

generate_badge() # This generates a badge for your readme.

# ----------------------------------------------
# At this time 🙌 push the code to GitHub 🙌
# ----------------------------------------------

# And click on the badge or use the function below to get the build 
# ready ahead of time.
build_binder()
# 🤞🚀

Alternate setup method

If for some reason you really don't want to set up your project as a compendium, then set it up by creating runtime.txt and install.R. This build will take a very long time.

# Note that this particular approach will be super slow.
# And take just as long everytime you edit your code
library(holepunch)
write_install() # Writes install.R with all your dependencies
write_runtime() # Writes the date your code was last modified. Can be overridden.
generate_badge() # Generates a badge you can add to your README. Clicking badge will launch the Binder.
# ----------------------------------------------
# At this time 🙌 push the code to GitHub 🙌
# ----------------------------------------------
# Then click the badge on your README or run
build_binder() # to kick off the build process
# 🤞🚀

Testing this package

An easy way to test this package without writing any code is to visit the binder-test repo and follow the instructions.

Roadmap

The ETA for the first release of this package is fall 2019 (after renv goes to CRAN). Comments, suggestions for improving the workflow or any other comments welcome in the issues. Other planned features include:

• Full support for GitHub packages
• Support for Bioconductor packages
• Reference Binders to separate environment from code (still in early planning)

Code of conduct

Please note that the 'holepunch' project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

karthik/holepunch documentation built on Feb. 20, 2023, 5:21 a.m.