Preparing a model workflow

A user can define a complete pipeline of methods and their options to build a model or updating an existing model in the configuration .yaml file

Steps in brief:

1. Start with a template of the HydroMT model plugin with which you want to build / update a model. Templates can be found in the online documentation of each model plugin.

2. Edit / add / remove sections (i.e. methods) based on which components you want to build or adapt. The arguments of specific methods can be found in the API chapter in the online documentation of each model plugin.

3. Save the configuration file and use it in combination with the HydroMT build and update methods.

Workflow (.yaml) file

The YAML file serves as the configuration and workflow definition for building and updating models in HydroMT. It uses a simple key-value syntax with structured sections to define steps and arguments for each method. Each step corresponds to a model action (method), and arguments specify how that action is applied. The order of execution is determined by the sequence of steps listed in the YAML file.

• Model Type: The top level defines the modeltype, such as “model”.

• Global Components: Under the global section, you can define reusable components that apply throughout the model workflow. Each component is named and has a specific type, like GridComponent or ConfigComponent.

• Steps: The main logic of the model is defined under steps. Each step is a method call, which typically includes the method name and its required arguments. The order of the steps is critical, as HydroMT executes each step sequentially.

Below is an example of the YAML format used in HydroMT:

---
modeltype: model
global:
  components:
    grid:
      type: GridComponent
    config:
      type: ConfigComponent

steps:
  - config.update:
      data:
        header.settings: value
        timers.end: '2010-02-15'
        timers.start: '2010-02-05'

  - grid.create_from_region:
      region:
        bbox: [12.05, 45.30, 12.85, 45.65]
      res: 0.01
      crs: 4326
      basin_index_path: merit_hydro_index
      hydrography_path: merit_hydro

  - grid.add_data_from_constant:
      constant: 0.01
      name: c1
      dtype: float32
      nodata: -99.0

  - grid.add_data_from_rasterdataset:
      raster_data: merit_hydro_1k
      variables:
        - elevtn
        - basins
      reproject_method:
        - average
        - mode

  - grid.add_data_from_rasterdataset:
      raster_data: vito
      fill_method: nearest
      reproject_method: mode
      rename:
        vito: landuse

  - grid.add_data_from_raster_reclass:
      raster_data: vito
      reclass_table_data: vito_reclass
      reclass_variables:
        - manning
      reproject_method:
        - average

  - grid.add_data_from_geodataframe:
      vector_data: hydro_lakes
      variables:
        - waterbody_id
        - Depth_avg
      nodata:
        - -1
        - -999.0
      rasterize_method: value
      rename:
        waterbody_id: lake_id
        Depth_avg: lake_depth

  - grid.add_data_from_geodataframe:
      vector_data: hydro_lakes
      rasterize_method: fraction
      rename:
        hydro_lakes: water_frac

  - write:
      components:
        - config
        - grid

### Explanation of Key Methods

• `config.update`: Updates configuration settings. In the example, it sets parameters like header.settings, and start and end times for the model run.

• `grid.create_from_region`: Creates a grid based on a specified bounding box (bbox), resolution, and coordinate reference system (CRS). Additional options include setting basin and hydrography paths.

• `grid.add_data_from_constant`: Adds a constant value to the grid. Parameters like name, dtype, and nodata specify how the constant data is handled.

• `grid.add_data_from_rasterdataset`: Adds data from a raster dataset. It includes options to specify variables, reprojection methods, and renaming rules for variables.

• `grid.add_data_from_raster_reclass`: Reclassifies raster data based on a specified reclassification table and applies transformations to the grid.

• `grid.add_data_from_geodataframe`: Adds vector data to the grid, rasterizing specific attributes, handling nodata values, and renaming variables.

• `write`: Specifies which components of the model (e.g., config, grid) should be written to disk at the end of the workflow. By default, all files are written unless specified otherwise.

It should be noted that, by default, the HydroMT build and update commands write all output files at the end of the workflow using the write method. This behavior can be customized by explicitly specifying the write step in the YAML file, allowing more granular control over which files are written and when.