Tip

For an interactive online version click here: Binder badge

Example: Working with models from CLI#

HydroMT has the following high-level functionality from the Command Line Interface (CLI) for setting up models from raw data or adjusting models:

  • building a model: building a model from scratch.

  • updating a model: adding or changing model components of an existing model.

  • clipping a model: changing the spatial domain of an existing model (e.g. select subbasins from a larger model).

Here we show how to build and update a hypothetical distributed model from the command line interface (CLI) based on the generic HydroMT grid_model.

Lets first check which models are available in our environment:

[1]:
!hydromt --models
model plugins:
generic models (hydromt 0.9.5.dev0):
 - grid_model
 - vector_model
 - mesh_model
 - network_model


Build a model from CLI#

To build a model you always follow the next four steps.

  1. Prepare or use a pre-defined data catalog with all the required data sources

  2. Define your model region, see the overview of model region options.

  3. Prepare a model configuration which describes the complete pipeline to build your model, see preparing a model configuration.

  4. Build you model using the CLI or Python interface

Here we focus steps 2-4 and use data from the predefined artifact_data data catalog

Using the hydromt build method we can setup a complete model from scratch. Let’s get an overview of the method and its arguments.

Note the required MODEL (i.e. name of the model), MODEL_ROOT (i.e. folder where to save the model) arguments. As of version v0.7.0 the REGION (i.e. area of interest) argument is optional. This argument can be used by adding -r or –region flag.

[2]:
!hydromt build --help
Usage: hydromt build [OPTIONS] MODEL MODEL_ROOT

  Build models from scratch.

  Example usage: --------------

  To build a wflow model for a subbasin using a point coordinates snapped to
  cells with upstream area >= 50 km2 hydromt build wflow /path/to/model_root
  -i /path/to/wflow_config.yml  -r "{'subbasin': [-7.24, 62.09], 'uparea':
  50}" -d deltares_data -d /path/to/data_catalog.yml -v

  To build a sfincs model based on a bbox hydromt build sfincs
  /path/to/model_root  -i /path/to/sfincs_config.yml  -r "{'bbox':
  [4.6891,52.9750,4.9576,53.1994]}"  -d /path/to/data_catalog.yml -v

Options:
  --opt TEXT               Method specific keyword arguments, see the method
                           documentation of the specific model for more
                           information about the arguments.
  -i, --config PATH        Path to hydroMT configuration file, for the model
                           specific implementation.
  -r, --region TEXT        Set the region for which to build the model, e.g.
                           {'subbasin': [-7.24, 62.09]}
  -d, --data TEXT          Path to local yaml data catalog file OR name of
                           predefined data catalog.
  --dd, --deltares-data    Flag: Shortcut to add the "deltares_data" catalog
  --fo, --force-overwrite  Flag: If provided overwrite existing model files
  --cache                  Flag: If provided cache tiled rasterdatasets
  -v, --verbose            Increase verbosity.
  -q, --quiet              Decrease verbosity.
  --help                   Show this message and exit.

[3]:
!hydromt build grid_model ./tmp_grid_model --region "{'bbox': [11.70, 45.35, 12.95, 46.70]}" --opt "setup_grid.res"=0.05 -vv
2024-03-27 01:26:00,228 - build - log - DEBUG - Writing log messages to new file /home/runner/work/hydromt/hydromt/docs/_examples/tmp_grid_model/hydromt.log.
2024-03-27 01:26:00,228 - build - log - INFO - HydroMT version: 0.9.5.dev0
2024-03-27 01:26:00,228 - build - main - INFO - Building instance of grid_model model at /home/runner/work/hydromt/hydromt/docs/_examples/tmp_grid_model.
2024-03-27 01:26:00,228 - build - main - INFO - User settings:
2024-03-27 01:26:00,243 - build - model_api - INFO - Initializing grid_model model from hydromt (v0.9.5.dev0).
2024-03-27 01:26:00,243 - build - model_api - INFO - setup_grid.region: {'bbox': [11.7, 45.35, 12.95, 46.7]}
2024-03-27 01:26:00,243 - build - model_api - INFO - setup_grid.res: 0.05
2024-03-27 01:26:00,243 - build - model_api - INFO - setup_grid.crs: None
2024-03-27 01:26:00,243 - build - model_api - INFO - setup_grid.rotated: False
2024-03-27 01:26:00,243 - build - model_api - INFO - setup_grid.hydrography_fn: None
2024-03-27 01:26:00,243 - build - model_api - INFO - setup_grid.basin_index_fn: None
2024-03-27 01:26:00,243 - build - model_api - INFO - setup_grid.add_mask: True
2024-03-27 01:26:00,243 - build - model_api - INFO - setup_grid.align: True
2024-03-27 01:26:00,243 - build - model_api - INFO - setup_grid.dec_origin: 0
2024-03-27 01:26:00,243 - build - model_api - INFO - setup_grid.dec_rotation: 3
2024-03-27 01:26:00,243 - build - model_grid - INFO - Preparing 2D grid.
2024-03-27 01:26:00,243 - build - basin_mask - DEBUG - Parsed region (kind=bbox): {'bbox': [11.7, 45.35, 12.95, 46.7]}
2024-03-27 01:26:00,254 - build - model_api - INFO - Writing model data to /home/runner/work/hydromt/hydromt/docs/_examples/tmp_grid_model
2024-03-27 01:26:00,254 - build - model_api - INFO - Writing model config to /home/runner/work/hydromt/hydromt/docs/_examples/tmp_grid_model/model.ini
2024-03-27 01:26:00,254 - build - model_api - ERROR - Default config file not found at grid_model/model.ini
2024-03-27 01:26:00,254 - build - model_api - DEBUG - No maps data found, skip writing.
2024-03-27 01:26:00,254 - build - model_api - DEBUG - Writing file grid/grid.nc
2024-03-27 01:26:00,368 - build - model_api - DEBUG - Writing file geoms/region.geojson
2024-03-27 01:26:00,401 - build - model_api - DEBUG - No tables found, skip writing.
2024-03-27 01:26:00,401 - build - model_api - DEBUG - No forcing data found, skip writing.
2024-03-27 01:26:00,401 - build - model_api - DEBUG - No states data found, skip writing.

The example above means the following: run hydromt build with:

  • grid_model: i.e. build a generic GridModel instance

  • ./tmp_grid_model: output model folder

  • --region "{'bbox': [11.70, 45.35, 12.95, 46.70]}": set the region of interest using a bounding box defined by its [xmin, ymin, xmax, ymax] coordinates (in WGS84)

  • --opt "setup_grid.res" = 0.05: choose the resolution of the grid to generate within the bounding box. Unit (degree or meter) depends on the chosen coordinate system.

  • -vv : give some extra verbosity (2 * v) to display feedback on screen. Now debug messages are provided.

As we did not specify a hydromt configuration, besides the hydromt.log file, an empty model simulation configuration file, only the model region (area of interest) and the grid definition have been defined and are respectively saved in the geoms folder and the grid.nc file. To build a complete model we need the use a hydromt configuration .yaml file.

[4]:
# print MODEL_ROOT folder
import os


def print_dir(root):
    for path, _, files in os.walk(root):
        print(path)
        for name in files:
            if name.endswith(".xml"):
                continue
            print(f" - {name}")


print_dir("tmp_grid_model")
tmp_grid_model
 - model.ini
 - hydromt.log
tmp_grid_model/grid
 - grid.nc
tmp_grid_model/geoms
 - region.geojson

The configuration file exists of available setup_methods for your model, listed in the order of execution. Most methods start with reading input data using the DataAdapter, transforming the data using workflows (e.g. reprojection, reclassification, aggregation, etc…) and adding the new model data to the right model component. An overview of the available methods can be found in the online API reference for the GridModel, VectorModel, and MeshModel

Note that these methods for the generic model classes are still quite limited. To get an idea of potential setup_ methods, checkout the model plugins

The configuration yaml file can be passed to the hydromt build method using the -i flag.

[5]:
# check the content of the .yaml file (for sake of the example only)
fn_yaml = "grid_model_build.yaml"
with open(fn_yaml, "r") as f:
    txt = f.read()
print(txt)
---
setup_config:
  header.settings: value
  timers.end: '2010-02-15'
  timers.start: '2010-02-05'

setup_grid:
  res: 0.05
  crs: 4326
  basin_index_fn: merit_hydro_index
  hydrography_fn: merit_hydro

setup_grid_from_constant:
  constant: 0.01
  name: c1
  dtype: float32
  nodata: -99.0

setup_grid_from_rasterdataset:
  raster_fn: merit_hydro_1k
  variables:
    - elevtn
    - basins
  reproject_method:
    - average
    - mode

setup_grid_from_rasterdataset2:
  raster_fn: vito
  fill_method: nearest
  reproject_method: mode
  rename:
    vito: landuse

setup_grid_from_raster_reclass:
  raster_fn: vito
  reclass_table_fn: vito_reclass
  reclass_variables:
    - manning
  reproject_method:
    - average

setup_grid_from_geodataframe:
  vector_fn: hydro_lakes
  variables:
    - waterbody_id
    - Depth_avg
  nodata:
    - -1
    - -999.0
  rasterize_method: value
  rename:
    waterbody_id: lake_id
    Detph_avg: lake_depth

setup_grid_from_geodataframe2:
  vector_fn: hydro_lakes
  rasterize_method: fraction
  rename:
    hydro_lakes: water_frac

write:
  components:
    - config
    - geoms
    - grid

In this configuration, you see that we will prepare quite a lot of data for our grid model using some of the generic model methods for grid. We will prepare:

  • A grid with constant values 0.01 using setup_grid_from_constant

  • A couple of grid based on reprojection of MERIT Hydro IHU (elevation, basins) and VITO (landuse) using setup_grid_from_rasterdataset. Note that to use the same method twice within the same configuration file, you can end the method name with a number.

  • A grid generated by mapping roughness values to the land use classes in VITO using setup_grid_from_raster_reclass

  • A couple of lake properties including the fraction of the grid cells covered by the lake geometry using setup_grid_from_geodataframe

[6]:
!hydromt build grid_model ./tmp_grid_model1 -r "{'bbox': [11.70, 45.35, 12.95, 46.70]}" -i grid_model_build.yaml -d artifact_data -d data/vito_reclass.yml -vv
2024-03-27 01:26:02,914 - build - log - DEBUG - Writing log messages to new file /home/runner/work/hydromt/hydromt/docs/_examples/tmp_grid_model1/hydromt.log.
2024-03-27 01:26:02,914 - build - log - INFO - HydroMT version: 0.9.5.dev0
2024-03-27 01:26:02,914 - build - main - INFO - Building instance of grid_model model at /home/runner/work/hydromt/hydromt/docs/_examples/tmp_grid_model1.
2024-03-27 01:26:02,915 - build - main - INFO - User settings:
2024-03-27 01:26:02,957 - build - data_catalog - INFO - Reading data catalog archive artifact_data v0.0.8
2024-03-27 01:26:02,958 - build - data_catalog - INFO - Parsing data catalog from /home/runner/.hydromt_data/artifact_data/v0.0.8/data_catalog.yml
2024-03-27 01:26:03,001 - build - data_catalog - INFO - Parsing data catalog from data/vito_reclass.yml
2024-03-27 01:26:03,002 - build - model_api - INFO - Initializing grid_model model from hydromt (v0.9.5.dev0).
2024-03-27 01:26:03,002 - build - model_api - DEBUG - Setting model config options.
2024-03-27 01:26:03,002 - build - model_api - ERROR - Default config file not found at grid_model/model.ini
2024-03-27 01:26:03,003 - build - model_api - INFO - setup_grid.region: {'bbox': [11.7, 45.35, 12.95, 46.7]}
2024-03-27 01:26:03,003 - build - model_api - INFO - setup_grid.res: 0.05
2024-03-27 01:26:03,003 - build - model_api - INFO - setup_grid.crs: 4326
2024-03-27 01:26:03,003 - build - model_api - INFO - setup_grid.rotated: False
2024-03-27 01:26:03,003 - build - model_api - INFO - setup_grid.hydrography_fn: merit_hydro
2024-03-27 01:26:03,003 - build - model_api - INFO - setup_grid.basin_index_fn: merit_hydro_index
2024-03-27 01:26:03,003 - build - model_api - INFO - setup_grid.add_mask: True
2024-03-27 01:26:03,003 - build - model_api - INFO - setup_grid.align: True
2024-03-27 01:26:03,003 - build - model_api - INFO - setup_grid.dec_origin: 0
2024-03-27 01:26:03,003 - build - model_api - INFO - setup_grid.dec_rotation: 3
2024-03-27 01:26:03,003 - build - model_grid - INFO - Preparing 2D grid.
2024-03-27 01:26:03,003 - build - basin_mask - DEBUG - Parsed region (kind=bbox): {'bbox': [11.7, 45.35, 12.95, 46.7]}
2024-03-27 01:26:03,015 - build - model_api - INFO - setup_grid_from_constant.constant: 0.01
2024-03-27 01:26:03,015 - build - model_api - INFO - setup_grid_from_constant.name: c1
2024-03-27 01:26:03,015 - build - model_api - INFO - setup_grid_from_constant.dtype: float32
2024-03-27 01:26:03,015 - build - model_api - INFO - setup_grid_from_constant.nodata: -99.0
2024-03-27 01:26:03,015 - build - model_api - INFO - setup_grid_from_constant.mask_name: mask
2024-03-27 01:26:03,020 - build - model_api - INFO - setup_grid_from_rasterdataset.raster_fn: merit_hydro_1k
2024-03-27 01:26:03,020 - build - model_api - INFO - setup_grid_from_rasterdataset.variables: ['elevtn', 'basins']
2024-03-27 01:26:03,020 - build - model_api - INFO - setup_grid_from_rasterdataset.fill_method: None
2024-03-27 01:26:03,020 - build - model_api - INFO - setup_grid_from_rasterdataset.reproject_method: ['average', 'mode']
2024-03-27 01:26:03,020 - build - model_api - INFO - setup_grid_from_rasterdataset.mask_name: mask
2024-03-27 01:26:03,020 - build - model_api - INFO - setup_grid_from_rasterdataset.rename: None
2024-03-27 01:26:03,020 - build - model_grid - INFO - Preparing grid data from raster source merit_hydro_1k
2024-03-27 01:26:03,021 - build - rasterdataset - INFO - Reading merit_hydro_1k raster data from /home/runner/.hydromt_data/artifact_data/v0.0.8/merit_hydro_1k/{variable}.tif
2024-03-27 01:26:03,071 - build - rasterdataset - DEBUG - Clip to [11.700, 45.350, 12.950, 46.700] (epsg:4326))
2024-03-27 01:26:03,245 - build - model_api - INFO - setup_grid_from_rasterdataset.raster_fn: vito
2024-03-27 01:26:03,245 - build - model_api - INFO - setup_grid_from_rasterdataset.variables: None
2024-03-27 01:26:03,245 - build - model_api - INFO - setup_grid_from_rasterdataset.fill_method: nearest
2024-03-27 01:26:03,245 - build - model_api - INFO - setup_grid_from_rasterdataset.reproject_method: mode
2024-03-27 01:26:03,245 - build - model_api - INFO - setup_grid_from_rasterdataset.mask_name: mask
2024-03-27 01:26:03,246 - build - model_api - INFO - setup_grid_from_rasterdataset.rename: {'vito': 'landuse'}
2024-03-27 01:26:03,246 - build - model_grid - INFO - Preparing grid data from raster source vito
2024-03-27 01:26:03,246 - build - rasterdataset - INFO - Reading vito raster data from /home/runner/.hydromt_data/artifact_data/v0.0.8/vito.tif
2024-03-27 01:26:03,260 - build - rasterdataset - DEBUG - Clip to [11.700, 45.350, 12.950, 46.700] (epsg:4326))
2024-03-27 01:26:03,301 - build - model_api - INFO - setup_grid_from_raster_reclass.raster_fn: vito
2024-03-27 01:26:03,301 - build - model_api - INFO - setup_grid_from_raster_reclass.reclass_table_fn: vito_reclass
2024-03-27 01:26:03,301 - build - model_api - INFO - setup_grid_from_raster_reclass.reclass_variables: ['manning']
2024-03-27 01:26:03,301 - build - model_api - INFO - setup_grid_from_raster_reclass.variable: None
2024-03-27 01:26:03,301 - build - model_api - INFO - setup_grid_from_raster_reclass.fill_method: None
2024-03-27 01:26:03,301 - build - model_api - INFO - setup_grid_from_raster_reclass.reproject_method: ['average']
2024-03-27 01:26:03,301 - build - model_api - INFO - setup_grid_from_raster_reclass.mask_name: mask
2024-03-27 01:26:03,301 - build - model_api - INFO - setup_grid_from_raster_reclass.rename: None
2024-03-27 01:26:03,301 - build - model_grid - INFO - Preparing grid data by reclassifying the data in vito based on vito_reclass
2024-03-27 01:26:03,302 - build - rasterdataset - INFO - Reading vito raster data from /home/runner/.hydromt_data/artifact_data/v0.0.8/vito.tif
2024-03-27 01:26:03,315 - build - rasterdataset - DEBUG - Clip to [11.700, 45.350, 12.950, 46.700] (epsg:4326))
2024-03-27 01:26:03,316 - build - dataframe - INFO - Reading vito_reclass csv data from /home/runner/work/hydromt/hydromt/docs/_examples/data/vito_reclass.csv
2024-03-27 01:26:03,522 - build - model_api - INFO - setup_grid_from_geodataframe.vector_fn: hydro_lakes
2024-03-27 01:26:03,523 - build - model_api - INFO - setup_grid_from_geodataframe.variables: ['waterbody_id', 'Depth_avg']
2024-03-27 01:26:03,523 - build - model_api - INFO - setup_grid_from_geodataframe.nodata: [-1, -999.0]
2024-03-27 01:26:03,523 - build - model_api - INFO - setup_grid_from_geodataframe.rasterize_method: value
2024-03-27 01:26:03,523 - build - model_api - INFO - setup_grid_from_geodataframe.mask_name: mask
2024-03-27 01:26:03,523 - build - model_api - INFO - setup_grid_from_geodataframe.rename: {'waterbody_id': 'lake_id', 'Detph_avg': 'lake_depth'}
2024-03-27 01:26:03,523 - build - model_api - INFO - setup_grid_from_geodataframe.all_touched: True
2024-03-27 01:26:03,523 - build - model_grid - INFO - Preparing grid data from vector 'hydro_lakes'.
2024-03-27 01:26:03,524 - build - geodataframe - INFO - Reading hydro_lakes vector data from /home/runner/.hydromt_data/artifact_data/v0.0.8/hydro_lakes.gpkg
2024-03-27 01:26:03,570 - build - geodataframe - DEBUG - Clip intersects [11.700, 45.350, 12.950, 46.700] (EPSG:4326)
2024-03-27 01:26:03,571 - build - geodataframe - DEBUG - Convert units for 1 columns.
2024-03-27 01:26:03,586 - build - model_api - INFO - setup_grid_from_geodataframe.vector_fn: hydro_lakes
2024-03-27 01:26:03,586 - build - model_api - INFO - setup_grid_from_geodataframe.variables: None
2024-03-27 01:26:03,586 - build - model_api - INFO - setup_grid_from_geodataframe.nodata: -1
2024-03-27 01:26:03,586 - build - model_api - INFO - setup_grid_from_geodataframe.rasterize_method: fraction
2024-03-27 01:26:03,586 - build - model_api - INFO - setup_grid_from_geodataframe.mask_name: mask
2024-03-27 01:26:03,586 - build - model_api - INFO - setup_grid_from_geodataframe.rename: {'hydro_lakes': 'water_frac'}
2024-03-27 01:26:03,586 - build - model_api - INFO - setup_grid_from_geodataframe.all_touched: True
2024-03-27 01:26:03,586 - build - model_grid - INFO - Preparing grid data from vector 'hydro_lakes'.
2024-03-27 01:26:03,587 - build - geodataframe - INFO - Reading hydro_lakes vector data from /home/runner/.hydromt_data/artifact_data/v0.0.8/hydro_lakes.gpkg
2024-03-27 01:26:03,609 - build - geodataframe - DEBUG - Clip intersects [11.700, 45.350, 12.950, 46.700] (EPSG:4326)
2024-03-27 01:26:03,610 - build - geodataframe - DEBUG - Convert units for 1 columns.
2024-03-27 01:26:03,648 - build - model_api - INFO - write.components: ['config', 'geoms', 'grid']
2024-03-27 01:26:03,648 - build - model_api - INFO - Writing model data to /home/runner/work/hydromt/hydromt/docs/_examples/tmp_grid_model1
2024-03-27 01:26:03,648 - build - model_api - INFO - Writing model config to /home/runner/work/hydromt/hydromt/docs/_examples/tmp_grid_model1/model.ini
2024-03-27 01:26:03,648 - build - model_api - DEBUG - Writing file geoms/region.geojson
2024-03-27 01:26:03,652 - build - model_api - DEBUG - Writing file grid/grid.nc
2024-03-27 01:26:03,846 - build - model_api - INFO - Writing model data to /home/runner/work/hydromt/hydromt/docs/_examples/tmp_grid_model1
2024-03-27 01:26:03,846 - build - model_api - INFO - Writing model config to /home/runner/work/hydromt/hydromt/docs/_examples/tmp_grid_model1/model.ini
2024-03-27 01:26:03,846 - build - model_api - DEBUG - No maps data found, skip writing.
2024-03-27 01:26:03,846 - build - model_api - DEBUG - Writing file grid/grid.nc
2024-03-27 01:26:04,030 - build - model_api - DEBUG - Writing file geoms/region.geojson
2024-03-27 01:26:04,034 - build - model_api - DEBUG - No tables found, skip writing.
2024-03-27 01:26:04,034 - build - model_api - DEBUG - No forcing data found, skip writing.
2024-03-27 01:26:04,034 - build - model_api - DEBUG - No states data found, skip writing.

The example above means the following: run hydromt build with:

  • grid_model: i.e. build a generic GridModel instance

  • ./tmp_grid_model1: output model folder

  • -r "{'bbox': [11.70, 45.35, 12.95, 46.70]}": set the region of interest using a bounding box defined by its [xmin, ymin, xmax, ymax] coordinates (in WGS84)

  • -i grid_model_build.yaml: use this .yaml file to configure the model build

  • -d artifact_data -d data/vito_reclass.yml: parse the pre-defined artifact_data and the local vito_reclass data catalogs

  • -vv : give some extra verbosity (2 * v) to display feedback on screen. Now debug messages are provided.

Let’s check some of the outputs that were produced:

[7]:
# Files created
print_dir("tmp_grid_model1")
tmp_grid_model1
 - model.ini
 - hydromt.log
tmp_grid_model1/grid
 - grid.nc
tmp_grid_model1/geoms
 - region.geojson
[8]:
# checkout the content of the hypothetical model simulation configuration
fn_yaml = "tmp_grid_model1/model.ini"
with open(fn_yaml, "r") as f:
    txt = f.read()
print(txt)
[header]
settings = value

[timers]
end = 2010-02-15
start = 2010-02-05


[9]:
# List of variables in grid.nc
import xarray as xr
ds = xr.open_dataset("tmp_grid_model1/grid/grid.nc")

print(f"Variables available in grid.nc: {list(ds.data_vars)}")
Variables available in grid.nc: ['mask', 'c1', 'elevtn', 'basins', 'landuse', 'manning', 'lake_id', 'Depth_avg', 'water_frac']
[10]:
# Plot one of the variable (change the name below to plot a different variable)
var = "elevtn"
ds[var].plot()
[10]:
<matplotlib.collections.QuadMesh at 0x7f426089dd90>
../_images/_examples_working_with_models_basics_21_1.png

Update a model from CLI#

Using the hydromt update method we can update an existing model with new components or modify existing components. Let’s get an overview of the method and its arguments.

Note that the MODEL (i.e. name of the model), and MODEL_ROOT (i.e. folder of existing model) are still required. There is an optional -o --model-out option to save the updated model in a different directory.

[11]:
!hydromt update --help
Usage: hydromt update [OPTIONS] MODEL MODEL_ROOT

  Update a specific component of a model.

  Set an output directory to copy the edited model to a new folder, otherwise
  maps are overwritten.

  Example usage: --------------

  Update (overwrite!) landuse-landcover based maps in a Wflow model: hydromt
  update wflow /path/to/model_root -c setup_lulcmaps --opt lulc_fn=vito -d
  /path/to/data_catalog.yml -v

  Update Wflow model components outlined in an .yml configuration file and
  write the model to a directory: hydromt update wflow /path/to/model_root  -o
  /path/to/model_out  -i /path/to/wflow_config.yml  -d
  /path/to/data_catalog.yml -v

Options:
  -o, --model-out DIRECTORY  Output model folder. Maps in MODEL_ROOT are
                             overwritten if left empty.
  -i, --config PATH          Path to hydroMT configuration file, for the model
                             specific implementation.
  -c, --components TEXT      Model methods from configuration file to run
  --opt TEXT                 Method specific keyword arguments, see the method
                             documentation of the specific model for more
                             information about the arguments.
  -d, --data TEXT            Path to local yaml data catalog file OR name of
                             predefined data catalog.
  --dd, --deltares-data      Flag: Shortcut to add the "deltares_data" catalog
  --fo, --force-overwrite    Flag: If provided overwrite existing model files
  --cache                    Flag: If provided cache tiled rasterdatasets
  -q, --quiet                Decrease verbosity.
  -v, --verbose              Increase verbosity.
  --help                     Show this message and exit.

In this basic example we use the hydromt update method to update the GridModel instance with an upstream area raster map. Then we write only the updated model map component to file.

The %%writefile magic saves the content below to a file. The content of the .yaml file start from the second line.

[12]:
%%writefile ./tmp_grid_model1/grid_model_update.yaml
setup_grid_from_rasterdataset:
    raster_fn: merit_hydro_1k
    variables: uparea
    reproject_method: max

write_grid:

Writing ./tmp_grid_model1/grid_model_update.yaml
[13]:
!hydromt update grid_model ./tmp_grid_model1 -o ./tmp_grid_model1_update -i ./tmp_grid_model1/grid_model_update.yaml -d artifact_data -vv
2024-03-27 01:26:10,003 - update - log - DEBUG - Writing log messages to new file /home/runner/work/hydromt/hydromt/docs/_examples/tmp_grid_model1_update/hydromt.log.
2024-03-27 01:26:10,003 - update - log - INFO - HydroMT version: 0.9.5.dev0
2024-03-27 01:26:10,003 - update - main - INFO - Updating grid_model model at /home/runner/work/hydromt/hydromt/docs/_examples/tmp_grid_model1 (r).
2024-03-27 01:26:10,003 - update - main - INFO - Output dir: /home/runner/work/hydromt/hydromt/docs/_examples/tmp_grid_model1_update
2024-03-27 01:26:10,003 - update - main - INFO - User settings:
2024-03-27 01:26:10,043 - update - data_catalog - INFO - Reading data catalog archive artifact_data v0.0.8
2024-03-27 01:26:10,043 - update - data_catalog - INFO - Parsing data catalog from /home/runner/.hydromt_data/artifact_data/v0.0.8/data_catalog.yml
2024-03-27 01:26:10,087 - update - log - DEBUG - Appending log messages to file /home/runner/work/hydromt/hydromt/docs/_examples/tmp_grid_model1/hydromt.log.
2024-03-27 01:26:10,087 - update - model_api - INFO - Initializing grid_model model from hydromt (v0.9.5.dev0).
2024-03-27 01:26:10,087 - update - model_api - INFO - Reading model data from /home/runner/work/hydromt/hydromt/docs/_examples/tmp_grid_model1
2024-03-27 01:26:10,088 - update - model_api - DEBUG - Model config read from /home/runner/work/hydromt/hydromt/docs/_examples/tmp_grid_model1/model.ini
2024-03-27 01:26:10,088 - update - model_api - DEBUG - Reading model file grid.
2024-03-27 01:26:10,127 - update - model_api - DEBUG - Reading model file region.
2024-03-27 01:26:10,156 - update - model_api - INFO - Reading model table files.
2024-03-27 01:26:10,157 - update - log - DEBUG - Appending log messages to file /home/runner/work/hydromt/hydromt/docs/_examples/tmp_grid_model1_update/hydromt.log.
2024-03-27 01:26:10,158 - update - model_api - INFO - setup_grid_from_rasterdataset.raster_fn: merit_hydro_1k
2024-03-27 01:26:10,158 - update - model_api - INFO - setup_grid_from_rasterdataset.variables: uparea
2024-03-27 01:26:10,158 - update - model_api - INFO - setup_grid_from_rasterdataset.fill_method: None
2024-03-27 01:26:10,158 - update - model_api - INFO - setup_grid_from_rasterdataset.reproject_method: max
2024-03-27 01:26:10,158 - update - model_api - INFO - setup_grid_from_rasterdataset.mask_name: mask
2024-03-27 01:26:10,158 - update - model_api - INFO - setup_grid_from_rasterdataset.rename: None
2024-03-27 01:26:10,158 - update - model_grid - INFO - Preparing grid data from raster source merit_hydro_1k
2024-03-27 01:26:10,159 - update - rasterdataset - INFO - Reading merit_hydro_1k raster data from /home/runner/.hydromt_data/artifact_data/v0.0.8/merit_hydro_1k/{variable}.tif
2024-03-27 01:26:10,175 - update - rasterdataset - DEBUG - Clip to [11.700, 45.350, 12.950, 46.700] (epsg:4326))
2024-03-27 01:26:10,328 - update - model_api - INFO - write_grid.fn: grid/grid.nc
2024-03-27 01:26:10,328 - update - model_api - INFO - write_grid.gdal_compliant: False
2024-03-27 01:26:10,328 - update - model_api - INFO - write_grid.rename_dims: False
2024-03-27 01:26:10,328 - update - model_api - INFO - write_grid.force_sn: False
2024-03-27 01:26:10,328 - update - model_api - DEBUG - Writing file grid/grid.nc

The example above means the following: run hydromt update with:

  • grid_model: i.e. update a generic GridModel instance

  • ./tmp_grid_model1: the folder of the to-be updated model

  • ./tmp_grid_model1_update: the folder of the updated model

  • -i ./tmp_grid_model1/grid_model_update.yaml: the hydromt configuration listing the methods to be executed

  • -vv : give some extra verbosity (2 * v) to display feedback on screen. Now debug messages are provided.

[14]:
# note the difference with the original model
print_dir("tmp_grid_model1_update")
tmp_grid_model1_update
 - hydromt.log
tmp_grid_model1_update/grid
 - grid.nc