Using HydroMT in Python

As HydroMT’s architecture is very modular, it is possible to use HydroMT in Python without using the command line interface (CLI). With Python, you actually have access to a lot of internal functionalities. This can be useful if you want to for example:

• build / update / clip models, check configurations or export data in Python instead of the CLI

• analyse model inputs or results

• analyse and compare input data without connecting to a specific model

• process input data for another reason than building a model

• create your own HydroMT plugin

So first, let’s go deeper into the API of HydroMT. You have all available functions and their documentation in the API reference.

HydroMT is here to read and harmonize input data, and to process it via its methods and workflows in order to prepare ready to run models. So HydroMT’s methods are organized around these main objects.

Input data

The main objects to work with input data are the DataCatalog and the DataAdapter classes of HydroMT. The DataCatalog is what is used to tell HydroMT where the data can be found and how it can be read, as well as what maintains the administration of exactly what data was used to maintain reproducibility. The DataAdapter are what does the actual reading of the data and get instructed and instantiated by the DataCatalog. Currently, five different types of input data are supported by the Adapters and represented by a specific Python data object:

• RasterDatasetAdapter : gridded datasets such as DEMs or gridded spatially distributed rainfall datasets (represented by RasterDataset objects, a raster-specific type of Xarray Datasets)

• DataFrameAdapter : tables that can be used to, for example, convert land classes to roughness values (represented by Pandas DataFrame objects)

• GeoDataFrameAdapter : vector datasets such as administrative units or river center lines (represented by Geopandas GeoDataFrame objects)

• GeoDatasetAdapter : time series with associated geo-locations such as observations of discharge (represented by GeoDataset objects, a geo-specific type of Xarray Datasets)

• DatasetAdapter : non-spatial N-dimension data (represented by Xarray Dataset objects).

So let’s say you would like to read data in HydroMT, you can do this by creating a DataCatalog instance and using the get_<data_type> methods to read the data. These are:

• get_rasterdataset

• get_dataframe

• get_geodataframe

• get_geodataset

• get_dataset

Here is a short example of how to read data in Python using HydroMT:

import hydromt
# create a data catalog from a local data_catalog file
cat = hydromt.DataCatalog("data_catalog.yml")
# read a raster dataset ("dem" source in the data catalog)
dem = cat.get_rasterdataset("dem")
# read a vector dataset ("catchments" source in the data catalog)
catchments = cat.get_geodataframe("catchments")
# read a geodataset with some time and space slicing
qobs = cat.get_geodataset(
  "qobs",
  time_tuple = ("2000-01-01", "2010-12-31"),
  bbox = [5.0, 50.0, 6.0, 51.0]
)

You can find more detailed examples on using the DataCatalog and DataAdapter in Python in:

• Reading raster data

• Reading vector data

• Reading geospatial point time-series data

• Preparing a data catalog

• Exporting data

Methods and workflows

Most of the heavy work in HydroMT is done by Methods and workflows. Methods provide the low-level functionality such as GIS rasterization, reprojection, or zonal statistics. Workflows combine several methods to transform input data to a model layer (e.g. interpolate nodata, then reproject). Examples of workflows include the delineation of hydrological basins (watersheds), conversion of landuse-landcover data to model parameter maps, and preparation of meteorological data.

The available methods in HydroMT are:

• raster: GIS methods to work with raster / regular grid data. For example, reprojecting, resampling, transform, interpolate nodata or zonal statistics etc.

• vector: GIS methods to work with geodataset data (N-dim point/line/polygon geometry). For example, reprojecting, transform, update geometry or convert to geopandas.GeoDataFrame to access further GIS methods.

• flw: Hydrological methods for raster DEM data. For example, calculate flow direction, flow accumulation, stream network, catchments, or reproject hydrography.

• gis_utils: other general GIS methods. For example to compute the area of a grid cell or to perform a merge of nearest geodataframe.

• stats: Statistical methods including skills to compute skill scores of models (e.g. NSE, KGE, bias and many more) and extremes to analyse extreme events (extract peaks or compute return values).

The available workflows in HydroMT are:

• grid: generic workflows to prepare regular gridded data. Used with the GridModel. For example to prepare regular grid data from constant, from RasterDataset (with or without reclassification) or from GeoDataFrame.

• mesh: generic workflows to prepare unstructured mesh data. Used with the MeshModel. For example to create a mesh grid or prepare unstructured mesh data from RasterDataset.

• basin_mask: workflows to prepare a basin mask based on different region definitions (bounding box, point coordinates, polygon etc.)

• rivers: workflows to prepare river profile data like width and depth.

• forcing: workflows to prepare meteorological forcing data. For example to prepare precipitation, temperature, or compute evapotranspiration data. Advanced downscaling methods are also available within these workflows.

You can find a couple of detailed examples of how to use HydroMT methods and workflows in Python:

• Working with raster data

• Working with flow direction data

• Define hydrological model regions

• Extreme Value Analysis

Models

As well as with the CLI, you can also build, update or clip models in Python. If you want to develop you own plugin you can find detailed information in the plugin development guide.

But you can also use HydroMT and its Model class to do some analysis on your model inputs or results. HydroMT views a model as a combination of different components to represent the different type of inputs of a model, like config for the model run configuration file, forcing for the dynamic forcing data of the model etc. For each component, there are methods to set_<component> (update or add a new data layer), read_<component> and write_<component>. In the model API you can find all available components.

Here is a small example of how to use the Model class in python to plot or analyse your model:

import hydromt
# create a GridModel instance for an existing grid model saved in "grid_model" folder
model = hydromt.GridModel(root="grid_model", mode="r")
# read/get the grid data
forcing = model.grid
# plot the DEM
grid["dem"].plot()

# read the model results
results = model.results
# Get the simulated discharge
qsim = results["qsim"]
# Read observations using a local data catalog
cat = hydromt.DataCatalog("data_catalog.yml")
qobs = cat.get_geodataset("qobs")
# Compute some skill scores like NSE
nse = hydromt.stats.nashsutcliffe(qobs, qsim)

You can find more detailed examples on using the Model class in Python in:

• Working with (grid) models in python

• Working with mesh models

And feel free to visit some of the plugins documentation to find even more examples!