EuroFlood

Query Europe's observed satellite flood-depth maps by place and time: lightweight, cloud-native, pip-installable.

Flood-recurrence over Zutphen (river IJssel): how often each ~90 m pixel flooded, 2015–2024, straight from the index.

EuroFlood is a data-access tool for the JRC / Copernicus CEMS-EFAS Satellite-Derived Flood Depth Maps for Europe: ~3,280 observed, Sentinel-1-derived flood-depth maps across Europe, 2015–2024. The source is published only as an un-indexed bulk FTP archive; EuroFlood turns it into a queryable index so you can discover which flood events touched a region (and when) and extract only the depth rasters you actually need.

It follows a Discover → Extract model:

• Discover: floods("Zutphen, Netherlands") streams a compact index (a Cloud-Optimized GeoTIFF read a window at a time via /vsicurl, plus a small sorted GeoParquet dictionary cached on first use) and returns a GeoDataFrame of matching flood events, transferring a few MB, never the whole archive.
• Extract: .download("out/") fetches and crops only the source depth GeoTIFFs for the events you selected.

It also exposes the global CEMS-GLOFAS modelled flood-hazard maps via hazard().

Install

pip install euroflood

Quick start

import euroflood as ef

# Discover observed flood events (place name, bbox, point+radius, or a shapefile)
cat = ef.floods("Zutphen, Netherlands")    # -> a GeoDataFrame, one row per event
cat = ef.floods(bbox=(6.14, 52.09, 6.27, 52.17), start=2024, end=2024)

# Extract: download + crop the depth rasters for the selected events
cat[cat["date"] >= "2024-01-01"].download("out/")

# Global modelled hazard (CEMS-GLOFAS return-period depth)
ef.hazard("Zutphen, Netherlands", return_period=100).download("hazard/")

Or from the command line:

euroflood floods "Zutphen, Netherlands"
euroflood hazard "Zutphen, Netherlands" -r 100 --download --out hazard/

New to EuroFlood? Work through the runnable tutorials: Quickstart → Discover & filter → Visualize → Download & measure → Hazard.

Visualize (optional [viz] extra)

pip install "euroflood[viz]" adds plotting: flood-recurrence and per-event footprints straight from the index (no download), plus the downloaded depth maps:

cat = ef.floods("Zutphen, Netherlands")
cat.plot()                                 # flood-recurrence heatmap (shown at the top)
cat.footprints()                           # a GeoDataFrame of each event's extent (+ extent_km2)
cat.explore()                              # interactive map with per-region hover tooltips
cat.head(3).download().plot(depth=True)    # fetch + render the actual depth rasters

A decade at Zutphen: per-cell recurrence, per-event depth, and observed depths against the modelled CEMS-GLOFAS return-period curve (see the case study).

See the Visualize tutorial.

How the data is served

• Zero-config (default): the published index is read remotely: the COG streams via /vsicurl and the ~14 MB dictionary + events table are cached locally on first use (SHA-256-verified). Set EUROFLOOD_INDEX_MODE=local to only ever use a local copy.
• Offline / HPC: euroflood mirror all --bbox <…> -r 100 stages a region's catalogue, flood depth maps, and hazard tiles into the cache (checksum-ledgered; euroflood verify all --deep gates readiness); then EUROFLOOD_OFFLINE=1 runs floods()/hazard() fully offline. Mirror layers independently with mirror index|floods|hazard.
• Build it yourself: producers can rebuild the index from the source archive (euroflood fetch-sources → ingest → build-index); see the HPC runbook.

Place names resolve online-first (OpenStreetMap Nominatim, falling back to an offline Eurostat NUTS dataset); set EUROFLOOD_GEOCODER_BACKEND=local to stay fully offline.

Documentation

Full docs: https://cisgroup.github.io/euroflood/

• Getting Started: install and run your first query.
• Tutorials: runnable, progressive notebooks (Quickstart → Hazard).
• Case studies: real-world flood analyses on genuine events across Europe (Storm Boris, the Valencia DANA, and more).
• Concepts: how the index works (the data model in one page).
• API Reference · HPC runbook

Data source, attribution & license

EuroFlood code is licensed under the MIT License.

The index and the underlying flood-depth maps are derived from the JRC / Copernicus CEMS-EFAS Satellite-Derived Flood Depth Maps for Europe and are licensed CC-BY-4.0.

For how to cite EuroFlood (the software, the index dataset, the source data, and the paper reproduction package), see Citing EuroFlood.

Developed at Princeton University (Complex Infrastructure Systems Group).

This is the public mirror of EuroFlood. Development happens in a separate private repository; each release here is a clean snapshot. Issues and pull requests are welcome — PRs are triaged and applied upstream.