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")