Skip to main content

depthdamage

PyPI Python pipeline License: MIT DOI

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/T or 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.1},
  doi     = {10.5281/zenodo.24235560},
  url     = {https://gitlab.com/geophilo1/depthdamage_sdk}
}

License

MIT, see LICENSE.

Metadata

Release files for depthdamage 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for depthdamage 0.1.1
File Size Uploaded Provenance Actions
depthdamage-0.1.1.tar.gz 54.4 kB Without provenance Details for depthdamage-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for depthdamage 0.1.1
File Interpreter ABI Platform Actions
depthdamage-0.1.1-py3-none-any.whl Python 3 none any Details for depthdamage-0.1.1-py3-none-any.whl

Total release size: 99.3 kB

Release files / depthdamage-0.1.1.tar.gz

Download URL depthdamage-0.1.1.tar.gz
Size 54.4 kB
Tags Source
SHA-256 checksum
How to use checksums
f2738bf3eaea3f0622ee14ece54238208eecf3b4334f6bb1687a3328ca1d8082
BLAKE2b-256 checksum
How to use checksums
4d4636aef7dcb0f96d3128dba4ed6174f6a1bc9948a859c7d46e9d85e9562264
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.1-py3-none-any.whl

Download URL depthdamage-0.1.1-py3-none-any.whl
Size 44.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a7ea51be7047f868d9a4db2422678a36d3462ac59b0f5c52f7b8ea299e354e75
BLAKE2b-256 checksum
How to use checksums
411f6bfce3f70b5e594bb9b60429ee76142ec82d62fe4ed62bba776971033fdd
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.1

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page