Build Model#

Using the HydroMT cli.#

Here we are going to build a FIAT model using the HydroMT cli.

[1]:

# Lets check out the available HydroMT model
! hydromt --models

Model plugins:
        - model (hydromt 1.2.0)
        - fiat (hydromt_fiat 1.0.0.dev0)

As we can see, the HydroMT-FIAT plugin in installed and ready to be used.
However before we can build a model, we need data to build with.
Besides the data, a configurations file is needed.
This configurations file is provided to the cli and contains the settings for the FIATModel.

Let’s first start with the data.

HydroMT-FIAT comes with a fetch data function to download a small dataset to build with.

[2]:

# Import the function
import sys

from hydromt_fiat.data import fetch_data

# Fetch the building data
data_dir = fetch_data("build-data", output_dir=".")

# Show the path
sys.stdout.write(f"{data_dir.as_posix()}\n")

Untarring contents of '/home/runner/.cache/hydromt_fiat/build-data.tar.gz' to '/home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/build-data'

/home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/build-data

[2]:

The data comes with a data catalog that is understood by HydroMT.
The data catalog contains reference to all the data and how to read them.
Let’s have a look at the contents of the data catalog.

[3]:

from pathlib import Path

# Open the data catalog and print the content to the stdout
with open(Path(data_dir, "data_catalog.yml")) as r:
    data = r.read()
print(data)

meta:
  version: v2025.2
  name: hydromt-fiat_test-data

buildings:
  data_type: GeoDataFrame
  uri: buildings/buildings.fgb
  driver:
    name: pyogrio
    filesystem: local
  metadata:
    crs: 28992
    url: https://service.pdok.nl/lv/bag/atom/bag.xml

buildings_link:
  data_type: DataFrame
  uri: buildings/buildings-jrc_map.csv
  driver:
    name: pandas
    filesystem: local
  metadata:
    notes: Made by dalmijn

commercial_content:
  data_type: RasterDataset
  uri: exposure/commercial_content.tif
  driver:
    name: rasterio
    filesystem: local
    options:
      chunks:
        x: 1500
        y: 1500
  metadata:
    category: exposure
    crs: 28992
    notes: Made by Deltares

commercial_structure:
  data_type: RasterDataset
  uri: exposure/commercial_structure.tif
  driver:
    name: rasterio
    filesystem: local
    options:
      chunks:
        x: 1500
        y: 1500
  metadata:
    category: exposure
    crs: 28992
    notes: Made by Deltares

damage_values:
  data_type: DataFrame
  uri: exposure/jrc_damage_values.csv
  driver:
    name: pandas
    filesystem: local
  metadata:
    category: exposure
    notes: Base damage values from the JRC publicated Excel from the tab "MaxDamage-Data", processed into a handy format for HydroMT-FIAT.
    url: https://publications.jrc.ec.europa.eu/repository/handle/JRC105688
    paper_ref: Huizinga, J., De Moel, H. and Szewczyk, W., Global flood depth-damage functions - Methodology and the database with guidelines, EUR 28552 EN, Publications Office of the European Union, Luxembourg, 2017, ISBN 978-92-79-67781-6, doi:10.2760/16510, JRC105688.
    paper_doi: https://dx.doi.org/10.2760/16510

exposure_grid_link:
  data_type: DataFrame
  uri: exposure/exp-jrc_map.csv
  driver:
    name: pandas
    filesystem: local
  metadata:
    notes: Made by dalmijn

flood_event:
  data_type: RasterDataset
  uri: floodmaps/event.tif
  driver:
    name: rasterio
    filesystem: local
    options:
      chunks:
        x: 1500
        y: 1500
  metadata:
    category: flood maps
    crs: 28992
    notes: Made by Rijkswaterstaat/ Deltares

flood_event_highres:
  data_type: RasterDataset
  uri: floodmaps/event_highres.tif
  driver:
    name: rasterio
    filesystem: local
    options:
      chunks:
        x: 1500
        y: 1500
  metadata:
    category: flood maps
    crs: 28992
    notes: Made by Rijkswaterstaat/ Deltares

industrial_content:
  data_type: RasterDataset
  uri: exposure/industrial_content.tif
  driver:
    name: rasterio
    filesystem: local
    options:
      chunks:
        x: 1500
        y: 1500
  metadata:
    category: exposure
    crs: 28992
    notes: Made by Deltares

industrial_structure:
  data_type: RasterDataset
  uri: exposure/industrial_structure.tif
  driver:
    name: rasterio
    filesystem: local
    options:
      chunks:
        x: 1500
        y: 1500
  metadata:
    category: exposure
    crs: 28992
    notes: Made by Deltares

osm_amenity:
  uri: amenity
  data_type: GeoDataFrame
  uri_resolver: osm_resolver
  driver:
    name: osm
    options:
      geom_type:
        - MultiPolygon
        - Polygon

osm_amenity_link:
  data_type: DataFrame
  uri: buildings/osm_amenity-jrc_map.csv
  driver:
    name: pandas
    filesystem: local
  metadata:
    notes: Made by S. Rautenbach

osm_buildings:
  uri: building
  data_type: GeoDataFrame
  uri_resolver: osm_resolver
  driver:
    name: osm
    options:
      geom_type:
        - MultiPolygon
        - Polygon

osm_buildings_link:
  data_type: DataFrame
  uri: buildings/osm_buildings-jrc_map.csv
  driver:
    name: pandas
    filesystem: local
  metadata:
    notes: Made by S. Rautenbach

osm_landuse:
  uri: landuse
  data_type: GeoDataFrame
  uri_resolver: osm_resolver
  driver:
    name: osm
    options:
      geom_type:
        - MultiPolygon
        - Polygon

osm_landuse_link:
  data_type: DataFrame
  uri: buildings/osm_landuse-jrc_map.csv
  driver:
    name: pandas
    filesystem: local
  metadata:
    notes: Made by S. Rautenbach

osm_roads:
  uri: highway
  data_type: GeoDataFrame
  uri_resolver: osm_resolver
  driver:
    name: osm
    options:
      geom_type:
      - LineString
      - MultiLineString
      tags:
      - motorway
      - primary
      - secondary
      - tertiary

vulnerability_curves:
  data_type: DataFrame
  uri: vulnerability/jrc_damage_functions.csv
  driver:
    name: pandas
    filesystem: local
    options:
      header: null
  metadata:
    category: vulnerability
    notes: JRC depth-damage functions for flooding, processed into a handy format for HydroMT-FIAT.
    url: https://publications.jrc.ec.europa.eu/repository/handle/JRC105688
    paper_ref: Huizinga, J., De Moel, H. and Szewczyk, W., Global flood depth-damage functions - Methodology and the database with guidelines, EUR 28552 EN, Publications Office of the European Union, Luxembourg, 2017, ISBN 978-92-79-67781-6, doi:10.2760/16510, JRC105688.
    paper_doi: https://dx.doi.org/10.2760/16510

vulnerability_curves_linking:
  data_type: DataFrame
  uri: vulnerability/jrc_damage_functions_linking.csv
  driver:
    name: pandas
    filesystem: local
  metadata:
    category: vulnerability
    notes: Default linking table for the JRC damage functions (e.g., the residential damage function links to residential buildings).

vulnerability_curves_linking_alt:
  data_type: DataFrame
  uri: vulnerability/jrc_damage_functions_linking_no_subtype.csv
  driver:
    name: pandas
    filesystem: local
  metadata:
    category: vulnerability
    notes: Same as 'vulnerability_curves_linking' but with no subtyping.

In order to build a model with the HydroMT cli, a build recipe is needed.
This build recipe is made in a yaml format. In this format we define at the very top
‘steps:’ and then add the steps that correspond with the python api, i.e. setup methods
for building the model. An example is shown below.

[4]:

# Open the recipe and print the content to the stdout
with open("./build.yml") as r:
    data = r.read()
print(data)

steps: # Grouping of the steps of the recipe
  # HydroMT-FIAT is highly dependent on a region
  - setup_region:
      region: ./build-data/region.geojson

  # Setup the vulnerability in one go
  - vulnerability.setup:
      vulnerability_fname: vulnerability_curves
      vulnerability_linking_fname: vulnerability_curves_linking
      unit: m
      continent: europe

  # Setup the hazard based on a flood map
  - hazard.setup:
      hazard_fnames: flood_event

  # Setup the exposure based on a vector dataset
  - exposure_geoms.setup:
      exposure_fname: buildings
      exposure_type_column: gebruiksdoel
      exposure_link_fname: buildings_link
      exposure_type_fill: unknown

  # Add the maximum damage to it
  - exposure_geoms.setup_max_damage:
      exposure_name: buildings
      exposure_type: damage
      exposure_cost_table_fname: damage_values
      country: World

  # Add extra information so Delft-FIAT could run it
  - exposure_geoms.update_column:
      exposure_name: buildings
      columns:
        - ground_flht
        - ground_elevtn
        - extract_method
      values:
        - 0
        - 0
        - centroid

Now we have a recipe, we can feed it to the cli of HydroMT.

Let’s have a look at the different build flags of ‘hydromt build’.

[5]:

! 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 -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.
  -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.

We need to specify our model, i.e. ‘fiat’, the path to the directory where out model
will be built, the path to the recipe with the flag ‘-i’ and the path to our
data catalog with the flag ‘-d’. Let’s add some extra verbosity for the logging and
let’s make sure our model is always written with the force overwrite flag ‘–fo’.

[6]:

! hydromt build fiat ./modeldata -i ./build.yml -d ./build-data/data_catalog.yml --fo -v

2025-11-03 12:10:53,424 - hydromt - log - INFO - HydroMT version: 1.2.0
2025-11-03 12:10:53,424 - hydromt.cli.main - main - INFO - Building instance of fiat model at /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/modeldata.
2025-11-03 12:10:53,424 - hydromt.cli.main - main - INFO - User settings:
2025-11-03 12:10:53,483 - hydromt.data_catalog.data_catalog - data_catalog - INFO - Parsing data catalog from ./build-data/data_catalog.yml
2025-11-03 12:10:54,152 - hydromt.model.root - root - INFO - setting root to /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/modeldata
2025-11-03 12:10:54,152 - hydromt.model.model - model - INFO - Initializing fiat model from hydromt_fiat (v1.0.0.dev0).
2025-11-03 12:10:54,153 - hydromt.model.model - model - INFO - build: setup_region
2025-11-03 12:10:54,153 - hydromt.model.model - model - INFO - <bound method FIATModel.setup_region of <hydromt_fiat.fiat.FIATModel object at 0x7fbca6f95fd0>>.replace: False
2025-11-03 12:10:54,153 - hydromt.model.model - model - INFO - <bound method FIATModel.setup_region of <hydromt_fiat.fiat.FIATModel object at 0x7fbca6f95fd0>>.region: ./build-data/region.geojson
2025-11-03 12:10:54,153 - hydromt.hydromt_fiat.fiat - fiat - INFO - Setting region from 'build-data/region.geojson'
2025-11-03 12:10:54,159 - hydromt.model.model - model - INFO - build: vulnerability.setup
2025-11-03 12:10:54,159 - hydromt.model.model - model - INFO - <bound method VulnerabilityComponent.setup of <hydromt_fiat.components.vulnerability.VulnerabilityComponent object at 0x7fbca3ad0ad0>>.vulnerability_linking_fname: vulnerability_curves_linking
2025-11-03 12:10:54,160 - hydromt.model.model - model - INFO - <bound method VulnerabilityComponent.setup of <hydromt_fiat.components.vulnerability.VulnerabilityComponent object at 0x7fbca3ad0ad0>>.unit: m
2025-11-03 12:10:54,160 - hydromt.model.model - model - INFO - <bound method VulnerabilityComponent.setup of <hydromt_fiat.components.vulnerability.VulnerabilityComponent object at 0x7fbca3ad0ad0>>.index_name: water depth
2025-11-03 12:10:54,160 - hydromt.model.model - model - INFO - <bound method VulnerabilityComponent.setup of <hydromt_fiat.components.vulnerability.VulnerabilityComponent object at 0x7fbca3ad0ad0>>.vulnerability_fname: vulnerability_curves
2025-11-03 12:10:54,160 - hydromt.model.model - model - INFO - <bound method VulnerabilityComponent.setup of <hydromt_fiat.components.vulnerability.VulnerabilityComponent object at 0x7fbca3ad0ad0>>.continent: europe
2025-11-03 12:10:54,160 - hydromt.hydromt_fiat.components.vulnerability - vulnerability - INFO - Setting up the vulnerability curves
2025-11-03 12:10:54,160 - hydromt.data_catalog.drivers.dataframe.pandas_driver - pandas_driver - INFO - Reading using pandas driver from /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/build-data/vulnerability/jrc_damage_functions.csv
2025-11-03 12:10:54,170 - hydromt.data_catalog.drivers.dataframe.pandas_driver - pandas_driver - INFO - Reading using pandas driver from /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/build-data/vulnerability/jrc_damage_functions_linking.csv
2025-11-03 12:10:54,284 - hydromt.model.model - model - INFO - build: hazard.setup
2025-11-03 12:10:54,284 - hydromt.model.model - model - INFO - <bound method HazardComponent.setup of <hydromt_fiat.components.hazard.HazardComponent object at 0x7fbca3ad0980>>.hazard_type: water_depth
2025-11-03 12:10:54,284 - hydromt.model.model - model - INFO - <bound method HazardComponent.setup of <hydromt_fiat.components.hazard.HazardComponent object at 0x7fbca3ad0980>>.return_periods: None
2025-11-03 12:10:54,284 - hydromt.model.model - model - INFO - <bound method HazardComponent.setup of <hydromt_fiat.components.hazard.HazardComponent object at 0x7fbca3ad0980>>.risk: False
2025-11-03 12:10:54,284 - hydromt.model.model - model - INFO - <bound method HazardComponent.setup of <hydromt_fiat.components.hazard.HazardComponent object at 0x7fbca3ad0980>>.unit: m
2025-11-03 12:10:54,284 - hydromt.model.model - model - INFO - <bound method HazardComponent.setup of <hydromt_fiat.components.hazard.HazardComponent object at 0x7fbca3ad0980>>.hazard_fnames: flood_event
2025-11-03 12:10:54,284 - hydromt.hydromt_fiat.components.hazard - hazard - INFO - Setting up hazard raster data
2025-11-03 12:10:54,369 - hydromt.hydromt_fiat.workflows.hazard - hazard - INFO - Added water_depth hazard map: flood_event
2025-11-03 12:10:54,370 - hydromt.hydromt_fiat.workflows.utils - utils - WARNING - No known grid provided to reproject to, defaulting to first specified grid for transform and extent
2025-11-03 12:10:54,374 - hydromt.model.model - model - INFO - build: exposure_geoms.setup
2025-11-03 12:10:54,374 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fbca3ad06e0>>.exposure_link_fname: buildings_link
2025-11-03 12:10:54,374 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fbca3ad06e0>>.exposure_type_fill: unknown
2025-11-03 12:10:54,374 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fbca3ad06e0>>.exposure_fname: buildings
2025-11-03 12:10:54,374 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fbca3ad06e0>>.exposure_type_column: gebruiksdoel
2025-11-03 12:10:54,374 - hydromt.hydromt_fiat.components.exposure_geom - exposure_geom - INFO - Setting up exposure geometries
2025-11-03 12:10:54,422 - hydromt.data_catalog.drivers.geodataframe.pyogrio_driver - pyogrio_driver - WARNING - Overwriting crs of GeoDataFrame to EPSG:28992
2025-11-03 12:10:54,425 - hydromt.data_catalog.drivers.dataframe.pandas_driver - pandas_driver - INFO - Reading using pandas driver from /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/build-data/buildings/buildings-jrc_map.csv
2025-11-03 12:10:54,426 - hydromt.hydromt_fiat.workflows.exposure_geom - exposure_geom - INFO - Setting up the exposure data for further use
2025-11-03 12:10:54,431 - hydromt.hydromt_fiat.workflows.exposure_geom - exposure_geom - INFO - Linking the exposure data with the vulnerability data
2025-11-03 12:10:54,438 - hydromt.hydromt_fiat.components.exposure_geom - exposure_geom - WARNING - 'fid' column encountered in buildings, column will be removed
2025-11-03 12:10:54,479 - hydromt.hydromt_fiat.components.exposure_geom - exposure_geom - INFO - Setting the model type to 'geom'
2025-11-03 12:10:54,480 - hydromt.model.model - model - INFO - build: exposure_geoms.setup_max_damage
2025-11-03 12:10:54,480 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup_max_damage of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fbca3ad06e0>>.exposure_cost_link_fname: None
2025-11-03 12:10:54,480 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup_max_damage of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fbca3ad06e0>>.exposure_name: buildings
2025-11-03 12:10:54,480 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup_max_damage of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fbca3ad06e0>>.exposure_type: damage
2025-11-03 12:10:54,480 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup_max_damage of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fbca3ad06e0>>.exposure_cost_table_fname: damage_values
2025-11-03 12:10:54,480 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup_max_damage of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fbca3ad06e0>>.country: World
2025-11-03 12:10:54,480 - hydromt.hydromt_fiat.components.exposure_geom - exposure_geom - INFO - Setting up maximum potential damage for buildings
2025-11-03 12:10:54,480 - hydromt.data_catalog.drivers.dataframe.pandas_driver - pandas_driver - INFO - Reading using pandas driver from /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/build-data/exposure/jrc_damage_values.csv
2025-11-03 12:10:54,498 - hydromt.model.model - model - INFO - build: exposure_geoms.update_column
2025-11-03 12:10:54,498 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.update_column of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fbca3ad06e0>>.exposure_name: buildings
2025-11-03 12:10:54,498 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.update_column of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fbca3ad06e0>>.columns: ['ground_flht', 'ground_elevtn', 'extract_method']
2025-11-03 12:10:54,498 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.update_column of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fbca3ad06e0>>.values: [0, 0, 'centroid']
2025-11-03 12:10:54,498 - hydromt.hydromt_fiat.components.exposure_geom - exposure_geom - INFO - Updating exposure data with ['ground_flht', 'ground_elevtn', 'extract_method'] columns
2025-11-03 12:10:54,499 - hydromt.hydromt_fiat.components.region - region - INFO - Writing the model region file..
2025-11-03 12:10:54,502 - hydromt.hydromt_fiat.components.exposure_geom - exposure_geom - INFO - Writing the exposure vector data..
2025-11-03 12:10:54,502 - hydromt.hydromt_fiat.components.exposure_geom - exposure_geom - INFO - Writing file to /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/modeldata/exposure/buildings.fgb
2025-11-03 12:10:54,512 - hydromt.hydromt_fiat.components.exposure_grid - exposure_grid - INFO - No exposure grid data found, skip writing.
2025-11-03 12:10:54,512 - hydromt.hydromt_fiat.components.hazard - hazard - INFO - Writing the hazard data..
2025-11-03 12:10:54,522 - hydromt.hydromt_fiat.components.vulnerability - vulnerability - INFO - Writing the vulnerability tables..
2025-11-03 12:10:54,528 - hydromt.hydromt_fiat.components.config - config - INFO - Writing the config file to /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/modeldata/settings.toml

It seems like our model built well. Let’s make sure all the necessary files are in

are in our model directory.

[7]:

from hydromt_fiat.utils import directory_tree

# Print the modeldata directory as a tree
directory_tree("./modeldata")

modeldata
├── region.geojson
├── exposure
│   └── buildings.fgb
├── settings.toml
├── vulnerability
│   ├── curves_id.csv
│   └── curves.csv
├── hazard.nc
└── hydromt.log

2 directories, 7 files

Build Model#

Using the HydroMT cli.#

This Page