Important

This software is Emerging and subject to ECMWF's guidelines on Software Maturity.

earthkit-hydro is a Python library for common hydrological functions.

Main Features

• Support for PCRaster, CaMa-Flood and HydroSHEDS river networks
• Computing statistics over catchments and subcatchments
• Finding catchments and subcatchments
• Calculation of upstream or downstream fields
• Handle arbitrary missing values
• Handle N-dimensional fields

Installation

Clone source code repository

git clone https://github.com/ecmwf/earthkit-hydro.git
cd earthkit-hydro

Create and activate conda environment

conda create -n hydro python=3.10
conda activate hydro

For default installation, run

pip install .

For a developer installation (includes linting and test libraries), run

pip install -e .[dev]
pre-commit install

Documentation

Earthkit-hydro can be imported as following:

import earthkit.hydro as ekh

The package contains different ways of constructing or loading a RiverNetwork object. A RiverNetwork object is a representation of a river network on a grid. It can be used to compute basic hydrological functions, such as propagating a scalar field along the river network or extract a catchment from the river network.

Mathematical Details

Given a discretisation of a domain i.e. a set of points $\mathcal{D}={ (x_i, y_i)}_{i=1}^N$, a river network is a directed acyclic graph $\mathcal{R}=(V,E)$ where the vertices $V \subseteq \mathcal{D}$. The out-degree of each vertex is at most 1 i.e. each point in the river network points to at most one downstream location.

For ease of notation, if an edge exists from $(x_i, y_i)$ to $(x_j, y_j)$, we write $i \rightarrow j$.

Readers

ekh.load_river_network(domain, version)

Loads a precomputed RiverNetwork. Current options are

domain	version	Details	Note
"efas"	"5"	1arcmin European	1
"glofas"	"4"	3arcmin global	2

ekh.create_river_network(path, river_network_format, source="file")

Creates a RiverNetwork. Current options are

• river_network_format: "esri_d8", "pcr_d8", "cama" or "precomputed"
• source: An earthkit-data compatable source. See list

Computing Metrics Over River Networks

Currently supported metrics are "sum", "mean", "max", "min" and "product". If weights is provided, it is used to weight the field in the calculation.

ekh.calculate_catchment_metric(river_network, field, stations, metric, weights=None)

Calculates the metric over each catchment defined by stations.

ekh.calculate_subcatchment_metric(river_network, field, stations, metric, weights=None)

Calculates the metric over each subcatchment defined by stations.

ekh.calculate_upstream_metric(river_network, field, metric, weights=None)

Calculates a metric over all upstream nodes for a river network.

ekh.calculate_metric_for_labels(field, labels, metric, weights=None)

(for advanced users) Calculates a metric over field for each label in the labels field.

ekh.flow_downstream(river_network, field)

(for advanced users) Calculates the total accumulated flux down a river network.
$$v_i^{\prime}=v_i+\sum_{j \rightarrow i}~v_j^{\prime}$$

Finding Catchments and Subcatchments

ekh.find_catchments(river_network, field)

Finds the catchments (all upstream nodes of specified nodes, with overwriting).
$$v_i^{\prime} = v_j^{\prime} ~ \text{if} ~ v_j^{\prime} \neq 0 ~ \text{else} ~ v_i, ~j ~ \text{s.t.} ~ i \rightarrow j$$

ekh.find_subcatchments(river_network, field)

Finds the subcatchments (all upstream nodes of specified nodes, without overwriting).
$$v_i^{\prime} = v_j^{\prime} ~ \text{if} ~ (v_j^{\prime} \neq 0 ~ \text{and} ~ v_j = 0) ~ \text{else} ~ v_i, ~j ~ \text{s.t.} ~ i \rightarrow j$$

Calculating Upstream or Downstream Fields

ekh.move_downstream(river_network, field)

Updates each node with the sum of its upstream nodes.
$$v_i^{\prime}=\sum_{j \rightarrow i}~v_j$$

ekh.move_upstream(river_network, field)

Updates each node with its downstream node.
$$v_i^{\prime} = v_j, ~j ~ \text{s.t.} ~ i \rightarrow j$$

Exporting or Masking a River Network

river_network.create_subnetwork(field)

Computes the river subnetwork defined by a field mask of the domain.

river_network.export(filename)

Exports the RiverNetwork as a joblib pickle.

Migrating from PCRaster

earthkit-hydro provides many functions with PCRaster equivalents, summarised below:

PCRaster	earthkit-hydro	Note
accuflux	calculate_upstream_metric	metric="sum"
catchmenttotal	calculate_upstream_metric	metric="sum"
areatotal	calculate_metric_for_labels	metric="sum", return_field=True
areaaverage	calculate_metric_for_labels	metric="mean", return_field=True
areamaximum	calculate_metric_for_labels	metric="max", return_field=True
areaminimum	calculate_metric_for_labels	metric="min", return_field=True
downstream	move_upstream
upstream	move_downstream
catchment	find_catchments
subcatchment	find_subcatchments
abs, sin, cos, tan, ...	np.abs, np.sin, np.cos, np.tan, ...	any numpy operations can be directly used

Points of difference

• earthkit-hydro treats missing values as np.nans i.e. any arithmetic involving a missing value will return a missing value. PCRaster does not always handle missing values exactly the same.
• earthkit-hydro can handle vector fields and fields of integers, floats, bools. PCRaster supports a restricted subset of this.

Attributions

¹ The EFAS river network is available under the conditions set out in the European Commission Reuse and Copyright Notice and is available at https://data.jrc.ec.europa.eu/dataset/f572c443-7466-4adf-87aa-c0847a169f23.

Margarita Choulga; Francesca Moschini; Cinzia Mazzetti; Grimaldi, Stefania; Disperati, Juliana; Beck, Hylke; Salamon, Peter; Prudhomme, Christel (2023): LISFLOOD static and parameter maps for Europe. European Commission, Joint Research Centre (JRC) [Dataset] PID: http://data.europa.eu/89h/f572c443-7466-4adf-87aa-c0847a169f23

² The GloFAS river network is available under the conditions set out in the European Commission Reuse and Copyright Notice and is available at https://data.jrc.ec.europa.eu/dataset/68050d73-9c06-499c-a441-dc5053cb0c86.

Margarita Choulga; Francesca Moschini; Cinzia Mazzetti; Disperati, Juliana; Grimaldi, Stefania; Beck, Hylke; Salamon, Peter; Prudhomme, Christel (2023): LISFLOOD static and parameter maps for GloFAS. European Commission, Joint Research Centre (JRC) [Dataset] PID: http://data.europa.eu/89h/68050d73-9c06-499c-a441-dc5053cb0c86