running How to EUREC4A 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
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:
pip install jupyter pip install -r https://raw.githubusercontent.com/eurec4a/how_to_eurec4a/master/requirements.txt
wget https://raw.githubusercontent.com/eurec4a/how_to_eurec4a/master/requirements.txt conda create -f requirements.txt conda activate how_to_eurec4a
Afterwards, you can start a local notebook server (either
jupyter notebook or
jupyter lab) and run and modify the chapter locally.
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.
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:
git clone email@example.com:eurec4a/how_to_eurec4a.git
git clone https://github.com/eurec4a/how_to_eurec4a
This will create a local copy of the entire book repository in a newly created local folder
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 the 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:
pip install jupyter pip install -r requirements.txt
conda create -f requirements.txt conda activate how_to_eurec4a
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
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
It is installed through the
requirements.txt and should register itself with
jupyter, so that you can open the files as if they where
If that does not work, please have a look at the installation instructions of
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
… or using jupyter lab
compile the book¶
You can also execute
jupyter-book directly via:
jb build how_to_eurec4a
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_eurec4a folder of the git repository.
The following instructions assume that you are working in that directory.
Text articles can be created by adding standard markdown files using your favourite text editor.
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
New Text Notebook >
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
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.
compile to PDF¶
If you’ve got a LaTeX environment available (e.g. TeXLive), you can also compile the book into a single PDF file. To do so, just run:
jb build how_to_eurec4a --builder pdflatex