depthdamage
Flood damage and risk for buildings and land use from depth-damage curves.
depthdamage turns water depths at assets (or on a land-use grid) into monetary damage
and expected annual damage (EAD):
- Depth-damage curves: piecewise-linear damage fractions, first-floor-height offsets, maximum damage per asset or per square metre, monotonicity and saturation checks, scaling, resampling and running-maximum repair.
- Exposure tables: assets with a curve key, value or area, first-floor height, ground elevation and zone; water-surface levels converted to depths.
- Event sets: one depth row per return period; damage of every event at every asset in one vectorised call.
- EAD: trapezoidal integration of the risk curve with explicit choices for the
protection standard (truncation), a zero-damage return period and the rare-end tail;
p = 1/Tor the Poisson relation. - Risk-curve diagnostics: interval contributions, tail share, dominant interval, non-monotone and few-event warnings, EAD against protection standards.
- Uncertainty: Monte Carlo over curves, asset values, depths and first-floor heights, with EAD percentiles in total and per zone.
- Aggregation: per-zone and per-land-use tables, shares, CSV output.
- Land-use grids: damage and EAD rasters from depth stacks and a class-to-curve map.
- JRC global curves bundled: the 30 average continental damage functions of Huizinga, de Moel & Szewczyk (2017) for residential, commercial, industrial, transport, infrastructure (roads) and agriculture, with their standard deviations.
It needs only NumPy. A command-line tool is included.
The JRC curves are read from the database spreadsheet published with Huizinga et al.
(2017) (JRC105688, sheet "Damage functions", version of 30 October 2017) and shipped as
depthdamage/data/huizinga2017.json: damage fractions at 0, 0.5, 1, 1.5, 2, 3, 4, 5 and
6 m for Europe, North America, Central & South America, Asia, Africa, Oceania and the
global average, where the database has them. The report prints the same curves to two
decimals (Tables 3-1 to 3-20); five of them differ from the spreadsheet (Oceania
residential at 0 m, North America industrial and agriculture, Asia infrastructure and
agriculture), and the spreadsheet values are used. Maximum damage values are not
bundled. Other curves load from CSV or JSON with read_curves; EXAMPLE_CURVE is an
invented shape for demonstrations and tests only.
Installation
pip install depthdamage
Requires Python 3.9 or newer.
Quickstart
import numpy as np
import depthdamage as dd
curves = dd.read_curves("curves.csv") # your curves, long or wide CSV, or JSON
# or the bundled JRC curves: dd.jrc_curve("residential", "europe", max_damage=...),
# dd.jrc_curves(region="europe") -> names "jrc-<sector>-europe"
exposure = dd.Exposure(
asset_id=["a1", "a2", "a3"],
curve=["res", "res", "com"],
value=[250_000, np.nan, 900_000], # NaN -> area * curve.max_damage
area=[np.nan, 140.0, np.nan],
first_floor_height=[0.0, 0.5, 0.2],
zone=["north", "north", "south"],
)
events = dd.EventSet(
return_periods=[10, 100, 1000],
depths=[[0.4, 0.6, 0.0], # one row per event, one column per asset
[1.2, 1.5, 0.7],
[2.1, 2.4, 1.6]],
)
res = dd.assess(exposure, curves, events, protection_rp=30, no_damage_rp=2,
protection_levels=[30, 100], monte_carlo_draws=1000, seed=1,
curve_sd=0.15, value_sigma=0.2)
res.ead # EAD of the whole set
res.asset_ead # per asset
res.zones # per-zone damage per event and EAD
res.risk.to_dict() # points, interval contributions, tail share, issues
res.uncertainty.percentiles() # Monte Carlo EAD percentiles
The building blocks are usable on their own:
c = dd.DepthDamageCurve([0, 0.5, 1, 2, 4], [0, 0.2, 0.4, 0.6, 1.0], name="res",
max_damage=600.0, unit="EUR/m2", source="<your source>")
c.fraction(1.5, first_floor_height=0.3) # fraction at 1.2 m above the floor
c.check() # non-monotone / not saturated warnings
dd.expected_annual_damage([10, 100], [100.0, 1000.0]) # 49.5
dd.expected_annual_damage([10, 100], [100.0, 1000.0], protection_rp=50) # 9.5
dd.expected_annual_damage([10, 100], [100.0, 1000.0], tail="constant") # 59.5
A complete synthetic run is in examples/quickstart.py.
Feature overview
| Area | Functions / classes |
|---|---|
| Curves | DepthDamageCurve (fraction, damage, check, is_monotone, depth_at_fraction, mean_fraction, with_offset, scaled, monotone, resampled), CurveSet, EXAMPLE_CURVE |
| Exposure | Exposure (max_damage, fraction, damage, depth_from_level, subset, summary) |
| Events | EventSet (from_levels, damage), EventDamage (ead, asset_ead, risk_curve, zone_table, asset_table) |
| Risk | expected_annual_damage, risk_curve -> RiskCurve, protection_sensitivity, exceedance_probability, return_period, probability_in_period |
| Uncertainty | monte_carlo -> MonteCarloResult |
| Grids | grid_damage, grid_risk -> GridDamage |
| Aggregation | aggregate, group_table, share_table, write_csv |
| JRC curves | jrc_curve, jrc_curves, jrc_available, JRC_SECTORS, JRC_REGIONS |
| One call | assess -> Assessment (to_dict()) |
| I/O | read_curves, read_curves_csv, read_curves_json, write_curves_csv, write_curves_json, read_exposure_csv, read_risk_csv |
Methods and sources
Relative damage. Damage = fraction(depth - first_floor_height) * max_damage, the
standard relative depth-damage approach (Merz et al. 2010). Curves are linearly
interpolated between tabulated points; below the first point the curve returns below
(default 0) and deeper water is clamped to the last value. Maximum damage is the asset's
own value or area * max_damage per m², as in the per-m² form of Huizinga et al. (2017).
EAD. The risk integral EAD = ∫ D(p) dp is approximated by the trapezoidal rule over
the probability intervals between events,
Σ (D_i + D_{i+1}) / 2 · (p_i − p_{i+1}) (Meyer, Haase & Scheuer 2009). The ends of the
curve are set by explicit options, since these choices change EAD substantially
(Olsen et al. 2015 compare such choices):
| Option | Effect |
|---|---|
no_damage_rp=T0 |
adds a point (1/T0, 0) on the frequent side |
protection_rp=Tp |
events more frequent than Tp cause no damage; the curve starts at 1/Tp with the damage interpolated linearly in p (truncation as in Ward et al. 2013) |
tail="none" |
integration stops at the rarest event |
tail="constant" |
the rarest event's damage is held down to p = 0 (adds D_min · p_min) |
prob="inverse" / "poisson" |
p = 1/T or p = 1 − exp(−1/T) |
The trapezoidal rule is linear in the damages, so per-asset EAD values add up exactly to the EAD of the summed damages for the same options.
Uncertainty. Monte Carlo sampling (de Moel & Aerts 2011 discuss these sources):
curve fractions times a factor N(1, curve_sd) per curve and draw (truncated at 0,
clipped to [0, 1]),
values times a log-normal factor with median 1 and log-sd value_sigma, additive depth
error N(0, depth_sd), additive first-floor error N(0, ffh_sd). All spreads default to
zero; choose them from your own validation data or literature for your region.
Probability over a period. 1 − (1 − 1/T)^n.
Values left to the user
- Maximum damage values, and curves other than the bundled JRC ones.
- All Monte Carlo spreads.
- Protection standards, zero-damage return period and tail choice.
Input files
Curves, long form (curve,depth,fraction[,max_damage,unit,source]) or wide form
(depth,<curve1>,<curve2>,...); --percent / percent=True for tables in percent.
Exposure: one row per asset with id, curve, optional value, area, ffh,
ground, zone, and one depth column per event named depth_T<return period>.
id,curve,value,area,ffh,zone,depth_T10,depth_T100,depth_T1000
a1,res,250000,,0.0,north,0.4,1.2,2.1
a2,res,,140,0.5,north,0.6,1.5,2.4
Command line
depthdamage assess assets.csv --curves curves.csv --protection-rp 30 --no-damage-rp 2 \
--protection-levels 30,100 --mc 1000 --seed 1 --curve-sd 0.15 --value-sigma 0.2 \
--assets-csv assets_ead.csv --zones-csv zones.csv -o report.json
depthdamage ead risk.csv --tail constant # columns return_period,damage
depthdamage curve curves.csv --name res --depths 0.5,1,2 --ffh 0.3 --value 120000
depthdamage check curves.csv --zero-at-ground --strict
depthdamage curve jrc:europe --name jrc-residential-europe --depths 0.25,1.2
depthdamage assess assets.csv --curves jrc:asia # curve column: jrc-<sector>-asia
All commands print JSON (or write it with -o).
Limitations
- Damage depends only on depth; duration, velocity, contamination and warning time are not modelled.
- Linear interpolation in probability between events; with few events EAD is coarse, and the result depends on the closing options above, which should be reported.
- No reprojection or raster reading; pass NumPy arrays.
References
- de Moel, H. & Aerts, J. C. J. H. (2011). Effect of uncertainty in land use, damage models and inundation depth on flood damage estimates. Natural Hazards 58, 407-425.
- Huizinga, J., de Moel, H. & Szewczyk, W. (2017). Global flood depth-damage functions: Methodology and the database with guidelines. JRC Technical Report EUR 28552 EN, Publications Office of the European Union, Luxembourg. https://doi.org/10.2760/16510
- Merz, B., Kreibich, H., Schwarze, R. & Thieken, A. (2010). Review article "Assessment of economic flood damage". Natural Hazards and Earth System Sciences 10, 1697-1724.
- Meyer, V., Haase, D. & Scheuer, S. (2009). Flood risk assessment in European river basins - concept, methods, and challenges exemplified at the Mulde river. Integrated Environmental Assessment and Management 5(1), 17-26.
- Olsen, A. S., Zhou, Q., Linde, J. J. & Arnbjerg-Nielsen, K. (2015). Comparing methods of calculating expected annual damage in urban pluvial flood risk assessments. Water 7(1), 255-270.
- Ward, P. J., Jongman, B., Sperna Weiland, F., Bouwman, A., van Beek, R., Bierkens, M. F. P., Ligtvoet, W. & Winsemius, H. C. (2013). Assessing flood risk at the global scale: model setup, results, and sensitivity. Environmental Research Letters 8, 044019.
Academic citation
@software{eminoglu_depthdamage,
author = {Eminoğlu, Yusuf},
title = {depthdamage},
year = {2026},
version = {0.1.0},
url = {https://gitlab.com/geophilo1/depthdamage_sdk}
}
License
MIT, see LICENSE.
Metadata
Release files for depthdamage 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| depthdamage-0.1.0.tar.gz | 54.2 kB | Without provenance | Details for depthdamage-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| depthdamage-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for depthdamage-0.1.0-py3-none-any.whl |
Total release size: 99.1 kB
Release files / depthdamage-0.1.0.tar.gz
| Download URL | depthdamage-0.1.0.tar.gz |
|---|---|
| Size | 54.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a0a2dd43312d6ce367abb0803fa83f99fe7a7036df92458fc2d13497ca3f757e
|
|
BLAKE2b-256 checksum How to use checksums |
e4c21c9a9d2f2069667f7b21f6502c5e997ed1143ca7dba5eeeb95ba53c49da5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Release files / depthdamage-0.1.0-py3-none-any.whl
| Download URL | depthdamage-0.1.0-py3-none-any.whl |
|---|---|
| Size | 44.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
93b160ee46aa543473996c9bb6d112d9f4327a8204bc8a824c13b32f13cff469
|
|
BLAKE2b-256 checksum How to use checksums |
6ac15b660a15abc7b7bf386047d7554c6565b56e19b2a6f9f4ed06c29a70ab7d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.18
|
Security for depthdamage 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.