Jupyter Notebooks¶

Literate Programming¶

Literate programming combines computer code with natural language to document and explain the code. This idea expands on the way we've used comments and pseudocode to organize and document our code directly in a .py file.

Use Cases¶

  • Data Science: Literate programming allows you to share code with descriptions and context to make interpretation and adaptation easier. Code outputs might include tables, summaries of analyses, and data visualizations.

  • Open / Reproducible / Replicable Science: Embed code in an article format allows others to examine and re-use specific code for reproduction or replication alongside traditional prose explanation.

  • Education: This workshop series was created with literate programming via Jupyter Notebooks.

  • Examples in Jupyter Notebooks

Jupyter Notebooks¶

The documentation for our series of Python workshops are an application of literate programming using a tool called Jupyter Notebooks.

Jupyter Notebooks save as .ipynb files (Jupyter Notebooks were previously called IPython Notebooks).

Jupyter Lab provides an interface for Jupyter that will eventually replace the classic Jupyter Notebook interface some of you may have encountered before. You can launch it by opening the Prompt/Terminal:

  • (PC) Start Menu > Miniforge3 > Miniforge Prompt
  • (Mac) Finder > Applications > Utilities > Terminal

And typing: jupyter lab. Note that the older interface is available by typing jupyter notebook instead.

Once Jupyter Lab opens in your browser, you can use the Launcher tab or File Menu>New>Notebook to create a Jupyter Notebook in a tab.

We'll work with Jupyter Lab for the remainder of the workshop!

Other Resources:¶

Binder¶

Binder is a free, non-profit, online service that hosts fully functional Jupyter Notebooks. You can view this workbook at: https://mybinder.org/v2/gh/UNC-Libraries-data/Python/main?filepath=Jupyter

In the interface, choose "Jupyter-Notebooks.ipynb" to open this workbook interactively.

Open OnDemand¶

Jupyter Lab is also available via Open OnDemand

Cells¶

Each Jupyter Notebook is made up of individual cells of different types:

  • Markdown for formatted text
  • Code for Python

Each type of cell needs to be "Run" to display formatted text or evaluate Python code.

Command and Edit Modes¶

Edit Mode¶

Double click or click and press enter on a cell to enter Edit Mode on a Markdown Cell. Click once for Python cells. This allows you to change the code or markdown within.

Command Mode¶

Click to the left of the cell, or hit Esc in a cell already in Edit mode to enter Command Mode. This allows you to add, copy and paste, or rearrange cells, or change the mode of a cell with keyboard shortcuts.

Adding and Deleting Cells¶

Click the + button at the top left to add cells (below) or use these shortcuts to insert cells from Command Mode:

  • a (insert cell above)
  • b (insert cell below)

Inside each cell, use the dropdown menu on the toolbar to choose between "Markdown" and "Code".

Right click a cell and choose "Delete cell" or press the D key twice in Command mode to remove a cell.

Markdown¶

Markdown is a convenient shorthand way to write HTML. A full introduction to the syntax is available here.

A few of the most important pieces of syntax are:

  • # ## ### ... represent ... level 1, 2, 3 headers respectively

  • *text* ... displays as ... text

  • **text** ... displays as ... text

  • `text` ... displays as ... text

  • [UNC home](http://unc.edu) ... displays as ... UNC home

  • ![Star Blur Photo](https://picsum.photos/id/1042/300/200) ... displays as ...

    • Image from Unsplash.com via Lorem Picsum Star Blur Photo

If necessary, you can also use html directly in your Markdown cells.

Bullets and Lists¶

Note: Be careful to include the space after each asterisk and indentation before subpoints.

Markdown

Displays As:
* Bullet 1 * Sub 1 * Bullet 2 + Sub 1
  • Bullet 1
    • Sub 1
  • Bullet 2
    • Sub 1
1. Item 1 2. Item 2
  1. Item 1
  2. Item 2

Exercise

  1. Create a markdown cell with a header, some plain text with at least one bold or italicized word, and a list (bulleted or numbered). If you're working in this document, you can use the cell below.

Exercise Cell

Code¶

Code cells follow normal Python Syntax, and when run produce outputs:

In [1]:
72*3
Out[1]:
216

Exercise

  1. Create a code cell, or use the cell below to call the print function on a string of your choice. Then run your code to produce an output.
In [2]:
#Excerise Cell

As usual, you'll want your notebook to contain all of the necessary statements importing packages and defining all variables used. Cells need to be run in order! Once run, each Python cell will be labeled like In [<number>] and each output will be labeled Out [<number>]. This helps you keep track of the order cells have been run in.

You can run cells individually as you develop a notebook, but once you're done it's good practice to use Kernel > Restart & Run All to reset your Python instance and make sure your code is actually self-contained.

Paths¶

Jupyter Notebooks automatically set your working directory to the folder where the .ipynb is saved. You'll have to save the document at least once to set your directory.

For example, the csv (comma separated values) file "CountyHealthData_2014-2015.csv" is stored in the same folder as this notebook, and it appears in oslistdir(".") without setting any working directory first.

In [3]:
import os
os.listdir(".")
Out[3]:
['.ipynb',
 '.ipynb_checkpoints',
 'CountyHealthData_2014-2015.csv',
 'Jupyter-Notebooks.html',
 'Jupyter-Notebooks.ipynb',
 'Other-Packages.ipynb',
 'Pandas.html',
 'Pandas.ipynb']

We'll return to this csv file when we introduce pandas, Python's leading data processing library.

Resources¶

Read more in the Official Docmentation:

  • Jupyter Notebooks
  • Jupyter Lab