Jupyter Notebooks

CoCalc offers several options for hosting running Jupyter Notebooks online.

What’s a Jupyter Notebook?

A Jupyter notebook is a specific filetype with the ending .ipynb, which records an interactive session with a Kernel. It made up of cells, which can either store one or more lines of code or formatted text. When you run a cell – which evaluates the piece of code in the cell via the active kernel session – you can see its output after the calculation is done. This combination of communicating back and forth with a kernel and adding descriptive text makes this form of document very attractive.

There are many Kernels available, which allow you to choose the programming language and environment you want to work. A uite popular choice is Python3, but there are also SageMath and others. Our page on Jupyter Kernel Selection shows how to set the kernel.

Note

Make sure and double-check that you’re working with a suitable kernel for your calculations!

CoCalc Jupyter Notebook Basic Features

By default, a Jupyter notebook on CoCalc has all CoCalc’s core features, including real-time collaboration, side chat, and TimeTravel. Read more in our blogpost. The basic user interface looks like the following:

_images/jupyter-notebook-cocalc-1.png

Above the main area is a menu bar and a button row:

  • The menu bar contains all commands, and in particular the Kernel menu is for changing it if necessary.
  • The button row gives you a one-click access to Run the current cell (otherwise press your Shift+Return keys), a way to restart the kernel (which clears the current session) and a Save button to make sure CoCalc has stored the file. The Time Travel button allows you to see previous versions of that notebook, such that you can go back in time to recover from a bad change.
  • Active cell: in the screenshot above, the blue bar on the left and a blue border around a cell indicates that this is the currently active one. Actions like Run, Delete Cell, etc. operate on the currently selected cell. It is also possible to select more than one cell.
  • Execution counter: On the left of each cell, there is an execution counter In [ x ]. The number x increases each time a cell is being run. After the kernel stopped and restarted, that counter starts again at 1.
  • The output of code cells is below the input cell. For example, Out [7]: is the output of cell In [7]:. In the right hand corner of the input cell is some information about how long it took to calculate the result.
  • Text cells are slightly different. Select “Markdown” in the [ Code ] dropdown menu in the button bar to change a code cell to such a markdown text cell. There, you can use Markdown to format the text. Similar to code-cells, either Run these text cells to see the processed Markdown code or press Shift+Return. To edit a text cell, either double click it or press your Return key.
  • Saving: more general, the nice things about Jupyter Notebooks is that they save all your intput and output in one single file. This means you can download or publish the notebook as it is, and everyone else sees it in exactly the same way.

CoCalc Jupyter Notebook Enhancements

These enhanced features are available in CoCalc Jupyter notebooks:

  • cell numbers: Cells are numbered consecutively at upper right. Unlike execution numbers shown in brackets at left, these don’t change when you re-run a compute cell or go blank when you clear output, and markdown cells are numbered as well as code cells.
_images/jup-cell-num-timing.png
  • run time for compute cells: When a compute cell is executed, the amount of time it takes is displayed at upper right. See preceding figure.
  • table of contents: Table of contents level (indicated by font size) is the same as markdown heading level, i.e. “#” for top level, “##” for second level, etc. Click the “Contents” button in the “Notebook” menu at the top of a notebook, or select “File –> Table of Contents”, or split the frame and change one of the resulting frames to “Table of Contents”. Each entry in the table of contents is a clickable link that takes you to the corresponding cell in the notebook.
_images/jup-toc2.png
  • slideshow CoCalc notebooks offer you a shortcut for making a slideshow. Select “View” > “Cell Toolbar…” > “Slideshow” to add a Slide button above the right of each cell. For each cell, you can specify whether it is a slide, subslide, or fragment. To view the slideshow, click the “Slideshow” in the “Notebook” menu at the top of a notebook, or select “File” > “Slideshow”, or split the frame and change one of the resulting frames to “Slideshow”. The latter allows you to view the original notebook side-by-side with the slides.
_images/slideshow-1.png

enabling “Slide” button in cell toolbar

_images/slideshow-2.png

selecting slide type for each cell

When presenting, the next slide is to the right, while the next subslide is below. Fragments are revealed within the present slide. Click in the slideshow and then click “?” to see a list of keyboard shortcuts. If you modify the notebook, you can update the slideshow by clicking in the toolbar above the show and clicking “Build”, or by clicking “File” in the toolbar above the notebook and again selecting “Slideshow”.

_images/slideshow-3.png

original notebook side by side with slideshow

Note: the legacy method of creating and presenting a slideshow by using a separate Linux terminal command and starting a small web server is still available by clicking “File” > “Slideshow via nbconvert…”.

  • nbgrader integration: CoCalc offers nbgrader support without adding separate Jupyter extensions. This ehancement is in under active development. See nbgrader in CoCalc for more information.

Jupyter Widgets

Jupyter Widgets are Python objects that let you build interactive GUIs for your Jupyter notebooks. CoCalc Jupyter notebooks combine the interactive capabilities of Jupyter widgets with the usual advanced features of the CoCalc platform, including real-time collaboration, TimeTravel, and side chat.

A good way to get started using Jupyter widgets is to go through the Widget List in the main widgets documentation.

_images/cocalc-widgets-a.png

CoCalc Jupyter notebook with Jupyter Widgets

Classical versus CoCalc

If you are having trouble with the CoCalc Jupyter Notebook, you can switch to the Classical Jupyter Notebook. You can always switch back to CoCalc Jupyter easily later (and please let us know what is missing so we can add it!).

NOTE: The Classical Jupyter notebook is not supported in the Firefox browser. See Jupyter Server options below if you need to use Firefox and do not want to use the CoCalc Jupyter notebook.

You can change the default for opening a Jupyter notebook - CoCalc or Classical - by clicking the checkbox labeled “Jupyter classic …” in your Editor settings in Account Preferences.

To switch your notebook to Classical from within a CoCalc Jupyter notebook: select “File” → “Switch to Classical Notebook” in the menu.

_images/switch-to-classical.png

switching to Classical from CoCalc Jupyter notebook

To switch your notebook to CoCalc from within a Classical Jupyter notebook: select “File” → “Switch to Classical Notebook” in the menu.

_images/switch-to-cocalc.png

switching to CoCalc from Classical Jupyter notebook

The main reasons to use the classical notebook are:
  • need for certain extensions (Howto setup Jupyter Extensions).
  • interactive widget support Note: as of April, 2019, CoCalc Jupyter notebooks support ipywidgets.

See our list of Jupyter related issues for more details.

Don’t mix CoCalc and Classical!

Warning

Multiple people simultaneously editing the same notebook, with some using classical and some using the new mode, will NOT work! Switching back and forth will cause problems (you may need to use TimeTravel to recover). Please avoid using classical notebook mode if you possibly can!

Alternatives: Plain Jupyter Server and JupyterLab Server

You can also run the full classical Jupyter notebook server, using either Plain Jupyter Server or JupyterHub Server. These options are available under Project settings and (+) New.

Using either of these options for the classical notebook has an advantage: it does not affect your “Jupyter classic” Editor setting, allowing you to keep CoCalc Jupyter notebook as the default for opening .ipynb files in the CoCalc main interface.

Tips and Tricks

Use the Halt Button to Conserve Memory

Each running Jupyter Notebook spawns a session in your project. This uses up memory, which could cause troubles running all your processes in your project.

You can either restart the kernel to clean up its current memory (i.e. all variables are deleted), or if you’ve finished working on that notebook, click the Halt button to stop the kernel and close the notebook.

_images/jupyter-halt-button.png