Jupyter Environment

JupyterLab is a user-friendly tool for working with data and code. Users can customize it by adding extra features and connecting it with other software. This makes organizing work and interacting with data more manageable. For more detailed information, please visit the JupyterLab documentation.

Terrascope users can use it for free and have direct access to the Terrascope datasets. The Terrascope JupyterLab environment is accessible after logging into the Terrascope platform with its credentials.

Notebooks are accessible after logging in to the Terrascope Jupyterlab Terrascope Notebooks site.

The notebooks service is subject to the Terrascope networking policy.

Notebook samples

At the end of 2021, Python 3.6 reached its end of life, so the platform-provided Python 3.6 interpreter is no longer available. The default Python interpreter will now be Python 3.11, which is already provided.

To change the Python version in the JupyterLab environment, click the current version indicator in the upper right corner, labelled ‘Switch kernel’ when hovered over. A drop-down box will appear (see Figure 1), enabling the selection of the preferred version.

Figure 1: Choosing the preferred Python version.

By default, sample notebooks are in the folder /notebook-samples. All these samples are adapted to the Python 3.11 interpreter.

These samples are divided into two sections: Terrascope and OpenEO samples.

Terrascope Samples:

  • Beginner: Notebooks that explain basic data reading and analysis principles, located in /notebook-samples/terrascope-samples/Terrascope/Beginner
  • Advanced: Notebooks that explore various datasets and extended data analysis tools, located in /notebook-samples/terrascope-samples/Terrascope/Advanced

OpenEO Community Samples:

  • A wide variety of community-contributed openEO Python examples showcasing different use cases can be found in /notebook-samples/openeo-samples/python.
  • A brief description of the use case is provided in the README.md file in the Python directory.

To ensure the latest version of these samples is available, these notebooks are automatically updated for each user on Monday at 2 a.m.

The update process includes:

  • The local changes are stashed (git stash -U)
  • Next, new commits for the repository and submodules get pulled with git pull --rebase --recurse-submodules.
  • Finally, the submodules are updated to ensure that when a new submodule is added, the repository will also contain the new submodule. This is done with git submodule update --init --recursive.

To get the local changes back, users can execute git stash pop. This resets the local changes, but it is possible to have some merge conflicts.

Notebook Git pull

To obtain the most recent version of Notebooks, users can pull from the Terrascope Notebook Git repository. If a user still needs to open one of the sample Notebooks, the JupyterLab environment will display the Launcher (see Figure 2). In the Launcher, select ‘Terminal’ under the ‘Other’ category.

The Launcher can also be accessed by clicking the + in the upper left corner of the screen. Once the Terminal is open, users can verify the current directory using the pwd command, which should typically be /home/users/<username>.

To store the pulled Notebooks in a different location, such as /data/users/Private/<username>, users can change directories using the cd command accordingly.

In the required directory, pull from the Terrascope Notebook Git repository using the command git pull --recurse-submodules.

Sharing notebooks

Notebooks can be shared with other Terrascope users by placing them in the Public folder, from where another user can copy them. Here’s how to proceed: Assume user1 wants to share a notebook with user2.

First, open a Terminal window in the Notebook environment (see Figure 2).

Figure 2: Notebook Terminal button in the Launch tab.

Then, navigate to the folder from where the files should be copied and use cp <source_path> /data/users/Public/user1/, for example:


cp /data/users/Private/user1/notebook-samples/Terrascope/Advanced/Sentinel-2_advanced.ipynb /data/users/Public/user1/

The notebook is then accessible to other users in the Public folder; see Figure 3.

Figure 3: Accessing a notebook from the Public folder.

Installing additional packages

Users can install additional Python packages in two ways within the Notebook environment:

  1. Using Terminal:
    • Open the terminal from the Launch tab (see Figure 2).
    • Activate the python3 environment with conda activate python3.
    • Install the package with pip install cyclopts --user.
  2. Within a Notebook Cell:
    • Add a new cell with pip install cyclopts --user for Python 3.11 notebooks.

Packages installed with the ‘–user’ flag are stored in the user’s home directory. This ensures persistence across the notebook when it restarts. However, installing other packages might lead to issues if new dependencies are introduced in the future. Users can use pip install without ‘–user’ or conda install for temporary installations. Use conda install -n python3 to install packages in the python kernel.

Basic Notebook commands

Working with a notebook is convenient, and the supporting text should enable a quick understanding of the code presented. Some basic Notebook commands are listed below.

Keyboard shortcut Command
Ctrl + Enter Run a cell
A insert a cell above current cell
B insert a cell below current cell
C copy a cell code
V paste a cell code
DD delete a selected cell
M change a ell to Markdown (text) mode

Some additional Notebook keyboard shortcuts and a Notebook tutorial can be helpful for additional information.

Restart Jupyterlab environment

In some cases (e.g., after updating the JupyterLab environment), users may need to restart their JupyterLab container. Here’s how to do it:

  1. Go to Help > Launch Classic Notebook in the menu bar.
  2. Click the Control Panel button in the upper right corner.
  3. Press the Stop My Server button.
  4. After waiting a few seconds, click the Start My Server button to initiate a new JupyterLab instance.
Back to top