Jupyter Notebooks

# Jupyter Notebooks

Database Design

---

# Agenda

1. [Overview](#overview)
1. [Setup](#setup)
1. [Cells](#cells)
1. [Code](#code)
1. [IPython.display](#ipython-display)
1. [Tooltips](#tooltips)
1. [Shortcut Cheat Sheet](#cheat-sheet)
1. [Conclusions](#conclusions)

---

# Overview

## Concept

[Project Jupyter](https://jupyter.org/) is a web-based publishing system that can incorporate Python and many other language interpreters into a web pages.

It is extremely handy for sharing code and including documentation and notes for better reproducibility, collaboration, and education.

---

## Key Features

Features of most interest to users:

- write documentation and notes in Markdown syntax

- write and execute code on the web

- supports a few popular data science languages, including Python and R

- import/export Jupyter Notebooks as `JSON`.

- bundled with the [Anaconda](https://www.anaconda.com/) data science toolkit

---

# Setup

## Install

**JupyterLab** - an application that allows you to edit and write Jupyter Notebooks - may be installed on your own computer via the command line, using either of the popular Python package managers, `pip` or `conda`.

```bash
pip install jupyterlab # try 'pip3' instead of 'pip' if your system requires it
```

---

## Run

Run from the command line:

```bash
jupyter-lab
```

- this will pop open an interface in your computer's default web browser

- click to create a new `Python 3` Notebook

---

## Anaconda Navigator

JupyterLab can alternatively be launched from Anaconda Navigator, which contains a bundle of common data science tools.

![JupyterLab in Anaconda Navigator](../assets/jupyter/anaconda_navigator.png)

---

## Visual Studio Code

As an alternative to JupyterLab, Visual Studio Code includes Jupyter Notebook integration. Simply open up any file with the `.ipynb` extension, and you will be able to start working in the notebook.

- Here is [an example `.ipynb` file](https://github.com/nyu-database-design/pandas-examples/blob/master/welcome.ipynb) - save it to your computer, pop it open in Visual Studio code, and try for yourself.

---

## GitHub

While GitHub does not include an execution environment for Jupyter Notebooks, it does allow visitors to view the notebooks. While the output of the notebook will be displayed, it is not possible to modify or re-run the code.

- See [this example notebook](https://github.com/nyu-database-design/pandas-examples/blob/master/welcome.ipynb).

---

## Binder

The Jupyter project includes a notebook execution environment called [Binder](https://mybinder.org/). Binder allows users to edit and execute notebooks, and includes the ability to load and edit any notebook hosted in a public GitHub repository. Changes made to the notebook are not saved to GitHub, but can be saved locally.

- See [an example notebook](https://mybinder.org/v2/gh/nyu-database-design/pandas-examples/blob/master/welcome.ipynb/HEAD).

---

## More

Given its popularity within the data science, scientific research, and Python communities, there are even more execution environment options for Jupyter notebooks, including:

- Google [Colaboratory](https://colab.research.google.com/)
- Microsoft [Azure Notebooks](https://notebooks.azure.com/)
- [CoCalc](https://cocalc.com/)
- JetBrains [Datalore](https://datalore.io)

---

# Cells

## Concept

Notebooks are a collection of individual **cells** that can be edited and executed. There are two types of cells:

- **Markdown** - text written in standard Markdown syntax.

- **Code** - programming code written in whichever language the Notebook has been set up to support. This is the default cell type.

---

## Activating cells

Any cell that has previously been placed in the notebook may be activated by double-clicking on it.

---

## Switching between cell types

Cells are by default Code cells. Use shortcuts to switch the type of a cell:

- `Esc`-`m` - switch the active cell to Markdown type

- `Esc`-`y` - switch the active cell to Code type

---

## Inserting new cells

There are two useful shortcuts for creating new cells:

- `Esc`-`a` - insert a new cell above the currently active cell.

- `Esc`-`b` - insert a new cell below the currently active cell.

---

## Deleting cells

To delete the currently-active cell, use the `Esc`-`x` shortcut.

---

## Executing cells

To execute the contents of a cell, press one either `Shift`-`Enter` to execute and move to the next cell below, or `Control`-`Enter` to execute but keep the current cell selected.

- **Markdown cells** will have their contents rendered as [HTML](/content/courses/web-design/slides/html) web content.

- **Code cells** will have their contents executed and any output displayed.

---

# Code

## Concept

A few notes about writing code in Jupyter Notebooks...

---

## Output expressions as the last line of code in a cell

If the last statement in a cell is an expression of some kind, the value of that expression will be output in the notebookwithout the need for `print()`.

For example:

```python
# function definition that returns a value
def return_something():
    return 'This will be output without print!'

# calling it as the last line in the cell will output the return value
return_something()
```

Outputs the following: `'This will be output without print!'`

---

## Output expressions as the last line of code in a cell (continued)

The code:

```python
# a simple variable assignment
x = 10

# referencing it as the last line in the cell will output the value
x
```

Outputs the following: `10`

---

## Output expressions as the last line of code in a cell (continued again)

The code:

```python
# a boolean expression
(True and False) and (not True)
```

Outputs the following: `False`

While the code:

```python
# a literal
4
```

Outputs the following: `4`

---

## Output values in the middle of a cell using print()

Should you need to output values in the middle of a cell, you may use `print()`.

For example:

```python
for i in range(5):
    print(i)
print("Done")
```

Outputs the following:

```
0
1
2
3
4
Done
```

---

# IPython.display

## The problem with print()

While `print()` works well for simple primitive values, it is really better used on the command line, not in a notebook.

- `print()` is _not designed for an interactive programming environment_ and does not visually display well more complex data structures types like large lists, dictionaries, or other media types such as images or video.

- To do so in a notebook, import and use functions in the `IPython.display` module.

---

## Outputting more complex data structures

For example:

```python
from IPython.display import display, Image, Markdown

my_list = [ {"foo", "bar"}, {"baz": "bum"} , {"biddle": "diddle"} , {"dum": "fum"} , {"gram": "pram"} ]
display( my_list )
```

Outputs the following:

```
[{'bar', 'foo'},
 {'baz': 'bum'},
 {'biddle': 'diddle'},
 {'dum': 'fum'},
 {'gram': 'pram'}]
```

---

## Rendering markdown code

It is possible to programmatically render Markdown code in a notebook. For example:

```python
# some Markdown code, stored in a variable
my_markdown = '''
A simple Markdown list:
- first item
- second item, with some **bold text**
- third item, with a [link](https://knowledge.kitchen)
'''

# render the markdown
Markdown(my_markdown)

```

Outputs the following:

A simple Markdown list:

- first item
- second item, with ome **bold text**
- third item, with a [link](https://knowledge.kitchen)

---

## Rendering images

It is also possible to render an image into a notebook. For example, the following code...

```python
from IPython.display import display, Image, Markdown

Image("https://knowledge.kitchen/content/courses/database-design/slides/assets/jupyter/donkey.png")
```

... will render the image from the referenced URL or file path:

![Donkey](../assets/jupyter/donkey.png)

---

# Tooltips

## Autocomplete

While writing code, trigger an autocomplete suggestion box to appear at any time by typing the `Tab` key.

- the autocompletion may take a second or two to appear.

- if nothing appears after a few seconds, Jupyter probably has no autocompletions to suggest.

---

## Function documentation

To view the documentation of any function, place the cursor between the opening and closing parentheses of the function in your code, and press the shortcut, `Shift`-`Tab`.

---

# Shortcut Cheat Sheet

## Recap

Here are the keyboard shortcuts we have covered:

- `Esc`-`m` - switch the active cell to Markdown type
- `Esc`-`y` - switch the active cell to Code type
- `Esc`-`a` - insert a new cell above the currently active cell.
- `Esc`-`b` - insert a new cell below the currently active cell.
- `Esc`-`x` - delete the currently-active cell
- `Shift`-`Enter` - execute and move to the next cell below
- `Tab` - trigger an autocomplete suggestion box to appear
- `Shift`-`Tab` - view the documentation of any function

---

# Conclusions

Thank you. Bye.