Jupyter Notebooks are an interactive code environment where live code, equations, visualisations and narrative text can be combined.

The ecocloud Platform supports Jupyter Notebooks with these languages:

• Python (installed with the SciPy packages); or
• R (statistical programming language)

Jupyter Notebooks are accessed through the JupyterLab user interface in the ecocloud Platform. JupyterLab can be used for other tasks, such as to manage files on the server’s temporary storage (see storage overview) and for writing R programs in RStudio (see using RStudio). This article only covers the use of Notebooks.

A single server can run multiple Notebooks. A single server is started to run the JupyterLab user interface and the Notebooks.

The sections below describe actions on the Jupyter server:

• Launching a Jupyter server
• Return to a running Jupyter server
• Terminating a Jupyter server

And actions that can be performed on Notebooks, once a Jupyter server is running:

• Creating a new Notebook (which also starts it running)
• Saving a Notebook to a file
• Shutting down a running Notebook (so it is not running)
• Starting up a Notebook from a file
• Closing a Notebook (and leaving it running)
• Opening a Notebook (that is already running).

Server operations

Launch server

1. Go to the tools page ⓔ.
2. Follow the link for either "R (RStudio and Jupyter)" or "Scientific Python (SciPy Jupyter)". The hub control panel will appear.
3. Press the “Start My Server” button. The “Spawner Options” page will appear.
4. Select either “SciPy Notebook” or “RStudio Notebook” (depending on if you want to use Python or R) and press the “Spawn” button. The JupyterLab page will appear.

Note: if you do not see the "Start My Server" button, it could be because another server is already running. Currently, a maximum of one server can be run, so you will need to terminate the running server before another can be launched. It could also be because another server is in the process of being terminated, in which case please wait a minute before trying again.

Return to server

If you have closed the browser tab showing the JupyterLab interface, you can return to it by:

1. Going to the ecocloud Dashboard ⓔ.
2. Press the "Open" button next to the running server.

Important: this only works if the JupyterLab interface is not already in another tab. If it is in another tab, it will bring up a dialog box asking you to "Please use a different workspace." Close all the tabs showing the JupyterLab interface and try again.

Terminate server

When finished with the JupyterLab server, it should be terminated so the resources it uses is freed up.

1. Save your data. This is very important, since all data in the server’s temporary storage will be lost when the server is terminated.
   1. Check that all notebooks and scripts you want to keep are saved to your workspace storage.
   2. Check that all input/result data you want to keep are saved to external storage.
2. From the "Hub" menu choose "Control Panel". The hub control panel will appear.
3. Press the “Stop My Server” button. Wait a few seconds for the “Stop My Server” button to disappear.
4. Close the browser tab containing the hub control panel.
5. Close the browser tab containing JupyterLab (ignore any error dialog that has appeared on it).

Caution: save any changes to the Notebooks before terminating the server. The server does not prompt you to save any unsaved changes.

The saved version of any notebooks you have running will be automatically started the next time JypyterLab is launched. If you do not want this to happen, first shutdown the notebook before terminating the server.

Notebook operations

New Notebook

From the JupyterLab page, a new Jupyter Notebook can be created by:

1. In the launcher (right pane), under the “Notebook” section, press the “Environment” button. For Python, the button is called “Environment (conda_py35)”; and for R, the button is called “Environment (conda_r_r34)”. A new Jupyter Notebook will appear.
2. Use the notebook. For example, enter some Python/R code (e.g. “6*7”) into the field and press the “Run” button (right pointing triangle in the toolbar).

A new notebook is automatically started. It is running and using compute cycles from your server. If you are no longer using the Notebook, you should shutdown the Notebook so those compute cycles can be used for running other Notebooks.

Save Notebook

To save changes made to the Notebook:

1. From the “File” menu choose “Save Notebook As”
2. Enter the name of the Notebook file. This should be a name under the workspace folder, for example "workspace/my-notebook.ipynb".
3. Press the “Save” button.

Important: The "workspace" directory should be added to the front of the file name. If that is not done, it will save it to the home directory, which is not preserved when the server is terminated (i.e. your notebook will be lost, even though it has been saved). The home directory is outside the "workspace" directory, and hence it is a part of the server's scratch storage (which is lost when the server is terminated).

Shutdown Notebook

A shutdown Notebook is no longer running. Note this is different from terminating the Jupyter server, which stops all running Notebooks. A Notebook can always be started up again, if you have saved it to a file.

If the Notebook is visible:

1. From the “File” menu, choose “Close and Shutdown Notebook”.

If the notebook is not visible:

1. Clicking on the “Running” tab along the left edge of the window.
2. Under the “Kernel sessions” section, press the “shutdown” button to the right of the notebook you want to shutdown.

Caution: save any changes to the Notebook before shutting down the Notebook. JupyterLab does not prompt you to save any unsaved changes.

Startup a Notebook

Runs a Notebook from a file.

1. Click on the “Files” tab on the left edge of the window.
2. Use the file browser (let pane) to find the notebook file.
3. Double click on the notebook file. It will open in a new tab in the right pane.

When finished, save any changes and close or shutdown the notebook.

Close Notebook

Closing a notebook hides it, so you can’t see it anymore. A closed notebook is still running on the server.

1. To close the notebook, from the “File” menu choose “Close Notebook” or click on the cross in the Notebook’s tab.
2. You will be prompted to confirm the shutdown operation. Press the "OK" button.

A closed Notebook is still running and using compute cycles from your server. If you are no longer using the Notebook, you should shutdown the Notebook so its compute cycles can be used for running other Notebooks.

Open Notebook

To open a closed notebook (i.e. one that is still running):

1. Click on the "Running" tab along the left edge of the window.
2. Under the "Kernel sessions" section, single click on the name of the notebook.