API Reference
Core Module
DamageScanner
DamageScanner - a direct damage assessment toolkit.
This class provides tools to assess direct physical damage from hazard events, using raster or vector exposure data and vulnerability curves. It supports both single-hazard footprints and risk-based multi-scenario assessments.
__init__(hazard_data, feature_data, curves, maxdam)
Initialize the DamageScanner class with hazard, exposure, curve, and max damage data.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
hazard_data
|
str | Path | DataArray | Dataset
|
Path to raster hazard file or xarray object. |
required |
feature_data
|
str | Path | DataFrame | GeoDataFrame | DataArray | Dataset
|
Exposure data, either raster or vector. |
required |
curves
|
str | Path | DataFrame
|
Vulnerability curves as DataFrame or CSV file path. |
required |
maxdam
|
str | Path | DataFrame
|
Maximum damage values per asset type. |
required |
Raises:
| Type | Description |
|---|---|
ImportError
|
If the input data formats are not supported or if required data is missing. |
ImportWarning
|
If the curves or maxdam data is not in the expected format. |
calculate(disable_progress=False, output_path=None, *, object_col='object_type', asset_type=None, multi_curves=None, return_full=True, nan_value=None, cellsize=None, resolution=None, scenario_name=None, in_millions=False, crs=None, transform=None)
Perform a damage calculation using the provided inputs.
Applies vulnerability curves and maximum damage values to the exposed features or raster grid to calculate expected damage.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
disable_progress
|
bool
|
If True, disables progress bars. |
False
|
output_path
|
str | None
|
Path to save the calculation results. The file format is determined by the file extension (e.g., '.csv', '.parquet' for vector data, '.tif' for raster data). If None, the data is not saved. |
None
|
object_col
|
str
|
Column name containing object/landuse types. Defaults to "object_type". (vector only) |
'object_type'
|
asset_type
|
str | None
|
Infrastructure class to evaluate (OSM-based vector only). |
None
|
multi_curves
|
dict | None
|
Mapping of asset types to curve sets. |
None
|
return_full
|
bool
|
Whether to return all features, even those with no hazard intersection. Defaults to True. (vector only) |
True
|
nan_value
|
float | int | None
|
Replace this value in the hazard raster with 0. (raster only) |
None
|
cellsize
|
float | int | None
|
Cell size (m²) if exposure and hazard are arrays. (raster only) |
None
|
resolution
|
float | int | None
|
Resolution in target projection (used for reprojection). (raster only) |
None
|
scenario_name
|
str | None
|
Scenario name used for filenames. (raster only) |
None
|
in_millions
|
bool
|
If True, convert results to millions. (raster only) |
False
|
crs
|
int | None
|
CRS for saving output raster. (raster only) |
None
|
transform
|
Any | None
|
Affine transform for saving raster. (raster only) |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame | tuple[DataFrame, ndarray, ndarray, Dataset | ndarray]
|
For vector: DataFrame with damages. |
DataFrame | tuple[DataFrame, ndarray, ndarray, Dataset | ndarray]
|
For raster: tuple of (damage_df, damagemap, landuse, hazard). |
Raises:
| Type | Description |
|---|---|
ImportError
|
If the input data formats are not supported or if required data is missing. |
ValueError
|
If the geometry type is unsupported or if object types in the data are not found in the curves. |
exposure(disable_progress=False, output_path=None, *, asset_type='landuse', return_full=True)
Run the exposure analysis to identify features affected by the hazard footprint.
This method analyzes the input data to determine which features are exposed to a hazard. It supports both raster and vector data types for the exposure analysis. If the data type is vector, additional keyword arguments can be specified to customize the analysis.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
disable_progress
|
bool
|
If True, disables progress bars during processing. |
False
|
output_path
|
Path | str | None
|
The file path to save the exposure data. The file format is determined by the file extension (e.g., '.parquet', '.csv', '.gpkg', '.shp'). If None, the data is not saved. |
None
|
asset_type
|
str
|
The type of asset to evaluate (only for vector data). |
'landuse'
|
return_full
|
bool
|
Whether to return all features, even those with no hazard intersection. Defaults to True. |
True
|
Returns:
| Type | Description |
|---|---|
GeoDataFrame | DataArray
|
A GeoDataFrame containing the affected assets if the input data is vector, |
GeoDataFrame | DataArray
|
or an xarray.DataArray if the input data is raster. |
Notes
- If
output_pathis provided, the method saves the exposure data to the specified path. - The file format is inferred from the file extension of
output_path. If the extension is not recognized, the data is saved as a Parquet file by default.
Raises:
| Type | Description |
|---|---|
ImportError
|
If the input data formats are not supported or if required data is missing. |
risk(hazard_dict, output_path=None, *, object_col='object_type', asset_type=None, multi_curves=None, return_full=True, nan_value=None, cellsize=None, resolution=None, scenario_name=None, in_millions=False, crs=None, transform=None)
Perform a risk assessment across multiple hazard return periods.
Integrates damages from each return period and computes expected annual damages. Supports both single and multi-curve inputs for infrastructure types.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
hazard_dict
|
dict[int | float, str | Path]
|
Dictionary mapping return periods to hazard raster paths. |
required |
output_path
|
str | None
|
Path to save the risk assessment results. The file format is determined by the file extension (e.g., '.csv', '.parquet'). If None, the data is not saved. |
None
|
object_col
|
str
|
Column name containing object/landuse types. Defaults to "object_type". (vector only) |
'object_type'
|
asset_type
|
str | None
|
Infrastructure class to evaluate (OSM-based vector only). |
None
|
multi_curves
|
dict | None
|
Mapping of asset types to curve sets. |
None
|
return_full
|
bool
|
Whether to return all features, even those with no hazard intersection. Defaults to True. (vector only) |
True
|
nan_value
|
float | int | None
|
Replace this value in the hazard raster with 0. (raster only) |
None
|
cellsize
|
float | int | None
|
Cell size (m²) if exposure and hazard are arrays. (raster only) |
None
|
resolution
|
float | int | None
|
Resolution in target projection (used for reprojection). (raster only) |
None
|
scenario_name
|
str | None
|
Scenario name used for filenames. (raster only) |
None
|
in_millions
|
bool
|
If True, convert results to millions. (raster only) |
False
|
crs
|
int | None
|
CRS for saving output raster. (raster only) |
None
|
transform
|
Any | None
|
Affine transform for saving raster. (raster only) |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame | None
|
A GeoDataFrame with risk values for each asset, or None if no results. |
Vector-based Functions
VectorExposure(hazard_file, feature_file, asset_type='roads', object_col='object_type', hazard_value_col='band_data', disable_progress=False, gridded=True, extract_strategy='raster-sequential', return_full=True)
Load and overlay vector or raster hazard with vector exposure data.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
hazard_file
|
Path | Dataset | DataArray | DatasetReader | GeoDataFrame
|
Hazard input. |
required |
feature_file
|
Path | GeoDataFrame | DataFrame | str
|
Exposure input. |
required |
asset_type
|
str | None
|
Infrastructure category (only for OSM). |
'roads'
|
object_col
|
str
|
Name of the object type column. |
'object_type'
|
hazard_value_col
|
str
|
Column name in vector hazard containing intensity values. |
'band_data'
|
disable_progress
|
bool
|
Whether to suppress progress bars. |
False
|
gridded
|
bool
|
Whether to process in spatial chunks. |
True
|
extract_strategy
|
str
|
exactextract strategy - "feature-sequential" or "raster-sequential". |
'raster-sequential'
|
return_full
|
bool
|
Whether to return all features, even those with no hazard intersection. |
True
|
Returns:
| Name | Type | Description |
|---|---|---|
tuple |
tuple[GeoDataFrame, str, CRS | None, float | None]
|
(features, object_col, hazard_crs, cell_area_m2) |
Raises:
| Type | Description |
|---|---|
ValueError
|
If input files are not in expected formats or if geometry types are unsupported. |
VectorScanner(hazard_file, feature_file, curve_path, maxdam_path=None, asset_type=None, multi_curves=dict(), object_col='object_type', hazard_value_col='band_data', disable_progress=False, gridded=True, extract_strategy='raster-sequential', return_full=True)
Perform vector-based direct damage assessment using hazard and exposure layers.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
hazard_file
|
Path | Dataset | DataArray | GeoDataFrame | str
|
Hazard input. |
required |
feature_file
|
Path | GeoDataFrame | str
|
Exposure input. |
required |
curve_path
|
Path | DataFrame | str
|
Vulnerability curve(s). |
required |
maxdam_path
|
Path | DataFrame | dict | None
|
Maximum damage values. |
None
|
asset_type
|
str | None
|
Infrastructure class (only for OSM). |
None
|
multi_curves
|
dict
|
Multiple curve sets. |
dict()
|
object_col
|
str
|
Column name with object type. |
'object_type'
|
hazard_value_col
|
str
|
Column name in vector hazard containing intensity values. |
'band_data'
|
disable_progress
|
bool
|
Whether to suppress progress bars. |
False
|
gridded
|
bool
|
Whether to process in spatial chunks. |
True
|
extract_strategy
|
str
|
exactextract strategy - "feature-sequential" or "raster-sequential". |
'raster-sequential'
|
return_full
|
bool
|
Whether to return all features, even those with no hazard intersection. |
True
|
Returns:
| Type | Description |
|---|---|
GeoDataFrame
|
Exposure data with calculated damages. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If input files are of unsupported formats or if geometry types are not supported. |
KeyError
|
If object types in exposure are not covered by maximum damage data. |
Raster-based Functions
match_and_load_rasters(raster_in1, raster_in2)
Match and clip two raster files to their common spatial extent and resolution.
Code adapted from http://sciience.tumblr.com/post/101722591382/finding-the-georeferenced-intersection-between-two
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
raster_in1
|
str | Path
|
Path to the first raster file. |
required |
raster_in2
|
str | Path
|
Path to the second raster file. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
tuple |
tuple[ndarray, ndarray, Affine]
|
(data1, data2, transform) - Clipped raster array from the first file. - Clipped raster array from the second file. - Affine transform of the intersecting region. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the rasters have different CRS or resolution. |
RasterScanner(exposure_file, hazard_file, curve_path, maxdam_path, lu_crs=28992, haz_crs=4326, hazard_col='FX', dtype=np.int32, save=False, *, nan_value=None, cellsize=None, resolution=None, output_path=None, scenario_name=None, in_millions=False, crs=None, transform=None)
Run a raster-based direct damage assessment using hazard and exposure layers.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
exposure_file
|
Path | ndarray | str
|
Path to land-use GeoTIFF or numpy array. |
required |
hazard_file
|
Path | ndarray | Dataset | str
|
Path to hazard raster or dataset. |
required |
curve_path
|
Path | DataFrame | ndarray | str
|
Vulnerability curve(s). |
required |
maxdam_path
|
Path | DataFrame | ndarray | str
|
Maximum damage values. |
required |
lu_crs
|
int
|
CRS of the land-use file (default EPSG:28992). |
28992
|
haz_crs
|
int
|
CRS of the hazard file (default EPSG:4326). |
4326
|
hazard_col
|
str
|
Column containing hazard intensity (default "FX"). |
'FX'
|
dtype
|
type
|
Output dtype for damage raster. |
int32
|
save
|
bool
|
If True, saves damage results to file. |
False
|
nan_value
|
float | int | None
|
Replace this value in the hazard raster with 0. |
None
|
cellsize
|
float | int | None
|
Cell size (m²) if exposure and hazard are arrays. |
None
|
resolution
|
float | int | None
|
Resolution in target projection (used for reprojection). |
None
|
output_path
|
str | Path | None
|
Output directory for saving results. |
None
|
scenario_name
|
str | None
|
Scenario name used for filenames. |
None
|
in_millions
|
bool
|
If True, convert results to millions. |
False
|
crs
|
int | None
|
CRS for saving output raster (optional). |
None
|
transform
|
Affine | None
|
Affine transform for saving raster (optional). |
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If cell size is not provided when required. |
ValueError
|
If vulnerability or max damage file has invalid structure. |
Returns:
| Name | Type | Description |
|---|---|---|
tuple |
tuple[DataFrame, ndarray, ndarray, Dataset | ndarray]
|
(damage_df, damagemap, landuse_in, hazard) - Damage per land-use category. - Damage map (grid with estimated damages). - Reprojected land-use map. - Reprojected hazard map. |
OSM Functions
extract(osm_path, geom_type, osm_keys, osm_query)
Extract specific infrastructure features from a .pbf file using OSM keys/values.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
osm_path
|
str | Path
|
Path to .osm.pbf file. |
required |
geom_type
|
str
|
One of 'points', 'lines', 'multipolygons'. |
required |
osm_keys
|
list[str]
|
Keys to extract from OSM file. |
required |
osm_query
|
dict
|
Key-value mapping used to filter. |
required |
Returns:
| Type | Description |
|---|---|
GeoDataFrame
|
Extracted GeoDataFrame with |
read_osm_data(osm_path, asset_type)
Load and extract OSM features for a given critical infrastructure type.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
osm_path
|
str | Path
|
Path to .osm.pbf file. |
required |
asset_type
|
str
|
One of the keys in DICT_CIS_OSM. |
required |
Returns:
| Type | Description |
|---|---|
GeoDataFrame
|
Cleaned and validated exposure GeoDataFrame. |
Raises:
| Type | Description |
|---|---|
ImportWarning
|
If asset_type is not supported. |
extract_first_geom(geom)
Extract the first geometry from a GeometryCollection.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
geom
|
Geometry
|
Shapely geometry object. |
required |
Returns:
| Type | Description |
|---|---|
Geometry
|
First geometry or unchanged object. |
create_point_from_polygon(gdf)
Convert multipolygon geometries into their centroid points.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
gdf
|
GeoDataFrame
|
GeoDataFrame with polygon geometries. |
required |
Returns:
| Type | Description |
|---|---|
GeoDataFrame
|
GeoDataFrame with point geometries instead. |
Download Functions
get_country_geofabrik(iso3, file_format='pbf', save_path=OSM_DATA_DIR, overwrite=False)
Downloads an OSM dataset for a country from Geofabrik.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
iso3
|
str
|
ISO3 country code (e.g., 'NLD'). |
required |
file_format
|
str
|
Either 'pbf' or 'shp'. |
'pbf'
|
save_path
|
str | Path
|
Directory to save the file. |
OSM_DATA_DIR
|
overwrite
|
bool
|
If True, overwrite existing file. |
False
|
Returns:
| Type | Description |
|---|---|
Path
|
The local path to the downloaded file. |
See Also
DICT_GEOFABRIK: ISO3-to-Geofabrik region mapping.
get_region_geofabrik(region, save_path=OSM_DATA_DIR, overwrite=False)
Downloads an OSM dataset for an entire region from Geofabrik.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
region
|
str
|
Name of the region (e.g., 'Europe', 'Africa', 'Asia'). |
required |
save_path
|
str | Path
|
Directory to save the file. |
OSM_DATA_DIR
|
overwrite
|
bool
|
If True, overwrite existing file. |
False
|
Returns:
| Type | Description |
|---|---|
Path
|
The local path to the downloaded file. |
get_planet_file(save_path=Path(OSM_DATA_DIR, 'planet-latest.osm.pbf'), overwrite=False)
Downloads the full OSM planet file (~60 GB) from planet.openstreetmap.org.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
save_path
|
str | Path
|
Destination path for the file. |
Path(OSM_DATA_DIR, 'planet-latest.osm.pbf')
|
overwrite
|
bool
|
If True, overwrite existing file. |
False
|
Returns:
| Type | Description |
|---|---|
Path
|
The local path to the downloaded planet file. |