====== 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 |site_name| or in the ``Binder service``. .. tab-set:: .. tab-item:: In the |site_name| You can launch your dataset from the |launch binder| badge in the bottom left corner of the dataset page: .. image:: /images/binder/binder_1.png :width: 300 .. tab-item:: 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. .. image:: /images/binder/binder_4.png :width: 800 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. .. image:: /images/binder/binder_2.png :width: 800 .. 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. .. image:: /images/binder/binder_3.png :width: 800 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 |launch binder| badge in the bottom left corner of the dataset page to copy the URL for sharing an interactive version of your dataset. .. image:: /images/binder/binder_5.png :width: 300 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. .. image:: /images/binder/binder_6.png :width: 800 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. =================== ========================================================================== #. JupyterLab You can use this interface without any environment configuration files. JupyterLab comes with Python (conda) and the following preinstalled packages (via `repo2docker`_): .. code-block:: yaml - 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. .. tab-set:: .. tab-item:: Conda environment configuration file Create a Conda environment configuration file ``environment.yml`` and upload the file to the dataset. .. code-block:: yaml :caption: environment.yml name: env dependencies: - python=3.11 - pandas==2.* - plotly==5.* .. tab-item:: 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. .. code-block:: text :caption: runtime.txt python-3.11 .. code-block:: text :caption: requirements.txt pandas==2.* plotly==5.* If you would like to use the RStudio interface, upload a ``runtime.txt`` file in the following format: .. code-block:: text :caption: runtime.txt r----
.. 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. .. code-block:: r :caption: install.R install.packages("rmarkdown") install.packages("leaflet") #. 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: .. code-block:: none https://hub.binder.depositar.io/user/XXX/lab/ You can switch to the classic notebook by change it into: .. code-block:: none https://hub.binder.depositar.io/user/XXX/tree/ #. RStudio After specifying the R environment according to ``1. JupyterLab``, the RStudio IDE will be available on the JupyterLab. .. image:: /images/binder/binder_7.png :width: 800 #. Shiny After specifying the R environment according to ``1. JupyterLab`` and uploading the required ``server.R`` and ``ui.R`` (e.g. https://github.com/rstudio/shiny-examples/tree/main/034-current-time), the Shiny will be available on the JupyterLab. .. image:: /images/binder/binder_8.png :width: 800 .. note:: Since |site_name| 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 |site_name|. * 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 https://github.com/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 |launch binder| 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`_. .. _Binder: https://mybinder.readthedocs.io/ .. _Academia Sinica Grid Computing Centre: https://dicos.grid.sinica.edu.tw/ .. _`Binder Example: Sea turtle sightings in Taiwan`: https://data.depositar.io/en/dataset/binder-example-sea-turtle-sightings-in-taiwan .. _JupyterLab: https://jupyterlab.readthedocs.io/ .. _Jupyter Notebook: https://jupyter-notebook.readthedocs.io/ .. _RStudio: https://docs.posit.co/ide/user/ .. _Shiny: https://shiny.posit.co/ .. _repo2docker: https://github.com/jupyterhub/repo2docker/blob/main/repo2docker/buildpacks/conda/environment.yml .. _Posit Package Manager: https://packagemanager.posit.co/cran/ .. _Configuration Files: https://mybinder.readthedocs.io/en/latest/using/config_files.html .. _mybinder: https://mybinder.org/ .. _BinderHub: https://binderhub.readthedocs.io/ .. _Binder user guide: https://mybinder.readthedocs.io/ .. _Binder forum: https://discourse.jupyter.org/c/binder .. _Terms of Use: https://data.depositar.io/en/terms_of_use .. _Privacy Policy: https://data.depositar.io/en/privacy .. |launch binder| image:: /images/binder/badge_logo.svg