Running how_to_ac3airborne locally

Running how_to_ac3airborne locally#

There are multiple options to run the Code examples from this book locally. In any case, it will involve the following steps:

install Python (we assume hat this is already done, have a look at python.org if you want to get it)
obtain the code from the book
install all required dependencies
run the code

You can decide between the quick an dirty method and the method using git, which will also set you up to contribute to the book.

Quick and dirty#

If you just like to run the code of a single notebook and don’t care to much about the details, the quickest option might be to download the chapter you are viewing as an ipython notebook (.ipynb) via the download button () on the top right of the page. If you don’t see the .ipynb option here, that’s because the source of the page can not be interpreted as a notebook and thus is not available for direct execution.

If you would just run the downloaded code, the chance is high that some required libraries are not yet installed on your system. You can either do try and error to find out which libraries are required for the chapter you downloaded, or you can simply installed all requirements for the entire book by running the following command on your command line:

Using pip

pip install jupyter
pip install -r https://raw.githubusercontent.com/igmk/how_to_ac3airborne/main/requirements.txt
pip install git+https://github.com/igmk/ac3airborne.git

This won’t work with any notebooks that use cartopy to make maps, pip does not manage their dependencies well.

Afterwards, you can start a local notebook server (either jupyter notebook or jupyter lab) and run and modify the chapter locally.

Note

Handling requirements in this project is not entirely straightforward, as the requirements strongly depend on which datasets are used. We use intake catalogs to describe how a dataset can be accessed which simplifies a lot of things. But as a consequence the set of required libraries is not only determined by the code in this repository, but also by the entries in the catalog.

Via git#

If you like to do it more properly, you can also clone the repository via git. Depending on if you have SSH public key authentication set up or not, you can do this via SSH or HTTPS:

SSH

git clone git@github.com:igmk/how_to_ac3airborne.git

HTTPS

git clone https://github.com/igmk/how_to_ac3airborne.git

This will create a local copy of the entire book repository in a newly created local folder how_to_ac3airborne. Please change into this directory.

Maybe use a virtual environment

If you use pip you might want to use a virtual environment for the book if you like to keep the required libraries in a confined place, but it is entirely optional and up to your preferences. There are many options to do so and virtualenv is one of them. Using virtualenv, you could create and activate an environment like:

virtualenv venv
. venv/bin/activate

and then continue normally.

You’ll have to install the dependencies as above, but as you already have all the files on your machine, you can also install it directly via:

Using pip

pip install jupyter
pip install -r requirements.txt

This won’t work with any notebooks that use cartopy to make maps, pip does not manage their dependencies well.

Depending on your needs, you can continue using interactive notebooks or compile the entire book.

About MyST notebooks

Internally, the book does not use the .ipynb file format as it is not well-suited for version control. Instead, we use Markedly Structured Text or MyST which is a variant of Markdown, optimized to contain executable code cells as in notebooks. The extension of MyST files is .md. In contrast to notebooks, these files do not contain generated cell outputs, so you’ll actually have to run the files in order to see anything.

jupytext is used to convert between MyST and ipynb formats. It is installed through the requirements.txt and should register itself with jupyter, so that you can open the files as if they where ipynb files. If that does not work, please have a look at the installation instructions of jupytext.

Interactive#

jupyter itself is not installed by the requirements file. If you’re using pip you might want to install it as well:

pip install jupyter

Once everything is set up, you can either start your notebook server:

either using classical notebooks

jupyter notebook

or using jupyter lab

jupyter lab

Compile the book#

You can also execute jupyter-book directly via:

jb build how_to_ac3airborne

which itself will run all code cells and output the results as HTML pages in a newly created folder. This variant is especially useful if you like to work directly on the MyST files (see note below) using a text editor and should be done every time before you submit new changes to the book.

Adding new articles#

Articles are generated from markdown files within the how_to_ac3airborne folder of the git repository. The following instructions assume that you are working in that directory.

Text articles#

Text articles can be created by adding standard markdown files using your favourite text editor.

Executable notebook#

If you want to add a new notebook, you can either start out from an existing MyST Markdown file by copying and modifying it, or you can create a new one from the jupyter notebook menu using File > New Text Notebook > MyST Markdown. If you already have an existing ipython notebook and want to convert it to MyST, you can do this by running

jupytext --to myst your_notebook.ipynb

This will create a new markdown file named your_notebook.md. After conversion, the ipynb file is not needed anymore and it should not be committed into the repository.

Entry in the table of contents#

After preparing your article or notebook, you’ll have to add it into the table of contents, such that it will actually show up in the compiled book. You can do this by modifying _toc.yml, where you can add the articles file name without suffix.