Intro to JupyterLab

QGreenland Researcher Workshop 2023

Note

We are going to demo a number of features around the use of JupyterLab in the following slides. Please plan to watch as we explain various features before trying them yourself in an exercise after the presentation.

What is JupyterLab?

👪 JupyterLab is a human-friendly interface to computation resources.

💻 You can do almost anything you can do on your personal computer!

JupyterLab logo

The JupyterLab logo is a screenshot from JupyterLab’s “Help -> About JupyterLab” pop-up in CryoCloud.

JupyterHub

CryoCloud: your personal JupyterLab in the cloud

• JupyterHub: https://hub.cryointhecloud.com
• Website: https://book.cryointhecloud.com

Cryocloud logo

JupyterHub is a system for creating many JupyterLabs, e.g. for classrooms

JupyterHub

Log in to CryoCloud JupyterHub with your GitHub username

• Important: select a 4GB server option
• Your JupyterLab workspace is dedicated, not shared!

Jupyterhub server selection

We encourage users to start with the 4GB RAM option to start. If individuals run into memory issues working with a dataset during the workshop, trying the 8GB option is reasonable.

Although each user has their own dedicated workspace and file system, compute resources are not completely isolated. For example, selecting a 4GB RAM server size results in a guaranteed allocation of 4GB but if more memory is free on the node a user may be able to utilize more than 4GB.

• No scheduler like on a supercomputer
  • Your computations will not interfere with anyone else’s

JupyterLab features

JupyterLab

Show what the CryoCloud JupyterLab looks like after signing in and selecting a server.

JupyterLab - memory/RAM usage

Highlight where to monitor memory usage. If a dataset is particularly large and/or an operation on the data is getting stuck, check memory usage.

If individuals run into memory issues working with a dataset during the workshop, trying the 8GB option is reasonable.

JupyterLab left side panel

We will talk about the left side panel first.

File Browser

• Drag & drop from your desktop
• Open many types of files and get a useful display
  • CSV will display as table
  • GeoJSON will display on a map
  • Images will open with an image viewer

JupyterLab file browser

Your home directory is dedicated to you. You will not be able to overwrite anyone else’s files, and vice versa. The shared* directories are the only common files.

Be very careful when deleting files from shared-public/, it’s possible to delete other people’s data.

If you need to delete a file in the file browser, select it and press the Delete key, or right-click a file and select “Delete” from the menu.

Running terminals and kernels

• Lists currently running Terminals and Kernels.

• If one of these apps gets ‘stuck’, you may need to shut it down and try again

• If you accidentally close a terminal or notebook tab, you can re-access it by clicking on its entry here.

JupyterLab Running Terminals and Kernels

We will not be covering the usage of the final three side panel views.

JupyterLab Launcher

Applications can be launched from the Launcher, opening a new tab/window for that application.

To open a new Launcher, click the + tab, File > New Launcher, or the Blue + button in the file browser left side panel.

Terminal

• conda install <package>
• mamba install <package>
• Common GDAL/OGR utilities: gdalinfo, ogrinfo, etc.

JupyterLab terminal

Conda and Mamba are already installed, and a notebook environment is pre-created. Use conda/mamba commands to install Python dependencies into the notebook environment.

Desktop

Desktop

The desktop opens in a new browser tab, not a new tab in JupyterLab.

Desktop

On first launch, select “Use default config”

Use default config

Desktop: file browser

The “Home” icon on the desktop shows the same files as JupyterLab File Browser.

Desktop file browser

There’s also a terminal emulator and other utilities often found in a desktop GUI environment.

Desktop: QGIS and QGreenland

Can open QGreenland!

Desktop with QGIS and QGreenland

Opening QGreenland should take ~2 minutes.

Do not use the logout function within the desktop, as this may make it difficult to get back into your desktop.

Desktop: logging out

Warning

Do not use “Logout” from the desktop environment!

To close the desktop, please close the window/tab that the desktop environment is open in.

TODO: add an image showing a “no” symbol over the logout menu?

Jupyter Notebooks

• A tool for Literate Programming
  • Showing your work
  • Tracking provenance
  • Telling a story
• See also:
  • Quarto
  • JupyterBook

Jupyter Notebook

At this point, do a live demo of the demo.ipynb notebook.

When demoing the notebook, ensure that we narrate double-clicking markdown cells to show the source of it. And also how to expand/collapse cells.

Also be sure to demonstrate how to create a new cell, change it’s type (Markdown, Code, …), and move cells around.

Note that execution order matters.

Finally, demo the sync.sh script which moves some data to fast local storage (qgis-data/). Before running, do rm -rf ~/qgis-data/* && rm ~/demo.ipynb. This step is important; without it, opening QGreenland could take multiple minutes. The qgis-data directory is where you should store any data if speed matters. E.g. if you have a 1GB dataset, it’ll be very important that it lives in fast storage!

/home/jovyan/shared/QGreenland/sync.sh

Shut down your server!

Important

At the end of each day, click File > Hub Control Panel and then click Stop My Server

Control Panel

Stop My Server

Shut down your server at the end of each day to save on cloud costs.

Any files you have created will remain next time you log in!

Exercise

💪 Getting started with JupyterLab