Your First Notebook

Make a notebook, put it on a kernel, run something, write down what it was for, and save it. It assumes only that Zasper is installed and open on a folder you can write to.

Make The Notebook

The file explorer is the first icon in the rail on the left, and the strip under its title names the folder Zasper was started in. The three buttons at the right-hand end of that strip make a file, a folder and a notebook. Press the notebook one.

The notebook arrives as Untitled.ipynb with its name already selected in the tree. Type a name over it, keep the .ipynb on the end, and press Enter; Escape keeps the name it came with. To put it somewhere other than the top of the project, right-click a folder in the tree and choose Add Notebook instead.

1 2

1New notebook, the third of the three buttons on the project strip.
2The new file, waiting for a name. Escape keeps the one it has.

Pick A Kernel

A notebook made this way does not name a kernel yet, so the first thing it asks is which one to run on. The list is every kernel installed on this machine — whatever jupyter kernelspec list prints. If the environment you meant is not in it, install ipykernel into that environment and open the notebook again. Installing Jupyter Kernels and Working with Conda cover how they are found.

Once the kernel has started, its name and a status dot sit at the right-hand end of the notebook’s toolbar: the dot is grey while the kernel is idle and lit while it is working. Click the name to move the notebook to a different kernel later.

1 2 3

Python 3 (ipykernel)

1Run the cell you are in and move to the next one.
2What kind of cell this is: code, prose, or raw text left alone.
3The kernel, and whether it is busy. Click it to switch.

Run A Cell

Click into the empty cell and type. Two chords run it, and the difference is where you end up:

Action	macOS	Windows / Linux
Run Cell and Select Next	`⇧⏎`	`Shift+Enter`
Run Cell	`⌃⏎`	`Ctrl+Enter`

On the last cell of the notebook, ⇧⏎ adds a new one to carry on in.

The number in the left margin is the cell’s turn with the kernel. [ ] has never run, [*] is queued or running now, and [7] was the seventh thing this kernel was asked to do — not the seventh cell in the file. Restart the kernel and the count starts again from one.

1 2

[1]

import pandas as pd
readings = pd.read_csv("data/measurements.csv")
print(f"{len(readings)} rows")

20160 rows

[*]

drift = readings.resample("1min", on="t").mean().diff()

1The first thing this kernel ran.
2Sent, and waiting its turn — the kernel runs one cell at a time.

Read What Comes Back

Anything the cell printed, returned or drew appears under it, in the order it happened: a line of text, a table, a figure. A cell that ends in an expression shows that expression’s value, which is why readings.head() on a line of its own is enough. Notebook Support lists what Zasper renders and what it does not.

An error arrives in the same place rather than in a dialog. The kernel keeps everything it had — the variables from the cells that worked are still there — so the usual fix is to correct the line and run it again.

[2]

readings.head(2)

	sensor	drift
0	a-14	0.000418
1	a-15	0.000512

[3]

readings.loc["b-03"]

KeyError: 'b-03'

Traceback (most recent call last):
  File "<ipython-input-3>", line 1, in <module>
    readings.loc["b-03"]
  File "pandas/core/indexing.py", line 1073
    return self._getitem_axis(key, axis=axis)

A table and a traceback, both in the box under the cell that made them.

Output that runs to hundreds of lines is capped at a height you can scroll inside. Expand or Collapse Output, Clear Cell Output and Clear All Outputs have no key binding; run them from the command palette (⇧⌘P / Ctrl+Shift+P), or from the toolbar over a cell.

A cell that will not finish is stopped with Interrupt, the square in the notebook toolbar. There is no binding for that either: interrupting is not something you do in the middle of typing. Restart beside it throws away the variables and starts the kernel again, which is the answer when interrupting does not take.

Say What It Was For

A notebook that is only code is a script with gaps in it. Change a cell to Markdown — the picker in the toolbar, or ⌃⇧M / Ctrl+Shift+M — write in it, and run it with ⇧⏎ to render it. ⌃⇧Y / Ctrl+Shift+Y turns a cell back into code, and double-clicking rendered prose opens its source again.

## Sensor drift

Fourteen days from the bench rig, resampled to one minute.

Sensor drift

Fourteen days from the bench rig, resampled to one minute.

The same cell being written, and after it has been run.

Headings written this way are what Table of Contents lists in the column beside the cells, so a notebook with a few ## lines in it becomes something you can jump around in rather than scroll.

Save It

⌘S, or Ctrl+S, or the first button in the toolbar. Until you do, a dot sits beside the name in the tab.

ipy drift.ipynb

README.md

1Edits this notebook has that the file on disk does not.

What gets written is the cells, the output they produced, and the name of the kernel they ran on. That last part is why opening the notebook tomorrow does not ask the question in step two again: it already knows the answer, and only asks when the kernel it names is not installed here.

Tabs, including this one, are remembered between sessions — Files and Tabs covers what reopens and what does not. Every chord Zasper listens for, including the ones this page skipped, is on Key Bindings, and the Help tab (F1) lists them inside the app with a filter.