Examples: your entry point to wradlib#
The documentation of \(\omega radlib\) basically consists of two elements: the first element is the library reference which provides a systematic documentation of each function in wradlib’s API. In order to use the library reference properly, you should have an idea what you’re actually looking for. This is why new users mostly start with the second element, the wradlib-notebooks. Here you can look for application examples that are close to what you actually want to achieve, and then use these as a basis for further development. Once you understood an example, you also know what to look for in the library reference.
Interactive examples with jupyter notebooks#
All \(\omega radlib\) examples are distributed as jupyter notebooks in the wradlib-notebooks repository. This way, you can interactively explore various topics. Each notebook is organized in documented code blocks. You can browse through a notebook block by block, inspect the results, and experiment with the code. However, you can also view the rendered notebooks including the example results on the web pages of this section: Each page was directly generated from \(\omega radlib\)’s example notebooks. This way, you can copy&paste code snippets directly into your applications.
Are you using \(\omega radlib\) on the Open Radar Science Shortcourse? Then please follow-up there to get your openradar software stack running.
You might also fire-up a jupyter notebook server with a wradlib docker container.
Otherwise, you need to make sure to
Once these conditions are met, you can open a notebook: Launch a console or bash window in the directory that contains the example notebooks.
If you installed \(\omega radlib\) into a conda environment (as recommended in Installation),
you need to activate that environment first. Let’s say you named the environment
(base) $ conda activate wradlib
(wradlib) $ jupyter notebook
Did you forget the name of the environment that contains wradlib? This way, you get an overview over all environments:
(base) $ conda info --envs
which will give you something like (example output under Windows):
# conda environments:
In both cases, a browser window will open (typically at http://localhost:8888/tree) which will show the tree of the directory in which you started the jupyter notebook server. Just open any notebook by clicking. Code cells are executed by hitting
Shift + Enter or by using the toolbar icons. It’s pretty much self-explaining, and you’ll soon get the hang of it.
How can I get the example notebooks?#
The notebooks are available in the wradlib-notebooks repository. Alternatively, you can download the latest (“bleeding edge”) notebooks. In both cases, you find everything in the directory
/notebooks (after extracting the downloaded archives).
How can I get the example data?#
Most notebooks use example data. These data are provided in a separate repository and can be fetched using
pooch. All you need to do is install this via pip manually:
$ python -m pip install git+https://github.com/wradlib/wradlib-data@pooch
Now you need to set an environment variable pointing to a folder where the data should be saved when requested:
open a console and execute
setx WRADLIB_DATA <full path to wradlib-data>.
You need to set the env variable in your current shell profile. In most cases, this will be loaded from
~/.bashrc. Open that file in an editor (e.g. via
$EDITOR ~/.bashrc) and add the following line at the end of the file:
$ export WRADLIB_DATA=/insert/full/path/to/wradlib-data/
After this procedure, the example notebooks will automagically pull the required files from the data archive.
How to install jupyter?#
As already pointed out above, you can just look at the rendered notebooks online docs. In order to use them interactively, you need to install
jupyter can be installed conveniently into conda environments. If you installed \(\omega radlib\) in a separate conda environment (as recommended in Installation), you need to install
jupyter in that environment, too:
(base) $ conda activate wradlib
(wradlib) $ conda install jupyter
If you are not sure which conda environments you have, you can check via
conda info --envs.
If you did not install \(\omega radlib\) via conda, you should first check whether
jupyter might already be available on your system (use e.g.
jupyter --version). If
jupyter is not available, you should check out the jupyter docs for alternative installation options.
I prefer simple Python scripts instead of notebooks#
No problem. If you downloaded the notebooks directly from the wradlib repository, you can easily convert them to Python scripts yourself (but you need to install jupyter to do the conversion):
$ jupyter nbconvert --to script <name of the notebook>