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.3.0)
- example_model (hydromt 1.3.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: hydromt build wflow_sbm /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: hydromt build sfincs /path/to/model_root -i
/path/to/sfincs_config.yml -d /path/to/data_catalog.yml -v
Options:
-i, --config PATH Path to hydroMT configuration file, for the model
specific implementation. [required]
-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
2026-01-26 09:30:41,993 - hydromt - log - INFO - HydroMT version: 1.3.0
2026-01-26 09:30:42,049 - hydromt.data_catalog.data_catalog - data_catalog - INFO - Parsing data catalog from ./global-data/data_catalog.yml
2026-01-26 09:30:42,660 - hydromt.data_catalog.data_catalog - data_catalog - INFO - Parsing data catalog from ./test-build-data/data_catalog.yml
2026-01-26 09:30:42,672 - hydromt.model.model - model - INFO - Initializing fiat model from hydromt_fiat (v1.0.0.dev0).
2026-01-26 09:30:42,673 - hydromt - log - INFO - HydroMT version: 1.3.0
2026-01-26 09:30:42,673 - hydromt.model.model - model - INFO - build: setup_region
2026-01-26 09:30:42,673 - hydromt.model.model - model - INFO - setup_region.replace=False
2026-01-26 09:30:42,673 - hydromt.model.model - model - INFO - setup_region.region=/home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/test-build-data/region.geojson
2026-01-26 09:30:42,673 - hydromt.hydromt_fiat.fiat - fiat - INFO - Setting region from '/home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/test-build-data/region.geojson'
2026-01-26 09:30:42,683 - hydromt.model.model - model - INFO - build: vulnerability.setup
2026-01-26 09:30:42,683 - hydromt.model.model - model - INFO - vulnerability.setup.vulnerability_linking_fname=jrc_curves_link
2026-01-26 09:30:42,683 - hydromt.model.model - model - INFO - vulnerability.setup.unit=m
2026-01-26 09:30:42,683 - hydromt.model.model - model - INFO - vulnerability.setup.index_name=water depth
2026-01-26 09:30:42,683 - hydromt.model.model - model - INFO - vulnerability.setup.vulnerability_fname=jrc_curves
2026-01-26 09:30:42,683 - hydromt.model.model - model - INFO - vulnerability.setup.continent=europe
2026-01-26 09:30:42,683 - hydromt.hydromt_fiat.components.vulnerability - vulnerability - INFO - Setting up the vulnerability curves
2026-01-26 09:30:42,683 - hydromt.data_catalog.sources.data_source - data_source - INFO - Reading jrc_curves DataFrame data from /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/global-data/vulnerability/jrc_damage_functions.csv
2026-01-26 09:30:42,701 - hydromt.data_catalog.sources.data_source - data_source - INFO - Reading jrc_curves_link DataFrame data from /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/global-data/vulnerability/jrc_damage_functions_linking.csv
2026-01-26 09:30:42,928 - hydromt.model.model - model - INFO - build: hazard.setup
2026-01-26 09:30:42,928 - hydromt.model.model - model - INFO - hazard.setup.hazard_type=water_depth
2026-01-26 09:30:42,928 - hydromt.model.model - model - INFO - hazard.setup.return_periods=None
2026-01-26 09:30:42,928 - hydromt.model.model - model - INFO - hazard.setup.risk=False
2026-01-26 09:30:42,928 - hydromt.model.model - model - INFO - hazard.setup.unit=m
2026-01-26 09:30:42,928 - hydromt.model.model - model - INFO - hazard.setup.hazard_fnames=flood_event
2026-01-26 09:30:42,928 - hydromt.hydromt_fiat.components.hazard - hazard - INFO - Setting up hazard raster data
2026-01-26 09:30:42,928 - hydromt.data_catalog.sources.data_source - data_source - INFO - Reading flood_event RasterDataset data from /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/test-build-data/floodmaps/event.tif
2026-01-26 09:30:43,012 - hydromt.hydromt_fiat.workflows.hazard - hazard - INFO - Added water_depth hazard map: flood_event
2026-01-26 09:30:43,013 - hydromt.hydromt_fiat.workflows.utils - utils - WARNING - No known grid provided to reproject to, defaulting to first specified grid for transform and extent
2026-01-26 09:30:43,018 - hydromt.model.model - model - INFO - build: exposure_geoms.setup
2026-01-26 09:30:43,018 - hydromt.model.model - model - INFO - exposure_geoms.setup.exposure_link_fname=osm_buildings_link
2026-01-26 09:30:43,018 - hydromt.model.model - model - INFO - exposure_geoms.setup.exposure_type_fill=unknown
2026-01-26 09:30:43,018 - hydromt.model.model - model - INFO - exposure_geoms.setup.exposure_fname=osm_buildings
2026-01-26 09:30:43,018 - hydromt.model.model - model - INFO - exposure_geoms.setup.exposure_type_column=building
2026-01-26 09:30:43,018 - hydromt.hydromt_fiat.components.exposure_geom - exposure_geom - INFO - Setting up exposure geometries
2026-01-26 09:30:43,019 - hydromt.data_catalog.sources.data_source - data_source - INFO - Reading osm_buildings GeoDataFrame data from /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/global-data/building
2026-01-26 09:30:43,019 - hydromt.hydromt_fiat.drivers.osm_driver - osm_driver - INFO - Retrieving building data from OSM API
2026-01-26 09:30:43,513 - hydromt.hydromt_fiat.drivers.osm_driver - osm_driver - INFO - Total number of building found from OSM: 578
2026-01-26 09:30:43,517 - hydromt.data_catalog.sources.data_source - data_source - INFO - Reading osm_buildings_link DataFrame data from /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/global-data/exposure/osm_buildings-jrc_map.csv
2026-01-26 09:30:43,519 - hydromt.hydromt_fiat.workflows.exposure_geom - exposure_geom - INFO - Setting up the exposure data for further use
2026-01-26 09:30:43,527 - hydromt.hydromt_fiat.workflows.exposure_geom - exposure_geom - INFO - Linking the exposure data with the vulnerability data
2026-01-26 09:30:43,537 - hydromt.hydromt_fiat.components.exposure_geom - exposure_geom - INFO - Setting the model type to 'geom'
2026-01-26 09:30:43,537 - hydromt.model.model - model - INFO - build: exposure_geoms.setup_max_damage
2026-01-26 09:30:43,537 - hydromt.model.model - model - INFO - exposure_geoms.setup_max_damage.exposure_cost_link_fname=None
2026-01-26 09:30:43,538 - hydromt.model.model - model - INFO - exposure_geoms.setup_max_damage.exposure_name=osm_buildings
2026-01-26 09:30:43,538 - hydromt.model.model - model - INFO - exposure_geoms.setup_max_damage.exposure_type=damage
2026-01-26 09:30:43,538 - hydromt.model.model - model - INFO - exposure_geoms.setup_max_damage.exposure_cost_table_fname=jrc_damage
2026-01-26 09:30:43,538 - hydromt.model.model - model - INFO - exposure_geoms.setup_max_damage.country=World
2026-01-26 09:30:43,538 - hydromt.hydromt_fiat.components.exposure_geom - exposure_geom - INFO - Setting up maximum potential damage for osm_buildings
2026-01-26 09:30:43,538 - hydromt.data_catalog.sources.data_source - data_source - INFO - Reading jrc_damage DataFrame data from /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/global-data/exposure/jrc_damage_values.csv
2026-01-26 09:30:43,556 - hydromt.model.model - model - INFO - build: exposure_geoms.update_column
2026-01-26 09:30:43,557 - hydromt.model.model - model - INFO - exposure_geoms.update_column.exposure_name=osm_buildings
2026-01-26 09:30:43,557 - hydromt.model.model - model - INFO - exposure_geoms.update_column.columns=['ref', 'method']
2026-01-26 09:30:43,557 - hydromt.model.model - model - INFO - exposure_geoms.update_column.values=[0, 'centroid']
2026-01-26 09:30:43,557 - hydromt.hydromt_fiat.components.exposure_geom - exposure_geom - INFO - Updating exposure data with ['ref', 'method'] columns
2026-01-26 09:30:43,557 - 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
2026-01-26 09:30:43,560 - hydromt.hydromt_fiat.components.exposure_geom - exposure_geom - INFO - Writing the exposure vector data..
2026-01-26 09:30:43,560 - 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
2026-01-26 09:30:43,568 - hydromt.hydromt_fiat.components.exposure_grid - exposure_grid - INFO - No exposure grid data found, skip writing.
2026-01-26 09:30:43,569 - hydromt.hydromt_fiat.components.hazard - hazard - INFO - Writing the hazard data to /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/modeldata/hazard.nc
[########################################] | 100% Completed | 100.53 ms
2026-01-26 09:30:43,679 - 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
2026-01-26 09:30:43,686 - hydromt.hydromt_fiat.components.config - config - INFO - Writing the config data to /home/runner/work/hydromt_fiat/hydromt_fiat/docs/_examples/modeldata/settings.toml
Error in sys.excepthook:
Original exception was:
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