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