Installation

Anaconda Python Installation

For many reasons, we recommend using a Conda environment to work with the full RavenPy installation. This implementation is able to manage the harder-to-install GIS dependencies, like GDAL.

Begin by creating an environment:

$ conda create -c conda-forge --name ravenpy

The newly created environment must then be activated:

$ conda activate ravenpy

RavenPy can then be installed directly via its conda-forge package by running:

(ravenpy) $ conda install -c conda-forge ravenpy

This approach installs the Raven binary directly to your environment PATH, as well as installs all the necessary Python and C libraries supporting GIS functionalities.

Python Installation (pip)

Warning

In order to compile the Raven model (provided by the raven-hydro package, a C++ compiler (GCC, Clang, MSVC, etc.) and either GNU Make (Linux/macOS) or Ninja (Windows) must be exposed on the $PATH.

Warning

The Raven model also requires that NetCDF4 libraries are installed on the system, exposed on the $PATH, and discoverable using the FindNetCDF.cmake helper script bundled with raven-hydro.

On Linux, this can be provided by the libnetcdf-dev system library; On macOS by the netcdf homebrew package; And on Windows by using UNIDATA’s pre-built binaries.

In order to perform this from Ubuntu/Debian:

$ sudo apt-get install gcc libnetcdf-dev gdal proj geos

Then, from your python environment, run:

$ pip install ravenpy[gis]

If desired, the core functions of RavenPy can be installed without its GIS functionalities as well. This implementation of RavenPy is much lighter on dependencies and can be installed easily with pip, without the need for conda or virtualenv.

$ pip install ravenpy

Using A Custom Raven Model Binary

If you wish to install the Raven model, either compiling the Raven binary from sources for your system or installing the pre-built binary offered by UWaterloo, we encourage you to consult the Raven documentation (Raven Downloads).

Once downloaded/compiled, the binary can be pointed to manually (as an absolute path) by setting the environment variable RAVENPY_RAVEN_BINARY_PATH in the terminal/command prompt/shell used at runtime.

$ export RAVENPY_RAVEN_BINARY_PATH=/path/to/my/custom/raven

Customizing remote service datasets

A number of functions and tests within RavenPy are dependent on remote services (THREDDS, GeoServer) for providing climate datasets, hydrological boundaries, and other data. These services are provided by Ouranos through the PAVICS project and may be subject to change in the future.

If for some reason you wish to use alternate services, you can set the following environment variables to point to your own instances of THREDDS and GeoServer:

$ export RAVENPY_THREDDS_URL=https://my.domain.org/thredds
$ export RAVENPY_GEOSERVER_URL=https://my.domain.org/geoserver

Development Installation (from sources)

The sources for RavenPy can be obtained from the GitHub repo:

$ git clone git://github.com/CSHS-CWRA/ravenpy

You can then create and activate your Conda environment by doing:

$ cd /path/to/ravenpy
$ conda env create -f environment.yml
$ conda activate ravenpy

You can then install RavenPy with:

# for the python dependencies
(ravenpy) $ pip install --editable ".[dev,gis]"

Install the pre-commit hook (to make sure that any code you contribute is properly formatted):

(ravenpy-env) $ pre-commit install

If everything was properly installed the test suite should run successfully:

(ravenpy-env) $ pytest tests