earthkit.hydro.river_network

Module contents

earthkit.hydro.river_network.available(data_source='https://sites.ecmwf.int/repository/earthkit-hydro/available.txt')

Prints the available precomputed networks.

Parameters:

data_source (str, optional) – Base URI to read available networks from.

earthkit.hydro.river_network.create(path, river_network_format, source='file', use_cache=True, cache_dir=None, cache_fname='{ekh_version}_{hash}.joblib', cache_compression=1)

Creates a river network from the given path, format, and source.

Parameters:

• path (str) – The path to the river network data. All common file formats are supported such as netCDF, GRIB, GeoTIFF, zarr, etc.

• river_network_format (str) – The format of the river network data. Supported formats are “precomputed”, “cama”, “pcr_d8”, “esri_d8”, “grit” and “merit_d8”.

• source (str) – The source of the river network data. Default is ‘file’. For possible sources see: https://earthkit-data.readthedocs.io/en/latest/guide/sources.html.

• use_cache (bool, optional) – Whether to cache the loaded/created river network for quicker reloading. Default is True.

• cache_dir (str, optional) – Where to store the cached river networks. Default is None, which uses tempfile.mkdtemp(suffix=”_earthkit_hydro”).

• cache_fname (str, optional) – A string template for the cache filename convention.

• cache_compression (int, optional) – A compression factor for the cached files.

Returns:

The river network object created from the given data.

Return type:

RiverNetwork

earthkit.hydro.river_network.export(river_network: RiverNetworkStorage | RiverNetwork, path: str, river_network_format: str = 'precomputed', compression=1)

Export a river network to a local file.

Note

Exporting to precomputed format is highly recommended for efficiency reasons. Other river network formats should only be used if compatibility is required with other tooling.

Note

For formats other than precomputed, only exporting as netcdf is currently supported.

Warning

The cama format has two different sink representations, one for inland sinks (-10), and one for coastal sinks (-9). There is only one sink representation in earthkit-hydro, so for cama format exports all sinks are exported as coastal sinks (-9). This does not change any results with earthkit-hydro, but be aware when using other tools.

Parameters:

• river_network (RiverNetworkStorage | RiverNetwork) – The river network to export.

• path (str) – Where to export the river network.

• river_network_format (str) – The format of the river network data. Currently supported formats are “pcr_d8”, “esri_d8” and “merit_d8”.

• compression (int) – The compression factor to use for the saved file. Only applied if river_network_format is precomputed.

Return type:

None. Writes the river network to a local file at path.

earthkit.hydro.river_network.load(domain, river_network_version, data_source='https://sites.ecmwf.int/repository/earthkit-hydro/{ekh_version}/{domain}/{river_network_version}/river_network.joblib', *args, **kwargs)

Load a precomputed river network from a named domain and river_network_version.

Supported networks are as follows:

domain	version	Details	Note	Attribution
“efas”	“5”	1arcmin European		[1]
“efas”	“4”	5km European	Smaller domain than v5	[1]
“glofas”	“4”	3arcmin global	60° South to 90° North	[2]
“glofas”	“3”	6arcmin global	60° South to 90° North	[2]
“cama_01min”	“4”	1arcmin global		[3]
“cama_03min”	“4”	3arcmin global		[3]
“cama_05min”	“4”	5arcmin global		[3]
“cama_06min”	“4”	6arcmin global		[3]
“cama_15min”	“4”	15arcmin global		[3]
“hydrosheds_30sec”	“1”	30arcsec global	56° South to 84° North	[4]
“hydrosheds_05min”	“1”	5arcmin global	56° South to 84° North	[4]
“hydrosheds_06min”	“1”	6arcmin global	56° South to 84° North	[4]
“grit”	“1”	30m global (vector)	segments network	[5]

Parameters:

• domain (str) – The domain of the river network.

• river_network_version (str) – The version of the river network on the specified domain.

• data_source (str, optional) – The data source URL template for the river network.

• *args (tuple) – Additional positional arguments to pass to create_river_network.

• **kwargs (dict) – Additional keyword arguments to pass to create_river_network.

Returns:

The loaded river network.

Return type:

RiverNetwork

References

[1] (1,2)

Choulga, Margarita; Moschini, Francesca; Mazzetti, Cinzia; 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

[2] (1,2)

Choulga, Margarita; Moschini, Francesca; Mazzetti, Cinzia; 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

[3] (1,2,3,4,5)

Yamazaki, Dai; Ikeshima, Daiki; Sosa, Jeison; Bates, Paul D.; Allen, George H.; Pavelsky, Tamlin M. (2019): MERIT Hydro: A high-resolution global hydrography map based on latest topography datasets. Water Resources Research, vol.55, pp.5053-5073, 2019, DOI: 10.1029/2019WR024873

[4] (1,2,3)

Lehner, Bernhard; Verdin, Kristine; Jarvis, Andy (2008): New global hydrography derived from spaceborne elevation data. Eos, Transactions, 89(10): 93-94. Data available at https://www.hydrosheds.org.

[5]

Wortmann, Michel; Slater, Louise; Hawker, Laurence; Liu, Yinxue; Neal, Jeffrey; Zhang, Boen; Schwenk, Jon; Allen, George H.; Ashworth, Philip; Boothroyd, Richard; Cloke, Hannah; Delorme, Pauline; Gebrechorkos, Solomon H.; Griffith, Helen; Leyland, Julian; McLelland, Stuart; Nicholas, Andrew P.; Sambrook-Smith, Gregory; Vahidi, Elham; Parsons, Daniel; Darby, Stephen E. (2025). Global River Topology (GRIT): A bifurcating river hydrography. Water Resources Research, 61(5), DOI: 10.1029/2024WR038308

earthkit.hydro.river_network.repair(input_path, output_path, river_network_format, input_source='file')

Given an initial river network, repairs the river network and writes the output to local file.

Warning

This function should only be used by advanced users. It should not be used without an understanding of why the initial river network needs repair.

The repairing algorithm is as follows:

1. Any invalid values are made missing

2. Any cycles are made missing

3. For offset/relative drainage directions river networks formats (“pcr_d8”, “esri_d8” and “merit_d8”), cells flowing outside the domain are set to sinks

4. Any missing values with a cell flowing into them are made into sinks

Parameters:

• input_path (str) – The path to the initial river network data. All common file formats are supported such as netCDF, GRIB, GeoTIFF, zarr, etc.

• output_path (str) – Where to export the repaired river network data. Currently only netcdf file format exports are supported.

• river_network_format (str) – The format of the river network data. Currently supported formats are “cama”, “pcr_d8”, “esri_d8” and “merit_d8”.

• input_source (str) – The source of the initial river network data. Default is ‘file’. For possible sources see: https://earthkit-data.readthedocs.io/en/latest/guide/sources.html.

Return type:

None. Writes a repaired river network to a local file at output_path, in the same format as the original.