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
global_data = fetch_data("global-data", output_dir=".")
osm_cache = fetch_data("osmnx") # For quicker build
# For small build data, in this case the region and flood map
build_data = fetch_data("test-build-data", output_dir=".")
# Show the path
sys.stdout.write(f"{global_data.as_posix()}\n")
Untarring contents of '/home/runner/.cache/hydromt_fiat/global-data.tar.gz' to '/home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/global-data'
Downloading file 'osmnx.tar.gz' from 'doi:10.5281/zenodo.17727394/osmnx.tar.gz' to '/home/runner/.cache/hydromt_fiat'.
Untarring contents of '/home/runner/.cache/hydromt_fiat/osmnx.tar.gz' to '/home/runner/.cache/hydromt_fiat/osmnx'
Untarring contents of '/home/runner/.cache/hydromt_fiat/test-build-data.tar.gz' to '/home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/test-build-data'
/home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/global-data
[2]:
71
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(global_data, "data_catalog.yml")) as r:
data = r.read()
print(data)
meta:
version: v2025.2
name: hydromt-fiat_global-data
jrc_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
jrc_curves_link:
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).
jrc_curves_link_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.
jrc_damage:
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
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: exposure/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: exposure/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: exposure/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
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: ./test-build-data/region.geojson
# Setup the vulnerability in one go
- vulnerability.setup:
vulnerability_fname: jrc_curves
vulnerability_linking_fname: jrc_curves_link
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: osm_buildings
exposure_type_column: building
exposure_link_fname: osm_buildings_link
exposure_type_fill: unknown
# Add the maximum damage to it
- exposure_geoms.setup_max_damage:
exposure_name: osm_buildings
exposure_type: damage
exposure_cost_table_fname: jrc_damage
country: World
# Add extra information so Delft-FIAT could run it
- exposure_geoms.update_column:
exposure_name: osm_buildings
columns:
- ref
- method
values:
- 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 ./global-data/data_catalog.yml -d ./test-build-data/data_catalog.yml --fo -v
2025-12-11 10:55:46,142 - hydromt - log - INFO - HydroMT version: 1.2.0
2025-12-11 10:55:46,143 - hydromt.cli.main - main - INFO - Building instance of fiat model at /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/modeldata.
2025-12-11 10:55:46,143 - hydromt.cli.main - main - INFO - User settings:
2025-12-11 10:55:46,202 - hydromt.data_catalog.data_catalog - data_catalog - INFO - Parsing data catalog from ./global-data/data_catalog.yml
2025-12-11 10:55:46,912 - hydromt.data_catalog.data_catalog - data_catalog - INFO - Parsing data catalog from ./test-build-data/data_catalog.yml
2025-12-11 10:55:46,924 - hydromt.model.root - root - INFO - setting root to /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/modeldata
2025-12-11 10:55:46,924 - hydromt.model.model - model - INFO - Initializing fiat model from hydromt_fiat (v1.0.0.dev0).
2025-12-11 10:55:46,925 - hydromt.model.model - model - INFO - build: setup_region
2025-12-11 10:55:46,925 - hydromt.model.model - model - INFO - <bound method FIATModel.setup_region of <hydromt_fiat.fiat.FIATModel object at 0x7fc16d146510>>.replace: False
2025-12-11 10:55:46,925 - hydromt.model.model - model - INFO - <bound method FIATModel.setup_region of <hydromt_fiat.fiat.FIATModel object at 0x7fc16d146510>>.region: ./test-build-data/region.geojson
2025-12-11 10:55:46,925 - hydromt.hydromt_fiat.fiat - fiat - INFO - Setting region from 'test-build-data/region.geojson'
2025-12-11 10:55:46,932 - hydromt.model.model - model - INFO - build: vulnerability.setup
2025-12-11 10:55:46,932 - hydromt.model.model - model - INFO - <bound method VulnerabilityComponent.setup of <hydromt_fiat.components.vulnerability.VulnerabilityComponent object at 0x7fc169ef8d70>>.vulnerability_linking_fname: jrc_curves_link
2025-12-11 10:55:46,932 - hydromt.model.model - model - INFO - <bound method VulnerabilityComponent.setup of <hydromt_fiat.components.vulnerability.VulnerabilityComponent object at 0x7fc169ef8d70>>.unit: m
2025-12-11 10:55:46,932 - hydromt.model.model - model - INFO - <bound method VulnerabilityComponent.setup of <hydromt_fiat.components.vulnerability.VulnerabilityComponent object at 0x7fc169ef8d70>>.index_name: water depth
2025-12-11 10:55:46,932 - hydromt.model.model - model - INFO - <bound method VulnerabilityComponent.setup of <hydromt_fiat.components.vulnerability.VulnerabilityComponent object at 0x7fc169ef8d70>>.vulnerability_fname: jrc_curves
2025-12-11 10:55:46,932 - hydromt.model.model - model - INFO - <bound method VulnerabilityComponent.setup of <hydromt_fiat.components.vulnerability.VulnerabilityComponent object at 0x7fc169ef8d70>>.continent: europe
2025-12-11 10:55:46,932 - hydromt.hydromt_fiat.components.vulnerability - vulnerability - INFO - Setting up the vulnerability curves
2025-12-11 10:55:46,933 - hydromt.data_catalog.drivers.dataframe.pandas_driver - pandas_driver - INFO - Reading using pandas driver from /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/global-data/vulnerability/jrc_damage_functions.csv
2025-12-11 10:55:46,943 - hydromt.data_catalog.drivers.dataframe.pandas_driver - pandas_driver - INFO - Reading using pandas driver from /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/global-data/vulnerability/jrc_damage_functions_linking.csv
2025-12-11 10:55:47,056 - hydromt.model.model - model - INFO - build: hazard.setup
2025-12-11 10:55:47,056 - hydromt.model.model - model - INFO - <bound method HazardComponent.setup of <hydromt_fiat.components.hazard.HazardComponent object at 0x7fc169ef8c20>>.hazard_type: water_depth
2025-12-11 10:55:47,056 - hydromt.model.model - model - INFO - <bound method HazardComponent.setup of <hydromt_fiat.components.hazard.HazardComponent object at 0x7fc169ef8c20>>.return_periods: None
2025-12-11 10:55:47,056 - hydromt.model.model - model - INFO - <bound method HazardComponent.setup of <hydromt_fiat.components.hazard.HazardComponent object at 0x7fc169ef8c20>>.risk: False
2025-12-11 10:55:47,056 - hydromt.model.model - model - INFO - <bound method HazardComponent.setup of <hydromt_fiat.components.hazard.HazardComponent object at 0x7fc169ef8c20>>.unit: m
2025-12-11 10:55:47,056 - hydromt.model.model - model - INFO - <bound method HazardComponent.setup of <hydromt_fiat.components.hazard.HazardComponent object at 0x7fc169ef8c20>>.hazard_fnames: flood_event
2025-12-11 10:55:47,056 - hydromt.hydromt_fiat.components.hazard - hazard - INFO - Setting up hazard raster data
2025-12-11 10:55:47,144 - hydromt.hydromt_fiat.workflows.hazard - hazard - INFO - Added water_depth hazard map: flood_event
2025-12-11 10:55:47,144 - hydromt.hydromt_fiat.workflows.utils - utils - WARNING - No known grid provided to reproject to, defaulting to first specified grid for transform and extent
2025-12-11 10:55:47,149 - hydromt.model.model - model - INFO - build: exposure_geoms.setup
2025-12-11 10:55:47,149 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fc169ef8980>>.exposure_link_fname: osm_buildings_link
2025-12-11 10:55:47,149 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fc169ef8980>>.exposure_type_fill: unknown
2025-12-11 10:55:47,149 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fc169ef8980>>.exposure_fname: osm_buildings
2025-12-11 10:55:47,149 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fc169ef8980>>.exposure_type_column: building
2025-12-11 10:55:47,149 - hydromt.hydromt_fiat.components.exposure_geom - exposure_geom - INFO - Setting up exposure geometries
2025-12-11 10:55:47,150 - hydromt.hydromt_fiat.drivers.osm_driver - osm_driver - INFO - Retrieving building data from OSM API
2025-12-11 10:55:47,525 - hydromt.hydromt_fiat.drivers.osm_driver - osm_driver - INFO - Total number of building found from OSM: 578
2025-12-11 10:55:47,529 - hydromt.data_catalog.drivers.dataframe.pandas_driver - pandas_driver - INFO - Reading using pandas driver from /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/global-data/exposure/osm_buildings-jrc_map.csv
2025-12-11 10:55:47,531 - hydromt.hydromt_fiat.workflows.exposure_geom - exposure_geom - INFO - Setting up the exposure data for further use
2025-12-11 10:55:47,536 - hydromt.hydromt_fiat.workflows.exposure_geom - exposure_geom - INFO - Linking the exposure data with the vulnerability data
2025-12-11 10:55:47,542 - hydromt.hydromt_fiat.components.exposure_geom - exposure_geom - INFO - Setting the model type to 'geom'
2025-12-11 10:55:47,543 - hydromt.model.model - model - INFO - build: exposure_geoms.setup_max_damage
2025-12-11 10:55:47,543 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup_max_damage of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fc169ef8980>>.exposure_cost_link_fname: None
2025-12-11 10:55:47,543 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup_max_damage of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fc169ef8980>>.exposure_name: osm_buildings
2025-12-11 10:55:47,543 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup_max_damage of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fc169ef8980>>.exposure_type: damage
2025-12-11 10:55:47,543 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup_max_damage of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fc169ef8980>>.exposure_cost_table_fname: jrc_damage
2025-12-11 10:55:47,543 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup_max_damage of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fc169ef8980>>.country: World
2025-12-11 10:55:47,543 - hydromt.hydromt_fiat.components.exposure_geom - exposure_geom - INFO - Setting up maximum potential damage for osm_buildings
2025-12-11 10:55:47,543 - hydromt.data_catalog.drivers.dataframe.pandas_driver - pandas_driver - INFO - Reading using pandas driver from /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/global-data/exposure/jrc_damage_values.csv
2025-12-11 10:55:47,558 - hydromt.model.model - model - INFO - build: exposure_geoms.update_column
2025-12-11 10:55:47,558 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.update_column of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fc169ef8980>>.exposure_name: osm_buildings
2025-12-11 10:55:47,558 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.update_column of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fc169ef8980>>.columns: ['ref', 'method']
2025-12-11 10:55:47,558 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.update_column of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fc169ef8980>>.values: [0, 'centroid']
2025-12-11 10:55:47,558 - hydromt.hydromt_fiat.components.exposure_geom - exposure_geom - INFO - Updating exposure data with ['ref', 'method'] columns
2025-12-11 10:55:47,559 - hydromt.hydromt_fiat.components.region - region - INFO - Writing the model region file to /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/modeldata/region.geojson
2025-12-11 10:55:47,561 - hydromt.hydromt_fiat.components.exposure_geom - exposure_geom - INFO - Writing the exposure vector data..
2025-12-11 10:55:47,562 - hydromt.hydromt_fiat.components.exposure_geom - exposure_geom - INFO - Writing the 'osm_buildings' geometry data to /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/modeldata/exposure/osm_buildings.fgb
2025-12-11 10:55:47,570 - hydromt.hydromt_fiat.components.exposure_grid - exposure_grid - INFO - No exposure grid data found, skip writing.
2025-12-11 10:55:47,570 - hydromt.hydromt_fiat.components.hazard - hazard - INFO - Writing the hazard data to /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/modeldata/hazard.nc
2025-12-11 10:55:47,581 - hydromt.hydromt_fiat.components.vulnerability - vulnerability - INFO - Writing the vulnerability data to /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/modeldata/vulnerability/curves.csv
2025-12-11 10:55:47,588 - hydromt.hydromt_fiat.components.config - config - INFO - Writing the config data 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
│ └── osm_buildings.fgb
├── settings.toml
├── vulnerability
│ ├── curves_id.csv
│ └── curves.csv
├── hazard.nc
└── hydromt.log
2 directories, 7 files