Metadata-Version: 2.4
Name: depthdamage
Version: 0.1.0
Summary: Flood damage and risk for buildings and land use: depth-damage curves with first-floor heights, multi-return-period event sets, expected annual damage with protection truncation, risk-curve diagnostics, Monte Carlo uncertainty and zone aggregation.
Author-email: Yusuf Eminoğlu <geospacephilo@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/geophilo1/depthdamage_sdk
Project-URL: Repository, https://gitlab.com/geophilo1/depthdamage_sdk
Project-URL: Issues, https://gitlab.com/geophilo1/depthdamage_sdk/-/work_items
Project-URL: Changelog, https://gitlab.com/geophilo1/depthdamage_sdk/-/blob/main/CHANGELOG.md
Keywords: flood,flood-risk,flood-damage,depth-damage,vulnerability,expected-annual-damage,ead,risk-curve,return-period,monte-carlo,exposure,natural-hazards,urban-planning,gis
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# depthdamage

[![PyPI](https://img.shields.io/pypi/v/depthdamage.svg)](https://pypi.org/project/depthdamage/)
[![Python](https://img.shields.io/pypi/pyversions/depthdamage.svg)](https://pypi.org/project/depthdamage/)
[![pipeline](https://gitlab.com/geophilo1/depthdamage_sdk/badges/main/pipeline.svg)](https://gitlab.com/geophilo1/depthdamage_sdk/-/pipelines)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://gitlab.com/geophilo1/depthdamage_sdk/-/blob/main/LICENSE)

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

```bash
pip install depthdamage
```

Requires Python 3.9 or newer.

## Quickstart

```python
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:

```python
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`](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>`.

```csv
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

```bash
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

```bibtex
@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](LICENSE).
