1. Jupyter notebook and Markdown#

A notebook is an electronic document used for literate programming. In literate programming, text (usually in the form of Markdown), code, and code output (both textual and graphical) are combined in a single document which can often also be exported to html, pdf or Word format.

Jupyter (IPython) is a browser-based notebook with support for highlighted code, code execution and result embedding, text with markup (Markdown, MathJax Equations or HTML), inline plots and other media.

Notebooks such as Jupyter (or RMarkdown with R programming) make it possible to combine your analyses, the analysis outputs in both textual and graphic form, and thoughts and comments in one place. This makes your work both readable and reproducible, two very important aspects of data science.

1.1. Markdown#

Markdown is a lightweight markup language that you can use to add formatting elements to plain text documents. Created by John Gruber in 2004, Markdown is now one of the world’s most popular markup languages with many non-standard extensions and dialects.

Using Markdown is different than using a WYSIWYG (What You See Is What You Get) editor such as Microsoft Word. In such an application you click buttons to format words and phrases, and the changes are visible immediately.
Markdown isn’t like that. When you create a Markdown-formatted file, you add Markdown syntax to the text to indicate which words and phrases should look different.

See https://www.markdownguide.org for complete documentation.

An example illustrates best. To generate paragraph headers you use hash symbols like this:

### level three header
##### level five header

Which will be rendered in any application “speaking” markdown into something like this:

1.1.1. level three header#

1.1.1.1. level five header#

1.1.2. Inline markup elements#

Here are some more often-used inline markup elements:

If you want **bold text** you surround that part with double asterisks.  
If you want _some italic words_ you surround them with single underscores.  
You can combine this into **_bold and italic_** of course!  
This is some Python code: `print("hello, world")`

And these will render as shown below:

If you want bold text you surround that part with double asterisks.
If you want some italic words you surround them with single underscores.
You can combine this into bold and italic of course!
This is some Python code: print("hello, world")

Below are a few of the block-level markup elements:

> This is a blockquote. It can span multiple lines. 

* bullet list item one (or `+`, or `-`)
* bullet list item two
* bullet list item three

1. A numbered list item. Note it does not matter which number you use.
1. Another numbered list item
1. A last numbered list item

which, when processed, render into

This is a blockquote. It can span multiple lines.

  • bullet list item one (or +, or -)

  • bullet list item two

  • bullet list item three

  1. A numbered list item. Note it does not matter which number you use.

  2. Another numbered list item

  3. A last numbered list item

1.1.4. Markdown code blocks#

If you want to include code blocks for communication purposes only, not for execution, you can use this syntax:

```python  
total = 1  
fraction = 1  
i = 1  
for n in range(2, 6):  
    i = i + n  
    total = total + i  
    fraction = fraction / i  
    print(f'i is now {i}; the cumulative sum is {total} and the cumulative "fraction" is {fraction}')  
```

wich will render into this nice colorfull representation we call syntax highlighting.:

total = 1
fraction = 1
i = 1
for n in range(2, 6):
    i = i + n
    total = total + i
    fraction = fraction / i
    print(f'i is now {i}; the cumulative sum is {total} and the cumulative "fraction" is {fraction}')

1.1.5. Equations#

Most Markdown processors also support rendering of equations that are specified Latex-style. For instance, this syntax for the equation of the sample standard deviation

$$s = \sqrt{\frac{1}{N-1} \sum_{i=1}^N (x_i - \overline{x})^2}$$

renders as

\[s = \sqrt{\frac{1}{N-1} \sum_{i=1}^N (x_i - \overline{x})^2}\]

Use single dollar sign delimiters $<equation>$ for inline equations and double dollar sign delimiters $$<equation>$$ for paragraph equations.
See this pdf or this website for a nice cheat sheets.

1.2. Jupyter#

A notebook is an ordered series of cells that are either markdown, code or raw text.
You can move these cells up or down, and evaluate/execute them individually or all in one.

You toggle between two “states”: edit mode or command mode.

When in edit mode you can edit cells but not delete, change, create or move them. For that you need to be in command mode.
When in edit mode, use esc key to go to command mode.
When in command mode, use enter key to edit the current selected cell.

1.2.1. Keyboard shortcuts in edit mode#

Enter to enter “Edit mode”

Cmd+A       Select all
Cmd+C       Copy
Cmd+X       Cut
Cmd+V       Paste
Cmd+Enter   Run/render cell
Shft+Enter  Run+next
Alt+Enter   Run+insert
Shft+m      Merge

Cmd is Mac-specific; on Linux or Windows use Ctrl

1.2.2. Keyboard shortcuts in command mode#

Esc Enter Command mode

d+d   Delete cell
y     Change to code
m     Change to markdown
r     Change to raw (no rendering or evaluation)
b     New cell below
a     New cell above

1.2.3. IPython/Jupyter magic commands#

This is a special type of code in code cells; they are not Python code but executed by the Jupyter engine.

There are many -simply run %magic to see them all- these are especially nice to know of.

  • %magic: reference on all magic commands

  • %conda: run conda terminal command, %conda install [pkgs]

  • %load : loads code from a source file and replaces the %load magic, %load script.py

  • %run: run a script, %run script.py

  • %time, %timeit: report execution time of a statement

  • %who, %who_ls, %whos: display variables defined in interactive namespace with varying details/display styles.