euroflood 0.1.0

Processing toolkit for European Satellite-Derived Flood Depth Maps (JRC/CEMS-EFAS): ingest, index, and extract flood data.

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 (Betterle & Salamon, 2025) — ~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

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-index pulls the full ~130 MB bundle for fast, fully offline queries.
• Build it yourself: producers can rebuild the index from the source archive (euroflood mirror → 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).
• 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. If you use EuroFlood's data, please cite the source:

Betterle, A. & Salamon, P. (2025). Satellite-Derived Flood Depth Maps for Europe. European Commission, Joint Research Centre (JRC) / Copernicus Emergency Management Service. https://data.jrc.ec.europa.eu/dataset/0bc96690-b89c-4909-9166-c2c322a20130

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.