API reference

Data

Data catalog

General

data_catalog.DataCatalog(data_libs, str] = [])	Catalog of DataAdapter sources to easily read from different files and keep track of files which have been accessed.
data_catalog.DataCatalog.sources	Returns dictionary of DataAdapter sources.
data_catalog.DataCatalog.keys	Returns list of data source names.
data_catalog.DataCatalog.predefined_catalogs
data_catalog.DataCatalog.to_dict([...])	Export the data catalog to a dictionary.
data_catalog.DataCatalog.to_dataframe([...])	Return data catalog summary as DataFrame
data_catalog.DataCatalog.to_yml(path[, ...])	Write data catalog to yaml format.
data_catalog.DataCatalog.export_data(data_root)	Export a data slice of each dataset and a data_catalog.yml file to disk.

Add data sources

data_catalog.DataCatalog.set_predefined_catalogs([...])
data_catalog.DataCatalog.from_predefined_catalogs(name)
data_catalog.DataCatalog.from_archive(urlpath)	Read a data archive including a data_catalog.yml file
data_catalog.DataCatalog.from_yml(urlpath[, ...])	Add data sources based on yaml file.
data_catalog.DataCatalog.from_dict(data_dict)	Add data sources based on dictionary.
data_catalog.DataCatalog.update(**kwargs)	Add data sources to library.

Get data

data_catalog.DataCatalog.get_rasterdataset(...)	Returns a clipped, sliced and unified RasterDataset from the data catalog.
data_catalog.DataCatalog.get_geodataset(...)	Returns a clipped, sliced and unified GeoDataset from the data catalog.
data_catalog.DataCatalog.get_geodataframe(...)	Returns a clipped and unified GeoDataFrame (vector) from the data catalog.

RasterDataset

data_adapter.RasterDatasetAdapter(path[, ...])	Initiates data adapter for geospatial raster data.
data_adapter.RasterDatasetAdapter.summary()	Returns a dictionary summary of the data adapter.
data_adapter.RasterDatasetAdapter.get_data([...])	Returns a clipped, sliced and unified RasterDataset based on the properties of this RasterDatasetAdapter.
data_adapter.RasterDatasetAdapter.to_dict()	Returns a dictionary view of the data source.
data_adapter.RasterDatasetAdapter.to_file(...)	Save a data slice to file.

GeoDataset

data_adapter.GeoDatasetAdapter(path[, ...])	Initiates data adapter for geospatial timeseries data.
data_adapter.GeoDatasetAdapter.summary()	Returns a dictionary summary of the data adapter.
data_adapter.GeoDatasetAdapter.get_data([...])	Returns a clipped, sliced and unified GeoDataset based on the properties of this GeoDatasetAdapter.
data_adapter.GeoDatasetAdapter.to_dict()	Returns a dictionary view of the data source.
data_adapter.GeoDatasetAdapter.to_file(...)	Save a data slice to file.

GeoDataFrame

data_adapter.GeoDataFrameAdapter(path[, ...])	Initiates data adapter for geospatial vector data.
data_adapter.GeoDataFrameAdapter.summary()	Returns a dictionary summary of the data adapter.
data_adapter.GeoDataFrameAdapter.get_data([...])	Returns a clipped and unified GeoDataFrame (vector) based on the properties of this GeoDataFrameAdapter.
data_adapter.GeoDataFrameAdapter.to_dict()	Returns a dictionary view of the data source.
data_adapter.GeoDataFrameAdapter.to_file(...)	Save a data slice to file.

DataFrame

data_adapter.DataFrameAdapter(path[, ...])	Initiates data adapter for 2D tabular data.
data_adapter.DataFrameAdapter.summary()	Returns a dictionary summary of the data adapter.
data_adapter.DataFrameAdapter.get_data([...])	Returns a DataFrame, optionally sliced by time and variables, based on the properties of this DataFrameAdapter.
data_adapter.DataFrameAdapter.to_dict()	Returns a dictionary view of the data source.
data_adapter.DataFrameAdapter.to_file(...[, ...])	Save dataframe slice to file.

Models

Discovery

ModelCatalog()

Classes

Model(root, mode, config_fn, data_libs, ...)	General and basic API for models in HydroMT
GridModel(root, mode, config_fn, data_libs)	Model class Grid Model for gridded models in HydroMT
LumpedModel(root, mode, config_fn, data_libs)	Model class Lumped Model for lumped models in HydroMT
MeshModel(root, mode, config_fn, data_libs)	Model class Mesh Model for mesh models in HydroMT

High level methods

Model.read([components])	Read the complete model schematization and configuration from model files.
Model.write([components])	Write the complete model schematization and configuration to model files.
Model.build(region[, res, write, opt])	Single method to build a model from scratch based on settings in opt.
Model.update([model_out, write, opt])	Single method to update a model based the settings in opt.
Model.set_root(root[, mode])	Initialize the model root.
Model.write_data_catalog([root, used_only])	Write the data catalog to hydromt_data.yml

Model components

Model.config	Model configuration.
Model.maps	Model maps.
Model.geoms	Model geometries.
Model.forcing	Model forcing.
Model.states	Model states.
Model.results	Model results.
MeshModel.mesh	Model static mesh data.
GridModel.grid	Model static gridded data.
LumpedModel.response_units	Model response unit (lumped) data.

General methods

Model.get_config(*args[, fallback, abs_path])	Get a config value at key(s).
Model.set_config(*args)	Update the config dictionary at key(s) with values.
Model.read_config([config_fn])	Parse config from file.
Model.write_config([config_name, config_root])	Write config to <root/config_fn>
Model.set_maps(data[, name, split_dataset])	Add raster data to the maps component.
Model.read_maps([fn])	Read model map at <root>/<fn> and add to maps component
Model.write_maps([fn])	Write maps to netcdf file at <root>/<fn>
Model.set_geoms(geom, name)	Add data to the geoms attribute.
Model.read_geoms([fn])	Read model geometries files at <root>/<fn> and add to geoms property
Model.write_geoms([fn])	Write model geometries to a vector file (by default GeoJSON) at <root>/<fn>
Model.set_forcing(data[, name, split_dataset])	Add data to forcing attribute.
Model.read_forcing([fn])	Read forcing at <root>/<fn> and add to forcing property
Model.write_forcing([fn])	Write forcing to netcdf file at <root>/<fn>
Model.set_states(data[, name, split_dataset])	Add data to states attribute.
Model.read_states([fn])	Read states at <root>/<fn> and add to states property
Model.write_states([fn])	Write states to netcdf file at <root>/<fn>
Model.set_results(data[, name, split_dataset])	Add data to results attribute.
Model.read_results([fn])	Read results at <root>/<fn> and add to results property
MeshModel.set_mesh(data[, name])	Add data to mesh.
MeshModel.read_mesh([fn])	Read model mesh data at <root>/<fn> and add to mesh property
MeshModel.write_mesh([fn])	Write model grid data to netcdf file at <root>/<fn>
GridModel.set_grid(data[, name])	Add data to grid.
GridModel.read_grid([fn])	Read model grid data at <root>/<fn> and add to grid property
GridModel.write_grid([fn])	Write model grid data to netcdf file at <root>/<fn>
LumpedModel.set_response_units(data[, name])	Add data to response_units.
LumpedModel.read_response_units([fn, fn_geom])	Read model response units from combined netcdf file at <root>/<fn> and geojson file at <root>/<fn_geom>.
LumpedModel.write_response_units([fn, fn_geom])	Write model response units to combined netcdf file at <root>/<fn> and geojson file at <root>/<fn_geom>.

Setup methods

Model.setup_config(**cfdict)	Update config with a dictionary
Model.setup_region(region[, hydrography_fn, ...])	This component sets the region of interest of the model.
Model.setup_maps_from_raster(raster_fn[, ...])	This component adds data variable(s) from raster_fn to maps object.
Model.setup_maps_from_raster_reclass(...[, ...])	This component adds data variable(s) to maps object by reclassifying the data in raster_fn based on reclass_table_fn.

Workflows

Basin mask

workflows.basin_mask.get_basin_geometry(ds)	Returns a geometry of the (sub)(inter)basin(s).
workflows.basin_mask.parse_region(region[, ...])	Checks and returns parsed region arguments.

River bathymetry

workflows.rivers.river_width(gdf_stream, ...)	Return segment average river width based on a river mask raster.
workflows.rivers.river_depth(data, method[, ...])	Derive river depth estimates based bankfull discharge.

Forcing

Data handling

workflows.forcing.precip(precip, da_like[, ...])	Lazy reprojection of precipitation to model grid and resampling of time dimension to frequency.
workflows.forcing.temp(temp, dem_model[, ...])	Lazy reprojection of temperature to model grid using lapse_rate for downscaling, and resampling of time dimension to frequency.
workflows.forcing.press(press, dem_model[, ...])	Lazy reprojection of pressure to model grid and resampling of time dimension to frequency.
workflows.forcing.pet(ds, temp, dem_model[, ...])	Determines reference evapotranspiration (lazy reprojection on model grid and resampling of time dimension to frequency).

Correction methods

workflows.forcing.press_correction(dem_model)	Pressure correction based on elevation lapse_rate.
workflows.forcing.temp_correction(dem[, ...])	Temperature correction based on elevation data.

Time resampling methods

workflows.forcing.resample_time(da, freq[, ...])	Resample data to destination frequency.
workflows.forcing.delta_freq(da_or_freq, ...)	Returns the relative difference between the dataset mean timestep and destination freq <1 : upsampling 1 : same >1 : downsampling

Computation methods

PET

workflows.forcing.pet_debruin(temp, press, ...)	Determines De Bruin (2016) reference evapotranspiration.
workflows.forcing.pet_makkink(temp, press, k_in)	Determnines Makkink reference evapotranspiration.

Reading/writing methods

Reading methods

io.open_raster(filename[, mask_nodata, ...])	Open a gdal-readable file with rasterio based on rioxarray.open_rasterio(), but return squeezed DataArray.
io.open_mfraster(paths[, chunks, concat, ...])	Open multiple gdal-readable files as single Dataset with geospatial attributes.
io.open_raster_from_tindex(fn_tindex[, ...])	Reads and merges raster tiles (potentially in different CRS) based on a tile index file as generated with gdaltindex.
io.open_vector(fn[, driver, crs, dst_crs, ...])	Open fiona-compatible geometry, csv, excel or xy file and parse to geopandas.GeoDataFrame().
io.open_vector_from_table(fn[, driver, ...])	Read point geometry files from csv, xy or excel table files.
io.open_geodataset(fn_locs[, fn_data, ...])	Open point location GIS file and timeseries file combine a single xarray.Dataset.
io.open_timeseries_from_table(fn[, name, ...])	Open timeseries csv file and parse to xarray.DataArray.

Raster writing methods

DataArray.raster.to_raster(raster_path[, ...])	Write DataArray object to a gdal-writable raster file.
Dataset.raster.to_mapstack(root[, driver, ...])	Write the Dataset object to one gdal-writable raster files per variable.

Raster methods

High level methods

merge.merge(data_arrays[, dst_crs, ...])	Merge multiple tiles to a single DataArray, if mismatching grid CRS or resolution, tiles are reprojected to match the output DataArray grid.
raster.full(coords[, nodata, dtype, name, ...])	Return a full DataArray based on a geospatial coords dictionary.
raster.full_like(other[, nodata, lazy])	Return a full object with the same grid and geospatial attributes as other.
raster.full_from_transform(transform, shape)	Return a full DataArray based on a geospatial transform and shape.

DataArray.raster.from_numpy(data, transform)	Transform a 2D/3D numpy array into a DataArray with geospatial attributes.
Dataset.raster.from_numpy(data_vars, transform)	Transform multiple numpy arrays to a Dataset object.

Attributes

DataArray.raster.attrs	Return dictionary of spatial attributes
DataArray.raster.crs	Return Coordinate Reference System as pyproj.CRS() object.
DataArray.raster.bounds	Return the bounds (xmin, ymin, xmax, ymax) of the object.
DataArray.raster.transform	Return the affine transform of the object.
DataArray.raster.res	Return resolution (x, y) tuple.
DataArray.raster.nodata	Nodata value of the DataArray.
DataArray.raster.dims	Return tuple of geospatial dimensions names.
DataArray.raster.coords	Return dict of geospatial dimensions coordinates.
DataArray.raster.dim0	Return the non geospatial dimension name.
DataArray.raster.y_dim	Return the y dimension name
DataArray.raster.x_dim	Return the x dimension name
DataArray.raster.xcoords	Return the x coordinates
DataArray.raster.ycoords	Return the y coordinates
DataArray.raster.shape	Return shape of geospatial dimension (height, width).
DataArray.raster.size	Return size of geospatial grid.
DataArray.raster.width	Return the width of the object (x dimension size).
DataArray.raster.height	Return the height of the object (y dimension size).
DataArray.raster.internal_bounds	Return the internal bounds of the object.
DataArray.raster.box	Return GeoDataFrame() of bounding box

General methods

DataArray.raster.set_crs([input_crs])	Set the Coordinate Reference System.
DataArray.raster.set_spatial_dims([x_dim, y_dim])	Set the geospatial dimensions of the object.
DataArray.raster.reset_spatial_dims_attrs()	Reset spatial dimension names and attributes to make CF-compliant Requires CRS attribute.
DataArray.raster.identical_grid(other)	Return True if other has an same grid as object (crs, transform, shape).
DataArray.raster.aligned_grid(other)	Return True if other grid aligns with object grid (crs, resolution, origin), but with a smaller extent
DataArray.raster.gdal_compliant([...])	Updates attributes to get GDAL compliant NetCDF files.
DataArray.raster.idx_to_xy(idx[, mask, ...])	Return x,y coordinates at linear index
DataArray.raster.xy_to_idx(xs, ys[, mask, ...])	Return linear index of x, y coordinates
DataArray.raster.rowcol(xs, ys[, mask, ...])	Return row, col indices of x, y coordinates
DataArray.raster.xy(r, c[, mask, ...])	Return x,y coordinates at cell center of row, col indices
DataArray.raster.flipud()	Returns raster flipped along y-axis
DataArray.raster.area_grid([dtype])	Returns the grid cell area [m2].
DataArray.raster.density_grid()	Returns the density in [unit/m2] of raster(s).

Nodata handling and interpolation

DataArray.raster.set_nodata([nodata, logger])	Set the nodata value as CF compliant attribute of the DataArray.
DataArray.raster.mask_nodata([fill_value])	Mask nodata values with fill_value (default np.nan).
DataArray.raster.interpolate_na([method])	Interpolate missing data

Clip

DataArray.raster.clip_bbox(bbox[, align, buffer])	Clip object based on a bounding box.
DataArray.raster.clip_mask(mask)	Clip object to region with mask values greater than zero.
DataArray.raster.clip_geom(geom[, align, ...])	Clip object to the bounding box of the geometry and add geometry 'mask' coordinate.

Reproject

DataArray.raster.reproject([dst_crs, ...])	Reproject a DataArray with geospatial coordinates, powered by rasterio.warp.reproject().
DataArray.raster.reindex2d(index[, dst_nodata])	Return reprojected DataArray object based on simple reindexing using linear indices in index, which can be calculated with nearest_index().
DataArray.raster.reproject_like(other[, method])	Reproject a object to match the grid of other.
DataArray.raster.transform_bounds(dst_crs[, ...])	Transform bounds from object to destination CRS.
DataArray.raster.nearest_index([dst_crs, ...])	Prepare nearest index mapping for the reprojection of a gridded timeseries file, powered by pyproj and k-d tree lookup.

Transform

DataArray.raster.rasterize(gdf[, col_name, ...])	Return an object with input geometry values burned in.
DataArray.raster.geometry_mask(gdf[, ...])	Return a grid with True values where shapes overlap pixels.
DataArray.raster.vectorize([connectivity])	Return geometry of grouped pixels with the same value in a DataArray object.
DataArray.raster.vector_grid()	Return a geopandas GeoDataFrame with a box for each grid cell.

Sampling and zonal stats

DataArray.raster.sample(gdf[, wdw])	Sample from map at point locations with optional window around the points.
DataArray.raster.zonal_stats(gdf, stats[, ...])	Calculate zonal statistics of raster samples aggregated for geometries.

Low level methods

gis_utils.axes_attrs(crs)	Provide CF-compliant variable names and metadata for axes
gis_utils.meridian_offset(ds[, x_name, bbox])	re-arange data along x dim

Geospatial timeseries methods

High level methods

DataArray.vector.from_gdf(gdf, array_like[, ...])	Parse GeoDataFrame object with point geometries to DataArray with geospatial attributes and merge with array_like data.
DataArray.vector.to_gdf([reducer])	Return geopandas GeoDataFrame with Point geometry based on DataArray coordinates.
Dataset.vector.from_gdf(gdf[, data_vars, ...])	Creates Dataset with geospatial coordinates.

Attributes

DataArray.vector.attrs	Return dictionary of spatial attributes
DataArray.vector.crs	Return Coordinate Reference System as pyproj.CRS() object.
DataArray.vector.index_dim	Index dimension name.
DataArray.vector.time_dim	Time dimension name.
DataArray.vector.y_dim
DataArray.vector.x_dim
DataArray.vector.xcoords	Return the x coordinates
DataArray.vector.ycoords	Return the y coordinates
DataArray.vector.index
DataArray.vector.bounds	Return the bounds (xmin, ymin, xmax, ymax) of the object.
DataArray.vector.total_bounds	Return the bounds (xmin, ymin, xmax, ymax) of the object.
DataArray.vector.sindex
DataArray.vector.geometry

General methods

DataArray.vector.set_crs([input_crs])	Set the Coordinate Reference System.
DataArray.vector.set_spatial_dims([x_dim, ...])	Set the spatial and index dimensions of the object.
DataArray.vector.reset_spatial_dims_attrs()	Reset spatial dimension names and attributes to make CF-compliant Requires CRS attribute.

Clip

DataArray.vector.clip_bbox(bbox[, buffer, ...])	Select point locations to bounding box.
DataArray.vector.clip_geom(geom[, predicate])	Select point locations to geometry.

Reproject

DataArray.vector.to_crs(dst_crs)

Transform spatial coordinates to a new coordinate reference system.

Flow direction methods

These methods are based on the pyflwdir library. For more flow direction based methods visit the pyflwdir docs.

flw.flwdir_from_da(da[, ftype, check_ftype, ...])	Parse dataarray to flow direction raster object.
flw.d8_from_dem(da_elv[, gdf_stream, ...])	Derive D8 flow directions grid from an elevation grid.
flw.reproject_hydrography_like(ds_hydro, da_elv)	Reproject flow direction and upstream area data to the da_elv crs and grid.
flw.upscale_flwdir(ds, flwdir, scale_ratio)	Upscale flow direction network to lower resolution.
flw.stream_map(ds[, stream])	Return a stream mask DataArray
flw.basin_map(ds, flwdir[, xy, idxs, ...])	Return a (sub)basin map, with unique non-zero IDs for each subbasin.
flw.gauge_map(ds[, idxs, xy, ids, stream, ...])	Return map with unique gauge IDs.
flw.outlet_map(da_flw[, ftype])	Returns a mask of basin outlets/pits from a flow direction raster.
flw.clip_basins(ds, flwdir, xy[, flwdir_name])	Clip a dataset to a subbasin.
flw.dem_adjust(da_elevtn, da_flwdir[, ...])	Returns hydrologically conditioned elevation.

General GIS methods

Raster

gis_utils.spread2d(da_obs[, da_mask, ...])	Returns values of da_obs spreaded to cells with nodata value within da_mask, powered by pyflwdir.gis_utils.spread2d()
gis_utils.reggrid_area(lats, lons)	Returns the cell area [m2] for a regular grid based on its cell centres lat, lon coordinates.
gis_utils.cellarea(lat[, xres, yres])	Return the area [m2] of cell based on the cell center latitude and its resolution in measured in degrees.
gis_utils.cellres(lat[, xres, yres])	Return the cell (x, y) resolution [m] based on cell center latitude and its resolution measured in degrees.

CRS and transform

gis_utils.parse_crs(crs[, bbox])
gis_utils.utm_crs(bbox)	Returns wkt string of nearest UTM projects
gis_utils.affine_to_coords(transform, shape)	Returs a raster axis with pixel center coordinates based on the transform.

Vector

gis_utils.filter_gdf(gdf[, geom, bbox, ...])	Filter GeoDataFrame geometries based on geometry mask or bounding box.
gis_utils.nearest(gdf1, gdf2)	Return the index of and distance [m] to the nearest geometry in gdf2 for each geometry of gdf1.
gis_utils.nearest_merge(gdf1, gdf2[, ...])	Merge attributes of gdf2 with the nearest feature of gdf1, optionally bounded by a maximumum distance max_dist.

PCRaster I/O

gis_utils.write_map(data, raster_path, ...)	Write pcraster map files using pcr.report functionality.
gis_utils.write_clone(tmpdir, ...)	write pcraster clone file to a tmpdir using gdal

Statistics

Statistics and performance metrics

stats.skills.bias(sim, obs[, dim])	Returns the bias between two time series.
stats.skills.percentual_bias(sim, obs[, dim])	Returns the percentual bias between two time series.
stats.skills.nashsutcliffe(sim, obs[, dim])	Returns the Nash-Sutcliffe model efficiency based on a simulated and observed time series.
stats.skills.lognashsutcliffe(sim, obs[, ...])	Returns the log Nash-Sutcliffe model efficiency based on simulated and observed time series.
stats.skills.pearson_correlation(sim, obs[, dim])	Returns the Pearson correlation coefficient of two time series.
stats.skills.spearman_rank_correlation(sim, obs)	Returns the spearman rank correlation coefficient of two time series.
stats.skills.kge(sim, obs[, dim])	Returns the Kling-Gupta Efficiency (KGE) of two time series
stats.skills.kge_2012(sim, obs[, dim])	Returns the Kling-Gupta Efficiency (KGE, 2012) of two time series
stats.skills.kge_non_parametric(sim, obs[, dim])	Returns the Non Parametric Kling-Gupta Efficiency (KGE, 2018) of two time series with decomposed scores
stats.skills.kge_non_parametric_flood(sim, obs)	Returns the Non Parametric Kling-Gupta Efficiency (KGE, 2018) of two time series optimized for flood peaks using Pearson (see Pool et al., 2018)
stats.skills.rsquared(sim, obs[, dim])	Returns the coefficient of determination of two time series.
stats.skills.mse(sim, obs[, dim])	Returns the mean squared error (MSE) between two time series.
stats.skills.rmse(sim, obs[, dim])	Returns the root mean squared error between two time series.

Utilities

Configuration files

config.configread(config_fn[, encoding, cf, ...])	Read configuration file and parse to (nested) dictionary.
config.configwrite(config_fn, cfdict[, ...])	_summary_

Logging

log.setuplog([name, path, log_level, fmt, ...])