FloodFrame

FloodFrame is what floods() and hazard() return — a thin geopandas.GeoDataFrame subclass (so all pandas/geopandas operations work) with a few convenience methods for downloading and visualizing the catalogue.

FloodFrame

Bases: GeoDataFrame

A GeoDataFrame of flood events with a convenience .download() method.

It is a plain geopandas.GeoDataFrame — filtering, stats, plotting and to_parquet all work as usual. The only addition is download, so floods(...).download("out/") and cat[cat.year == 2021].download("out/") both work. Use the functional download_catalogue if a heavy reshape ever degrades the object back to a plain GeoDataFrame.

Methods:

Name	Description
download	Download + crop the rasters for these rows, and remember them.
depths	Downloaded rasters as DepthRaster objects.
stats	Per-event depth statistics for the downloaded rasters.
summary	Aggregate (envelope) depth statistics across the downloaded rasters.
plot	Plot this catalogue (static, matplotlib). Requires euroflood[viz].
explore	Interactive map of this catalogue (folium). See plot.
footprints	Per-event flood extents from the index (one geometry per event).

Attributes:

Name	Type	Description
files	list[Path]	Paths of the downloaded rasters for the rows in this frame (may be empty).

Attributes

files property

files: list[Path]

Paths of the downloaded rasters for the rows in this frame (may be empty).

Methods:

download

download(
    output_dir: str | Path | None = None,
    *,
    crop: bool = True,
    force: bool = False,
    settings: Settings | None = None,
    on_bytes: Callable[[int], None] | None = None
) -> FloodFrame

Download + crop the rasters for these rows, and remember them.

Routes by collection (see _dispatch_download), so a hazard catalogue fetches+mosaics+crops while a historic one downloads one file per event — both via the same .download(). Cropped outputs are cached: a re-run reuses existing files (nothing re-downloaded) unless force=True.

Returns the catalogue itself, now carrying a path column, so the result is actionable — cat = ef.floods("Zutphen").download() then cat.plot(depth=True) / cat.stats() all reuse the downloaded rasters. The written paths are available via files.

Parameters:

Name	Type	Description	Default
output_dir	str | Path | None	Directory for the written GeoTIFFs. Defaults to settings.output_dir.	None
crop	bool	If True (default), crop each raster to the ROI polygon.	True
force	bool	Re-download + re-crop even if the output already exists.	False
settings	Settings | None	Optional configuration (defaults to the frame's own settings).	None
on_bytes	Callable[[int], None] | None	Optional progress callback (n_bytes) -> None per downloaded chunk (the CLI uses it to drive a progress bar; library callers can pass their own).	None

Returns:

Type	Description
FloodFrame	This FloodFrame, with a path column populated for the rows
FloodFrame	whose rasters were written (None where a row produced no raster).

Examples:

>>> import euroflood as ef
>>> cat = ef.floods("Zutphen").download("out/")
>>> cat.files  # the downloaded GeoTIFFs

depths

depths() -> list[Any]

Downloaded rasters as DepthRaster objects.

So ef.floods("Zutphen").download().depths()[0].plot() works. Requires euroflood[viz]. Returns an empty list if nothing has been downloaded.

stats

stats(*, scale: float | None = None) -> Any

Per-event depth statistics for the downloaded rasters.

One row per downloaded event: max/mean/p95 depth (m), flooded area (km²), water volume (m³ and million-m³), and wet-pixel count. Reads only rasters a prior download fetched — no network I/O.

Parameters:

Name	Type	Description	Default
scale	float | None	Raster-value→metre multiplier. None (default) picks it from the catalogue kind — EFAS historic depth is centimetres (0.01), GLOFAS hazard depth is already metres (1.0). Pass a value to override.	None

Returns:

Type	Description
Any	A pandas.DataFrame of per-event statistics.

Raises:

Type	Description
ProcessingError	If nothing has been downloaded (call download).

Examples:

>>> import euroflood as ef
>>> ef.floods("Zutphen").download().stats()

summary

summary(*, scale: float | None = None) -> dict[str, float]

Aggregate (envelope) depth statistics across the downloaded rasters.

Combines the downloaded rasters into a per-pixel maximum composite and summarizes it, so overlapping events are not double-counted: overall max depth, union flooded area (km²), and envelope water volume. Reads only already-downloaded rasters.

Parameters:

Name	Type	Description	Default
scale	float | None	Raster-value→metre multiplier; None (default) infers it from the catalogue kind (see stats).	None

Returns:

Type	Description
dict[str, float]	A dict of headline numbers (max_depth_m, flooded_area_km2,
dict[str, float]	volume_m3, volume_Mm3, ...).

Raises:

Type	Description
ProcessingError	If nothing has been downloaded (call download).

plot

plot(*, geo: bool = False, **kwargs: Any) -> Any

Plot this catalogue (static, matplotlib). Requires euroflood[viz].

The default is the flood-recurrence heatmap over the query ROI — cheap, no download.

Parameters:

Name	Type	Description	Default
geo	bool	If True, fall back to the raw geopandas plot of the catalogue geometry instead of the recurrence view.	False
**kwargs	Any	Passed through to the renderer. Notably depth=True (download + render the depth raster, guarded by a row cap), footprints=True (per-event extents), event_id= (a single event's footprint), and boundary=False.	{}

Returns:

Type	Description
Any	A matplotlib.axes.Axes.

Raises:

Type	Description
ImportError	If the viz extra is not installed.
VisualizationError	For an empty catalogue, or the recurrence view on a hazard catalogue (no combo index).

Examples:

>>> import euroflood as ef
>>> ef.floods("Zutphen").plot()  # recurrence heatmap
>>> ef.floods("Zutphen").plot(footprints=True)

explore

explore(*, geo: bool = False, **kwargs: Any) -> Any

Interactive map of this catalogue (folium). See plot.

Recurrence regions carry hover tooltips listing which floods hit each area and when. Requires euroflood[viz].

Parameters:

Name	Type	Description	Default
geo	bool	If True, fall back to the raw geopandas .explore() of the catalogue geometry.	False
**kwargs	Any	Passed through to the renderer (depth=, footprints=, event_id=, boundary=, backend=).	{}

Returns:

Type	Description
Any	A folium.Map.

Raises:

Type	Description
ImportError	If the viz extra is not installed.
VisualizationError	For an empty/hazard catalogue on the recurrence view.

footprints

footprints() -> Any

Per-event flood extents from the index (one geometry per event).

Replaces the catalogue's shared ROI geometry with each event's actual footprint (derived from the index — no download) and adds an extent_km2 column, so the result is a normal GeoDataFrame you can plot, explore, to_file, or measure. Requires euroflood[viz].

Returns:

Type	Description
Any	A plain geopandas.GeoDataFrame (EPSG:4326) with the catalogue's
Any	metadata, a per-event geometry, and extent_km2.

Raises:

Type	Description
VisualizationError	For an empty or hazard catalogue (no combo index).

Examples:

>>> import euroflood as ef
>>> ext = ef.floods("Zutphen").footprints()
>>> ext.to_file("extents.geojson")