Getting started with pyrealm

This page helps you to get started with using pyrealm from the ground up.

Prerequisites

Using the command line

The following instructions expect the user to use the command line, by which we mean, depending on the operating system, a terminal (Linux, macOS) or PowerShell/Cygwin Bash Shell or similar (Windows). Please see this Medium article and this Software Carpentries course if you need further instructions.

Installing prerequisites

Before installing pyrealm, make sure you have python installed. Here are the versions for

• Windows,

• Linux - there usually is a python version installed natively which should work,

• and macOS - you can also install python using Homebrew by typing brew install python3 into the terminal.

The pyrealm package can be easily installed using the python pip package. Mostly, your python version should come with pip readily available. If this is not the case, the pip documentation shows you how to install pip.

Installing pyrealm

When the above prerequisites are fulfilled, you can simply install pyrealm by typing the command pip install pyrealm into the command line. This will, at this point in time, install pyrealm version 1.0.0. If a different version is required, this can be specified in the command, e.g.: pip install pyrealm==2.0.0.

However, it is good practice to use a virtual environment for this, to not pollute your python environment with packages and versions you might not need for other work. Detailed information on how to do this can be found on the Python Packaging User Guide. In short, install virtualenv: pip install virtualenv, and then you can create a virtual environment typing python3 -m venv .venv (or py -m venv .venv on Windows) and activate it with source .venv/bin/activate (.venv\Scripts\activate on Windows). Then do pip install pyrealm and install everything else you might want to use. When you are done with your pyrealm work just type deactivate. You can re-activate and alter your environment anytime once it is set up.

Running the worked examples

The easiest way to get started with using pyrealm is going through the worked examples in this documentation. Each example can be run in a jupyter notebook. For this, it can be opened using a jupyter hub cloud service such as Google Colab or a locally hosted jupyter hub. It is also straightforward to install and run it locally on your machine following these steps:

• Install JupyterLab by running pip install jupyterlab.

• Start JupyterLab by running jupyter lab from the same directory where your jupyter notebooks are located.

• Open your jupyter notebook – have a look at the JupyterLab documentation for a detailed description of the user interface.

There are a number of Python packages which are necessary for running the examples, namely wget to download example data (note that this is different in the jupyter notebooks from the worked examples in the documentation, which access the data directly from the github repository without downloading it separately), matplotlib, for plotting, xarray as a data structure for handling the data and netCDF4 as file format in which the example data is stored.

The pyrealm package is also designed to work with multi-dimensional inputs to support efficient calculations - please review the overview of array inputs.

The following code block (run from the jupyter_notebooks directory of pyrealm) sets everything up for running the notebooks on Linux:

pip install virtualenv
python3 -m venv .venv
source .venv/bin/activate

# install the necessary packages
pip install pyrealm==2.0.0rc4
pip install jupyterlab
pip install wget matplotlib xarray netCDF4

jupyter lab

Good notebooks to get started with are

• the Standard P Model worked example

• the Subdaily P Model worked example

• the Splash Model worked example.

pyrealm developers

We welcome contributions to improving and extending the pyrealm package. The code for pyrealm can be found on Github. A guide how to develop for pyrealm can be found in the CONTRIBUTING.md file.