Binder

Binder is an online service for building and running computational environments in the browser, which can be used to reproduce and demonstrate research results hosted by code repositories.

Note

• This feature is a work in process. If you have any comment or feedback, please contact us.

• The computing resource is provided by Academia Sinica Grid Computing Centre, Grant No. AS-CFII-112-103.

Features

• Load public datasets and create computational environments such as JupyterLab and RStudio. Programs written in Python, R, … are to be used together with data and resources in the loaded dataset.

• Create a cloud computational environment with a single click. There is no need to install packages on your computer.

• Customize your Binder environment and install extra packages through configuration files.

How to Use

Prepare a dataset for the Binder service

A dataset which can be used with the Binder service (hereafter referred to as binder-ready dataset) contains the following files:

• (Required) The programs and data for analysis: The code (e.g. Python, R) to be run and the data to be processed.

• (Optional) An environment configuration file: The file that specifies packages that should be installed in the environment and the scripts to be run after installing the environment. If the configuration file is not provided, Binder will build a default JupyterLab environment.

Take this binder-ready dataset (Binder Example: Sea turtle sightings in Taiwan) as an example, the dataset contains three files:

• TurtleSpot2022_v2 (The data to be analyzed. CSV format.)

• Example Jupyter notebook (A Jupyter Notebook contains a Python program. Ipynb format.)

• Conda environment file (An environment.yml environment configuration file that specifies which Python version and packages to install in the built JupyterLab environment.)

Launch your dataset

You can launch your dataset either in the depositar or in the Binder service.

In the depositar

You can launch your dataset from the badge in the bottom left corner of the dataset page:

In the Binder service

You can also head to Binder service: https://binder.depositar.io/ to run a binder-ready dataset.

Specify the CKAN dataset repository and paste the URL of the dataset.

Then click the launch button to start the Binder.

Note

The ARK URL of the dataset is not supported at this time.

Binder will create an environment and install required packages according to the given environment configuration files. You can also see the logs generated by the build process.

Note

Regarding the environment configuration files, please refer to the next section (Supported Environments and Customization).

If the build process has been completed, Binder will open the environment automatically. In this example, a JupyterLab will be opened.

Then you can run the analysis and show the results in the JupyterLab environment.

Share the URL of the computational environment

You can right click on the badge in the bottom left corner of the dataset page to copy the URL for sharing an interactive version of your dataset.

You can also copy and share the URL through a button in the Binder service after specifying the CKAN dataset repository and pasting the URL of the dataset.

Supported Environments and Customization

Binder supports the following interfaces:

Interface	Description
JupyterLab	The default interface. An IDE containing Python, R, and Julia environment.
Jupyter Notebook	The classic Jupyter notebook interface.
RStudio	An IDE for R statistical language.
Shiny	A package for building interactive web applications from R.

1. JupyterLab

   You can use this interface without any environment configuration files.

   JupyterLab comes with Python (conda) and the following preinstalled packages (via repo2docker):

   - python=3.10
   - nodejs=18
   - pip
   - ipywidgets==8.*   # https://github.com/jupyter-widgets/ipywidgets
   - jupyter-offlinenotebook==0.2.*   # https://github.com/manics/jupyter-offlinenotebook
   - jupyter-resource-usage==0.7.*   # https://github.com/jupyter-server/jupyter-resource-usage
   - jupyter_server==1.*   # https://github.com/jupyter-server/jupyter_server
   - jupyterhub-singleuser==3.*   # https://github.com/jupyterhub/jupyterhub
   - jupyterlab==3.*   # https://github.com/jupyterlab/jupyterlab
   - notebook==6.*   # https://github.com/jupyter/notebook
   

   You can specify the version of Python and packages to be installed through one of the following two ways:

   Note

   Please upload the files mentioned below as individual resources to the binder-ready dataset.

   Conda environment configuration file

   Create a Conda environment configuration file environment.yml and upload the file to the dataset.

   environment.yml

   name: env
   dependencies:
     - python=3.11
     - pandas==2.*
     - plotly==5.*
   

   runtime.txt and requirements.txt

   Create a runtime.txt and a requirements.txt to specify the Python version and the packages, respectively. Then upload the two files to the dataset.

   runtime.txt

   python-3.11
   

   requirements.txt

   pandas==2.*
   plotly==5.*
   

   If you would like to use the RStudio interface, upload a runtime.txt file in the following format:

   runtime.txt

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

   Note

   RVERSION is the R version. YYYY-MM-DD is the snapshot on Posit Package Manager of that day for setting up the R runtime. E.g. r-4.3.3-2024-02-29.

   And, you can upload the install.R to specify the R packages to be used in the R environment.

   install.R

   install.packages("rmarkdown")
   install.packages("leaflet")
   

2. Jupyter Notebook

   If you prefer the classic Jupyter Notebook, just replace /lab/ with /tree/ in the default JupyterLab URL. For example, for the following URL:

   https://hub.binder.depositar.io/user/XXX/lab/
   

   You can switch to the classic notebook by change it into:

   https://hub.binder.depositar.io/user/XXX/tree/
   

3. RStudio

   After specifying the R environment according to 1. JupyterLab, the RStudio IDE will be available on the JupyterLab.

   

4. Shiny

   After specifying the R environment according to 1. JupyterLab and uploading the required server.R and ui.R (e.g. rstudio/shiny-examples), the Shiny will be available on the JupyterLab.

   

   Note

   Since depositar doesn’t allow creating subfolders, please upload files required for Shiny as individual resources to the dataset.

   Please refer to the Configuration Files section on the Binder user guide for further information about the environment configuration files.

Frequently Asked Questions

• Is the Binder service free to use?

  • Yes. A kind reminder: the Binder service is subject to the Terms of Use and Privacy Policy of the depositar.

• What’s the difference between this service and the mybinder?

  • mybinder is a public service provided by the Binder project and built upon the BinderHub. Our Binder service is also based on BinderHub but extended with support for CKAN datasets.

• Where can I find an example of binder-ready repository?

  • Please refer to the binder-examples GitHub organization.

• Why can’t I run my dataset in the Binder service?

  • If you make your dataset private, the dataset page won’t show the badge and you can’t run the dataset in the Binder service.

  • If there are errors in the configuration files, the building process may fail.

• What are the service’s restrictions?

  • 2 GB RAM

  • 1 CPU core

  • 10 minutes inactivity timeout

  • 2 GB provisional storage

  • We do not offer persistent storage.

• Can I have more RAM / CPU cores / storage?

  • Please contact us.

• I have a question about the Binder service.

  • Please refer to the Binder user guide or join the discussion at the Binder forum.