IT Services - How to Use JupyterLab

Overview

Our 2024 fall quarter images bring some major changes to the way notebooks are accessed on our cluster. Previously, users were directed towards an outdated interface known as Notebook 6. Our default is now known as JupyterLab, which brings numerous improvements to the Datahub experience.

Video Guide

(Coming Soon)

Main Differences Between Notebook 6 and JupyterLab

A summary of the new features:

Modular UI - You can now have multiple tabs in the same window and keep views such as the file explorer easily accessible.
Visual Debugger - Quickly and efficiently debug issues with your Python code via a new UI.
Integrated Git Sidebar Tool - A new (graphical) way to create and manage local git repositories.
GitHub Search Tool - Search for repos on Github and navigate their structure without leaving the window.
Dark Mode - Toggle between a light and dark theme for JupyterLab. Terminals have their own light/dark mode in the Settings tab.
Latex Editor/Exporter - Edit and export LaTeX (+ bib) files as PDFs.
Markdown Editor/Exporter - Edit and export Markdown documents as PDFs.

General Guide

New UI

This is JupyterLab, the default interface that all of our images now use. There is a file browser on the left with several additional extensions installed by default. On the right is the "launcher," which includes a list of shortcuts to several common utilities.
To navigate the file browser, double click on which directory/file you would like to access. To go back to your home directory, click on the folder icon (highlighted in red below).
JupyterLab also now supports dark mode.
You can switch between light and dark mode by going to Settings>Theme.
To turn off your pod, you can go to File>Hub Control Panel followed by Stop My Server. You can also press My Server to return to JupyterLab.

Writing + Debugging a Notebook

To open a notebook, double click on a .ipynb file and you'll be greeted with this:
You'll notice that most of the buttons are from Notebook 6. The play button runs the code in a target cell, the stop button stops currently running code, and the validate button allows users to ensure that their notebooks pass any given tests. The main advantage of JupyterLab however is that it allows you to have multiple notebooks open in the same tab via the + button in the status bar.
There are many ways to add a new cell. The buttons outlined in red below add a new cell. The button highlighted in blue clones the current cell and adds it below. The buttons highlighted in orange add a new cell above the currently selected one and below the currently selected one respectively.
A cell can be three possible types: code, markdown, and raw. To switch between them, select the cell you would like to change and click on the below dropdown menu in the status bar.
One of the more notable new features of JupyterLab's Notebook editor is the visual debugger. You can use it to easily diagnose issues with your code instead of relying on more primitive methods such as printing variable values. To enable the debugger in your notebook, click on the little bug icon in the top right corner.
Once the button turns orange, the debug UI will appear on the right side of your screen and the line numbers in your cells will be enumerated. Clicking on a line sets a breakpoint as a red dot. Running the cell will cause the Python interpreter to halt at the first breakpoint and display extensive debugging information about the current cell. To proceed to the next breakpoint after running the cell, click on the play button in the Callstack menu. Once all breakpoints have been passed, execution will proceed as normal.

NBClassic/Notebook 7

If you don't prefer the JupyterLab UI, you can also try Notebook 7 or NBClassic which more closely resemble Datahub's previous UI. Notebook 7 has most of the features that JupyterLab does such as the visual debugger, whereas NBClassic does not. Please keep in mind that we consider both of these alternatives to be more experimental in nature. If you have any major issues, please fallback to JupyterLab and send them to datahub@ucsd.edu.
The quickest way to access Notebook7/NBClassic is by using the Open In dropdown menu on a selected notebook.
Navigating the Notebook7 UI should be more straightforward especially if you've used Notebook 6. Double clicking on a notebook will open the editor in a new browser tab.
As for the second option, NBClassic is almost identical to Notebook 6 but any extensions such as NBGrader are no longer supported. We cannot guarantee long-term support for this view.

LaTeX/Markdown Editor

We're happy to announce that the Jupyter team has added a native LaTeX parser (the backend being xelatex + bibtex) extension into the latest iteration of JupyterLab. This means that students can drop their assignments into JupyterLab and get to work. While the instructions below are for LaTeX, there is also a Markdown editor in JupyterLab that works largely in the same way.

Begin by either importing or creating a .tex file. The editor automatically highlights special keywords with appropriate syntax coloring, making the document more readable and easier to navigate.
To render your properly-formatted, right-click anywhere while in the editor and select Show Latex Preview
An error will be displayed from the backend LaTeX parser on failure.
If the parser succeeds, a rendered PDF will then be opened on the right side of your screen.
To download your LaTeX document as a PDF, simply click on Show Latex Previewand download the generated PDF from the file browser.

NBGrader

While the NBGrader package itself has not changed too substantially from Notebook 6, there have been some notable changes to conform with JupyterLab's new UI.

Formgrader is accessible via Nbgrader>Formgrader.
The JupyterLab UI, but with the NBGrader dropdown tab highlighted.

Create a formgrader assignment as normal and add a notebook file to its corresponding directory. There are two buttons to create a new assignment while you're editing a notebook. One is accessible via the Nbgrader dropdown and the other is always on the right side of the notebook.
The JupyterLab UI, but with the NBGrader dropdown tab highlighted. The "Create assignment" option is highlighted in red. There is also a "Create assignment" tab on the right side of the notebook.

The Create Assignment UI should appear with each cell having several available grading options. If you need a refresh on what each option does, you can take a look at our Nbgrader documentation for more information.

A JupyterLab notebook with the NBGrader assignment UI opened. It shows each of the individual cells in the notebook and their type (read-only, autograded task, etc.)

Students can fetch/submit their assignments by going to Nbgrader>Assignment List. The UI is nearly identical to Notebook 6's.
The page that shows up when NBGrader -> Assignments is clicked in the dropdown. It shows assignments as students would see them, with the ability to either download/submit the assignment or look at the instructor's feedback.

If you have any questions or concerns, please email datahub@ucsd.edu or submit a ticket.