Getting Started with Jupyter Notebooks¶

What is a Notebook?¶

A notebook is a single document where you can run code, display and visualize its output, add explanations enriched with images, charts, and equations, making your code more transparent, interpretable, reproducible, and shareable.

What is Jupyter Notebook?¶

The Jupyter Notebook is a powerful tool to interactively prototype and present ideas and workflows.

The Jupyter Notebook is an open source web application that enables you to create documents that contain runnable code, text, equations, and visualizations.

Jupyter supports IPython kernel to allow you to write/prototype programs in Python. You can also use other kernels (e.g., R and Julia .. etc) with Jupyter notebooks.

The Jupyter Notebook combines three components:

Notebook web app: An interactive web application to edit code in the browser, run code from the browser, see the results of running the code in the browser, create and use interactive widgets, and author narrative text and equations.
Kernels: Processes launched by the notebook web app that runs code in a specific language and handles interactive widgets and tab completion. The default kernel runs Python code.
Notebook documents: Documents that contain visible content in the notebook web app, including inputs and outputs of an interactive session, narrative text, equations, and images, and rich media representations of objects. Each notebook document has its own kernel. Notebook documents are files with a .ipynb extension Internally, notebook documents are json data with binary output encoded.

ShapeWorks installs Jupyter for you¶

The Jupyter Notebook is not included with Python. The conda_installs script the comes with ShapeWorks (conda_installs.sh for Mac OS and Linux and conda_installs.bat for Window) installs Jupyter Notebook for you.

ShapeWorks also installs and enables for you

a spell checker extension for the text cells
a table of content extension to easily navigate notebooks

Starting the Jupyter Notebook server¶

Now that you have run conda_installs - only needed once by running:

source conda_installs.sh

To get the server started, all you need to do is

open up your terminal
go to the folder where you would like to save your notebooks in
activate shapeworks environment by running conda activate shapeworks
launch the notebook server by running jupyter notebook

Note: Notebooks for demonstrating ShapeWorks tools are located in Examples/Python/notebooks/tutorials. We recommend that you create a folder in Examples/Python/notebooks/ directory for your own notebooks.

This will launch the Jupyter server. Your default browser will then start or open a new tab to this local URL: http://localhost:8888/tree

Your browser should now look something like this:

Creating a notebook¶

So far, you have started a notebook server and create the folder where you will save your notebooks. Let's now create an actual Notebook document.

This is in fact a click away, all you need to do is click on the new button in the upper right and choose the type of file (notebook) you want to create.

The word Untitled beside the Jupyter logo is the name of your notebooks. You can move your mouse over the word Untitled and click on the text to rename your notebook to a more descriptive name that reflects the purpose of your notebook.

Running notebook cells¶

A Jupyter notebook can have both text (written in markdown) and code cells. When you create a new cell, it defaults to be a code cell running the kernel you chose for your notebook.

Below is a simple Python code that prints Hello ShapeWorks!. Running a cell means that you will execute the chunk of code in that cell. To run a cell, you can do either of the below:

click Cell from the Jupyter menu then click Run Cells
click the cell and hit the Run button in the bar below the Jupyter menu
press Shift + Enter if you prefer keyboard shortcuts

Having multiple cells¶

Typically, we divide our code and text into logical chunks, each in a cell, for readability. Cells can be run in order and share variables and libraries imports. You can also run cells in non-sequential order, especially when you are prototyping your notebook.

If a code cell is not yet executed, you will find an empty square braces In [ ] to the left of the cell. Once it is executed, this will auto fill with a number that indicates the order that you ran the cells.

Jupyter notebook supports Markdown, a simple markup language that enables simple formatting for section headers, code samples, weblinks, and images, yet is still readable as plain text.

To create a text cell, create a new cell and set its type to Markdown using the drop-down menu in the top icon bar. Start writing your text with markdown styling, for example:

User _underscore_ for italics and **double asterisks** for bold.

Then run the cell (e.g. press Shift + Enter).

Notebook keyboard shortcuts¶

Esc + H: displays a complete list of keyboard shortcuts
Esc + A: insert new cell above the current cell
Esc + B: insert new cell below the current cell
Esc + D + D: delete current cell
Esc + Z: undo
Shift + enter: run current cell and move to next
To show a function's argument list (i.e., signature), use ( then shift-tab
Use shift-tab-tab to show more help for a function
To show the help of a function, use help(function) or function?
To show all functions supported by an object, use dot-tab after the variable name