Python notebooks
A notebook puts Python cells on a page. Readers run them, change them and run them again, in the browser, with nothing to install: Pyodide runs Python in WebAssembly. Until then the cells are part of the page, written in when it's built, so they're read, searched and checked like the rest of it.
This one reads the track of a saildrone, the one that Mapping a mission draws, from the site's public files. Press Run all, or the button of a cell. The first run loads Python, pandas and matplotlib, about 30 MB, which the browser keeps for the next time.
What runs before the cells
Puts sd1030.geojson in the working directory.
The track is a GeoJSON file: a line for each leg, with the time it started and the temperature of the sea.
import json
import pandas as pd
with open('sd1030.geojson') as file:
features = json.load(file)['features']
legs = pd.DataFrame([feature['properties'] for feature in features if feature['geometry']['type'] == 'LineString'])
legs['time'] = pd.to_datetime(legs['time'])
legs.head()The coolest and the warmest water of each month:
legs.set_index('time')['temperature'].resample('MS').agg(['min', 'mean', 'max']).round(2)And the whole mission:
import matplotlib.pyplot as plt
figure, axes = plt.subplots(figsize=(8, 3))
axes.plot(legs['time'], legs['temperature'], color='#2e7a48')
axes.set_title('Sea temperature along the track')
axes.set_ylabel('°C')
plt.show()Writing a notebook
A notebook is a ::: notebook container. Each python code block in it is a cell, and the text between them stays text, between the cells:
::: notebook
```yaml
title: A first look
packages: [pandas]
files:
data/track.csv: { url: /data/track.csv }
```
Read the track:
```python
import pandas as pd
pd.read_csv('data/track.csv').head()
```
:::The settings go in a YAML block at the start, and all of them are optional:
titlenames the notebook.packagesare installed before the first cell: packages that Pyodide has, pure Python packages from PyPI, or URLs of wheels, such as one in your public files.{ name: geopandas, deps: false }installs a package without the ones it depends on. The packages that the cells import, and Pyodide has, are installed anyway.filesputs files in the working directory, as in a Node.js playground:{ url }for a file of the site,{ content }for text written here, or the URL of a folder of your public files for all of it.setupis Python that runs before the first cell, such as the settings or the patches a package needs in a browser. It's shown above the cells, folded.srctakes the cells from a Jupyter notebook in your public files, with the outputs it was saved with:src: /notebooks/first-look.ipynb. The text of the container then goes above it.
What readers can do
They run a cell with its button, or all of them with Run all, and edit the code in the same editor as the playground's, with completions from what the cells have made so far. Shift+Enter runs a cell and goes to the next one, Ctrl+Enter (⌘Enter on a Mac) runs it, and Alt+Enter runs it and adds a cell below. Stop interrupts a long cell, Restart starts Python again, and the download button saves the notebook as an .ipynb file, with what the cells showed, to carry on in Jupyter.
A cell shows what it prints, the value of its last line, and its figures. pandas tables come as tables, and matplotlib figures as pictures, with a text alternative made of their titles and the labels of their axes.
What runs in a browser
Pyodide has NumPy, pandas, pyarrow, matplotlib, xarray, netCDF4, SciPy, scikit-learn, GeoPandas and some 350 other packages, and installs pure Python packages from PyPI. What a browser doesn't have, Python doesn't either: there are no threads, no subprocesses and no raw sockets, and files that cells write are gone when the page is closed. Data can come from your public files, or from any server that allows it with CORS.
A notebook needs no special headers from the server, unlike a playground. With the two that isolate a page, Stop interrupts the running cell; without them, it starts Python again.