Metadata-Version: 2.4
Name: euroflood
Version: 0.1.0
Summary: Processing toolkit for European Satellite-Derived Flood Depth Maps (JRC/CEMS-EFAS): ingest, index, and extract flood data.
Project-URL: Homepage, https://github.com/cisgroup/euroflood
Project-URL: Repository, https://github.com/cisgroup/euroflood
Project-URL: Documentation, https://cisgroup.github.io/euroflood/
Project-URL: Issues, https://github.com/cisgroup/euroflood/issues
Author-email: Jürgen Hackl <hackl@princeton.edu>
License: MIT
License-File: LICENSE
Keywords: CEMS-EFAS,Copernicus,Europe,GLOFAS,Sentinel-1,cloud-optimized geotiff,flood,flood depth,flood risk,geoparquet,geospatial,hydrology,remote sensing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Typing :: Typed
Requires-Python: !=3.14.1,<4.0,>=3.13
Requires-Dist: beautifulsoup4<5.0.0,>=4.14.3
Requires-Dist: click>=8.4.2
Requires-Dist: duckdb<2.0.0,>=1.4.3
Requires-Dist: geopandas>=1.1.3
Requires-Dist: numpy<3.0.0,>=2.4.1
Requires-Dist: pandas<3.0.0,>=2.3.3
Requires-Dist: platformdirs>=4.10.0
Requires-Dist: pooch>=1.8.0
Requires-Dist: pyarrow<24.0.0,>=23.0.0
Requires-Dist: pydantic-settings<3.0.0,>=2.12.0
Requires-Dist: pydantic<3.0.0,>=2.12.5
Requires-Dist: pyproj<4.0,>=3.7
Requires-Dist: rasterio<2.0.0,>=1.5.0
Requires-Dist: requests>=2.34.2
Requires-Dist: rich<15,>=13
Requires-Dist: shapely<3.0.0,>=2.1.2
Requires-Dist: structlog<26.0.0,>=25.5.0
Requires-Dist: tenacity<10.0.0,>=9.1.2
Provides-Extra: publish
Requires-Dist: boto3>=1.35; extra == 'publish'
Requires-Dist: botocore>=1.35; extra == 'publish'
Provides-Extra: viz
Requires-Dist: branca>=0.7; extra == 'viz'
Requires-Dist: contextily>=1.6; extra == 'viz'
Requires-Dist: folium>=0.17; extra == 'viz'
Requires-Dist: ipywidgets>=8; extra == 'viz'
Requires-Dist: matplotlib>=3.9; extra == 'viz'
Description-Content-Type: text/markdown

# EuroFlood

[![CI](https://github.com/cisgroup/euroflood/actions/workflows/ci.yml/badge.svg)](https://github.com/cisgroup/euroflood/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/cisgroup/euroflood/branch/main/graph/badge.svg)](https://codecov.io/gh/cisgroup/euroflood)
[![docs](https://img.shields.io/badge/docs-mkdocs--material-blue)](https://cisgroup.github.io/euroflood/)
[![Python](https://img.shields.io/badge/python-3.13%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/cisgroup/euroflood/blob/main/LICENSE)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

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

<p align="center">
  <a href="https://cisgroup.github.io/euroflood/">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/cisgroup/euroflood/main/docs/images/hero-dark.png">
      <img src="https://raw.githubusercontent.com/cisgroup/euroflood/main/docs/images/hero.png" width="760" alt="EuroFlood — flood-recurrence map of Zutphen on the river IJssel, over a grayscale basemap" />
    </picture>
  </a>
</p>

<p align="center"><em>Flood-recurrence over Zutphen (river IJssel) — how often each ~90&nbsp;m pixel flooded, 2015–2024, straight from the index.</em></p>

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

```bash
pip install euroflood
```

## Quick start

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

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

> New to EuroFlood? Work through the runnable
> **[tutorials](https://cisgroup.github.io/euroflood/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:

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

<p align="center">
  <img src="https://raw.githubusercontent.com/cisgroup/euroflood/main/docs/images/footprints.png" width="45%" alt="Per-event flood extents (footprints)" />
  <img src="https://raw.githubusercontent.com/cisgroup/euroflood/main/docs/images/depth.png" width="45%" alt="Downloaded flood-depth map" />
</p>

See the [Visualize tutorial](https://cisgroup.github.io/euroflood/tutorials/03_visualize/).

## 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](https://cisgroup.github.io/euroflood/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](https://cisgroup.github.io/euroflood/getting-started/) —
  install and run your first query.
- [Tutorials](https://cisgroup.github.io/euroflood/tutorials/) — runnable,
  progressive notebooks (Quickstart → Hazard).
- [Concepts](https://cisgroup.github.io/euroflood/concepts/) — how the index
  works (the data model in one page).
- [API Reference](https://cisgroup.github.io/euroflood/reference/) ·
  [HPC runbook](https://cisgroup.github.io/euroflood/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).

<!-- public-mirror -->
---

_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._
