Jupyter notebooks are web applications that combine text, code and output (https://jupyter.org/). Jupyter supports over 40 programming languages.
Jupyter notebooks can be used to analyze data stored in openBIS.
It is possible to connect to a JupyterHub server and launch Jupyter notebooks directly from the openBIS interface. This feature is not available by default, but needs to be enabled and configured by a system admin. JupyterHub docker containers are available from our download page: openBIS download. Further documentation can be found here: JupyterHub for openBIS
How to use Jupyter notebooks from openBIS
Jupyter notebooks can be opened at every level of the openBIS hierarchy (Space, Project, Experiment/Collection, Object, Dataset) from the More… dropdown menu, as shown below.
Jupyter notebooks can also be launched from the main menu, under Utilities, as shown below.
Note: if you use SSO for authentication (eg. Switch aai), the first time you want to work with a Jupyter notebook, you first need to open the Jupyter Workspace and then launch a notebook from wherever you want to open it.
To create a notebook, it is necessary to enter:
- The dataset(s) needed for the analysis.
- The owner of the Jupyter notebook. Jupyter notebooks are saved back to openBIS as datasets, and these belong either to an Experiment/Collection or to an Object. The owner is the Experiment/Collection or Object where the notebook should be stored.
- The directory name. This is the name of the folder that will be created on the JupyterHub server.
- Notebook name. This is the name of the Jupyter notebook
Jupyter notebooks can also be opened from a Project, Experiment, Experimental Step choosing the corresponding option in the More drop down menu. When opening notebooks from an Experiment or Experimental Step, all connected datasets are automatically selected.
Overview of Jupyter notebook opened from openBIS.
The Jupyter notebook opened from the openBIS interface contains some pre-filled cells. All cells need to be run. The information of two cells should be modified: Name of the dataset where the notebook will be stored and Notes (in red below).
If you get this message “Session is no longer valid. Please login again” replace the code in the cell after Connect to openBIS with the following:
Enter your username in the cell and when you run the cell, you will be prompted to enter your password.
If you are running the latest JupyterHub version released in July 2021 (available at https://hub.docker.com/u/openbis) you do not need to enter username and password, as authentication uses the openBIS session token. If your session token is not renewed you can enter it manually, as shown below:
The session token can be copied from the User Profile under the Utilities Main Menu in the ELN.
Your script should be written in the section named Process your data here, that contains one empty cell (see below). You can, of course, add additional cells.
After the analysis is done, the notebook can be saved back to openBIS, by running the last few cells which contain the information about where the notebook will be stored (as shown below).
A JupyterLab openBIS extension is also available: JupyterLab openBIS extension
This enables connectivity between JupyterLab and openBIS.