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]:
70
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-10 14:25:40,550 - hydromt - log - INFO - HydroMT version: 1.2.0
2025-11-10 14:25:40,550 - hydromt.cli.main - main - INFO - Building instance of fiat model at /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/modeldata.
2025-11-10 14:25:40,551 - hydromt.cli.main - main - INFO - User settings:
2025-11-10 14:25:40,608 - hydromt.data_catalog.data_catalog - data_catalog - INFO - Parsing data catalog from ./build-data/data_catalog.yml
2025-11-10 14:25:41,245 - hydromt.model.root - root - INFO - setting root to /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/modeldata
2025-11-10 14:25:41,246 - hydromt.model.model - model - INFO - Initializing fiat model from hydromt_fiat (v1.0.0.dev0).
2025-11-10 14:25:41,246 - hydromt.model.model - model - INFO - build: setup_region
2025-11-10 14:25:41,246 - hydromt.model.model - model - INFO - <bound method FIATModel.setup_region of <hydromt_fiat.fiat.FIATModel object at 0x7fba70e2c050>>.replace: False
2025-11-10 14:25:41,246 - hydromt.model.model - model - INFO - <bound method FIATModel.setup_region of <hydromt_fiat.fiat.FIATModel object at 0x7fba70e2c050>>.region: ./build-data/region.geojson
2025-11-10 14:25:41,246 - hydromt.hydromt_fiat.fiat - fiat - INFO - Setting region from 'build-data/region.geojson'
2025-11-10 14:25:41,253 - hydromt.model.model - model - INFO - build: vulnerability.setup
2025-11-10 14:25:41,253 - hydromt.model.model - model - INFO - <bound method VulnerabilityComponent.setup of <hydromt_fiat.components.vulnerability.VulnerabilityComponent object at 0x7fba6de30d70>>.vulnerability_linking_fname: vulnerability_curves_linking
2025-11-10 14:25:41,253 - hydromt.model.model - model - INFO - <bound method VulnerabilityComponent.setup of <hydromt_fiat.components.vulnerability.VulnerabilityComponent object at 0x7fba6de30d70>>.unit: m
2025-11-10 14:25:41,253 - hydromt.model.model - model - INFO - <bound method VulnerabilityComponent.setup of <hydromt_fiat.components.vulnerability.VulnerabilityComponent object at 0x7fba6de30d70>>.index_name: water depth
2025-11-10 14:25:41,253 - hydromt.model.model - model - INFO - <bound method VulnerabilityComponent.setup of <hydromt_fiat.components.vulnerability.VulnerabilityComponent object at 0x7fba6de30d70>>.vulnerability_fname: vulnerability_curves
2025-11-10 14:25:41,253 - hydromt.model.model - model - INFO - <bound method VulnerabilityComponent.setup of <hydromt_fiat.components.vulnerability.VulnerabilityComponent object at 0x7fba6de30d70>>.continent: europe
2025-11-10 14:25:41,253 - hydromt.hydromt_fiat.components.vulnerability - vulnerability - INFO - Setting up the vulnerability curves
2025-11-10 14:25:41,254 - 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-10 14:25:41,264 - 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-10 14:25:41,378 - hydromt.model.model - model - INFO - build: hazard.setup
2025-11-10 14:25:41,378 - hydromt.model.model - model - INFO - <bound method HazardComponent.setup of <hydromt_fiat.components.hazard.HazardComponent object at 0x7fba6de30c20>>.hazard_type: water_depth
2025-11-10 14:25:41,378 - hydromt.model.model - model - INFO - <bound method HazardComponent.setup of <hydromt_fiat.components.hazard.HazardComponent object at 0x7fba6de30c20>>.return_periods: None
2025-11-10 14:25:41,378 - hydromt.model.model - model - INFO - <bound method HazardComponent.setup of <hydromt_fiat.components.hazard.HazardComponent object at 0x7fba6de30c20>>.risk: False
2025-11-10 14:25:41,378 - hydromt.model.model - model - INFO - <bound method HazardComponent.setup of <hydromt_fiat.components.hazard.HazardComponent object at 0x7fba6de30c20>>.unit: m
2025-11-10 14:25:41,378 - hydromt.model.model - model - INFO - <bound method HazardComponent.setup of <hydromt_fiat.components.hazard.HazardComponent object at 0x7fba6de30c20>>.hazard_fnames: flood_event
2025-11-10 14:25:41,378 - hydromt.hydromt_fiat.components.hazard - hazard - INFO - Setting up hazard raster data
2025-11-10 14:25:41,463 - hydromt.hydromt_fiat.workflows.hazard - hazard - INFO - Added water_depth hazard map: flood_event
2025-11-10 14:25:41,463 - 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-10 14:25:41,467 - hydromt.model.model - model - INFO - build: exposure_geoms.setup
2025-11-10 14:25:41,467 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fba6de30980>>.exposure_link_fname: buildings_link
2025-11-10 14:25:41,468 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fba6de30980>>.exposure_type_fill: unknown
2025-11-10 14:25:41,468 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fba6de30980>>.exposure_fname: buildings
2025-11-10 14:25:41,468 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fba6de30980>>.exposure_type_column: gebruiksdoel
2025-11-10 14:25:41,468 - hydromt.hydromt_fiat.components.exposure_geom - exposure_geom - INFO - Setting up exposure geometries
2025-11-10 14:25:41,515 - hydromt.data_catalog.drivers.geodataframe.pyogrio_driver - pyogrio_driver - WARNING - Overwriting crs of GeoDataFrame to EPSG:28992
2025-11-10 14:25:41,518 - 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-10 14:25:41,520 - hydromt.hydromt_fiat.workflows.exposure_geom - exposure_geom - INFO - Setting up the exposure data for further use
2025-11-10 14:25:41,525 - hydromt.hydromt_fiat.workflows.exposure_geom - exposure_geom - INFO - Linking the exposure data with the vulnerability data
2025-11-10 14:25:41,531 - hydromt.hydromt_fiat.components.exposure_geom - exposure_geom - WARNING - 'fid' column encountered in buildings, column will be removed
2025-11-10 14:25:41,573 - hydromt.hydromt_fiat.components.exposure_geom - exposure_geom - INFO - Setting the model type to 'geom'
2025-11-10 14:25:41,573 - hydromt.model.model - model - INFO - build: exposure_geoms.setup_max_damage
2025-11-10 14:25:41,574 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup_max_damage of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fba6de30980>>.exposure_cost_link_fname: None
2025-11-10 14:25:41,574 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup_max_damage of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fba6de30980>>.exposure_name: buildings
2025-11-10 14:25:41,574 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup_max_damage of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fba6de30980>>.exposure_type: damage
2025-11-10 14:25:41,574 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup_max_damage of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fba6de30980>>.exposure_cost_table_fname: damage_values
2025-11-10 14:25:41,574 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.setup_max_damage of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fba6de30980>>.country: World
2025-11-10 14:25:41,574 - hydromt.hydromt_fiat.components.exposure_geom - exposure_geom - INFO - Setting up maximum potential damage for buildings
2025-11-10 14:25:41,574 - 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-10 14:25:41,591 - hydromt.model.model - model - INFO - build: exposure_geoms.update_column
2025-11-10 14:25:41,591 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.update_column of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fba6de30980>>.exposure_name: buildings
2025-11-10 14:25:41,591 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.update_column of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fba6de30980>>.columns: ['ground_flht', 'ground_elevtn', 'extract_method']
2025-11-10 14:25:41,591 - hydromt.model.model - model - INFO - <bound method ExposureGeomsComponent.update_column of <hydromt_fiat.components.exposure_geom.ExposureGeomsComponent object at 0x7fba6de30980>>.values: [0, 0, 'centroid']
2025-11-10 14:25:41,591 - hydromt.hydromt_fiat.components.exposure_geom - exposure_geom - INFO - Updating exposure data with ['ground_flht', 'ground_elevtn', 'extract_method'] columns
2025-11-10 14:25:41,592 - hydromt.hydromt_fiat.components.region - region - INFO - Writing the model region file..
2025-11-10 14:25:41,595 - hydromt.hydromt_fiat.components.exposure_geom - exposure_geom - INFO - Writing the exposure vector data..
2025-11-10 14:25:41,595 - 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-10 14:25:41,605 - hydromt.hydromt_fiat.components.exposure_grid - exposure_grid - INFO - No exposure grid data found, skip writing.
2025-11-10 14:25:41,605 - hydromt.hydromt_fiat.components.hazard - hazard - INFO - Writing the hazard data..
2025-11-10 14:25:41,616 - hydromt.hydromt_fiat.components.vulnerability - vulnerability - INFO - Writing the vulnerability tables..
2025-11-10 14:25:41,622 - 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