GETTING STARTED WITH BINDER

Author: Tony Castronova acastronova@cuahsi.org
Last edited: 02.07.2020

Description

Connecting the MyBinder compute capabilities with the HydroShare repository enables scientific reproducibility, replicability, and scientific collaboration across transdisciplinary water science domains. This document outlines the benefits, general use, and advanced use of Binder for these purposes.

What is Binder?

The Binder project offers an easy place to share computing environments to everyone. It allows users to specify custom environments and share them with a single link. Use-cases involve workshops, scientific workflows and streamline sharing among teams.

The Binder Project builds tools that reward best-practices in reproducible data science by utilizing community-developed standards for reproducibility. When repositories follow these best-practices and are hosted in an online repository, then Binder automatically builds a linkable environment anybody can access.

For more information see a complete description on their webpage

Advantages

The primary advantage of making your HydroShare data and workflows "Binder-compliant" is the ability to...

Binder Configuration Files

Binder configuration files are used to build your compute environment on-the-fly and are created specifically individual resources. An abbreviated list of these files is shown below, however a comprehensive list can be found here.

Note: A single HydroShare resource must contain one or more of these files.

• environment.yml - Install a Python environment
• requirements.txt - Install a Python environment
• setup.py - Install Python packages
• Project.toml - Install a Julia environment
• REQUIRE - Install a Julia environment (legacy)
• install.R - Install an R/RStudio environment
• apt.txt - Install packages with apt-get
• DESCRIPTION - Install an R package
• manifest.xml - Install Stencila
• postBuild - Run code after installing the environment
• start - Run code before the user sessions starts
• runtime.txt - Specifying runtimes
• default.nix - the nix package manager
• Dockerfile - Advanced environments

Basic Configuration Examples

A simple Python configuration may look like the following:

HydroShare resource files

.  
+-- my_script.py   
+-- binder_folder     
|  +-- requirements.txt   
|  +-- runtime.txt   

File Contents

my_script.py

  
import numpy  
import pandas  
...  

requirements.txt

numpy==1.18.1  
pandas==1.0.1  

runtime.txt

python-3.8.1  

A complete example of this can be found at link.

Advanced Recipe Examples

Further Reading

Examples