API — floods, hazard, download

The top-level functions for discovering flood events and hazard layers and fetching their rasters. All are re-exported from euroflood (e.g. euroflood.floods).

The object these return is a FloodFrame.

Discover historic floods

floods

floods(
    region: Any = None,
    *,
    point: tuple[float, float] | None = None,
    radius_m: float = 0.0,
    bbox: tuple[float, float, float, float] | None = None,
    shapefile: str | Path | None = None,
    buffer_m: float = 0.0,
    year: int | None = None,
    start: str | int | None = None,
    end: str | int | None = None,
    level: int | None = None,
    shape: str = "exact",
    output_dir: str | Path | None = None,
    settings: Settings | None = None
) -> FloodFrame

Query historic flood events for a region (cheap; no rasters downloaded).

Parameters:

Name	Type	Description	Default
region	Any	Place name, shapely geometry, GeoDataFrame, or bbox tuple.	None
point	tuple[float, float] | None	A (lat, lon) point; combine with radius_m.	None
radius_m	float	Radius in metres around point.	0.0
bbox	tuple[float, float, float, float] | None	A (minx, miny, maxx, maxy) bounding box (WGS84).	None
shapefile	str | Path | None	Path to a vector file used as the ROI.	None
buffer_m	float	Optional extra metric buffer around the ROI.	0.0
year	int | None	Keep only events in this year.	None
start	str | int | None	Keep events on/after this date ("YYYY" or "YYYY-MM-DD").	None
end	str | int | None	Keep events on/before this date ("YYYY" or "YYYY-MM-DD").	None
level	int | None	Optional NUTS level filter for place-name resolution.	None
shape	str	ROI shape derived from the resolved region — "exact" (default, the raw boundary), "bbox" (its bounding rectangle), or "hull" (its convex hull). Useful when an admin boundary follows a river or is oddly shaped; buffer_m still applies on top of the chosen shape.	'exact'
output_dir	str | Path | None	Directory the cached-download auto-detect scans (defaults to settings.output_dir). Pass the same dir you .download() to so a later query of the same area already carries the files.	None
settings	Settings | None	Optional configuration (e.g. a different cache/index version).	None

Returns:

Name	Type	Description
FloodFrame	FloodFrame	One row per flood event; .download("out/") fetches rasters.

Raises:

Type	Description
GeocodingError	If a place name cannot be resolved.
FileNotFoundError	If no index is available locally and no remote index is configured (run build-index/mirror-index or set index_mode="remote").

Examples:

>>> import euroflood as ef
>>> cat = ef.floods("Zutphen")
>>> recent = cat[cat["date"] >= "2021-01-01"]
>>> recent.download("out/")

Query global flood hazard

hazard

hazard(
    region: Any = None,
    *,
    point: tuple[float, float] | None = None,
    radius_m: float = 0.0,
    bbox: tuple[float, float, float, float] | None = None,
    shapefile: str | Path | None = None,
    buffer_m: float = 0.0,
    return_period: int | list[int] | None = None,
    level: int | None = None,
    shape: str = "exact",
    output_dir: str | Path | None = None,
    settings: Settings | None = None
) -> FloodFrame

Query global flood-hazard maps by return period (CEMS-GLOFAS).

Mirrors floods exactly but takes return_period instead of a time filter. Returns a downloadable FloodFrame with one row per return period; .download("out/") writes one mosaicked, ROI-cropped hazard_RP{rp}.tif per row.

Parameters:

Name	Type	Description	Default
region	Any	Place name, shapely geometry, GeoDataFrame, or bbox tuple.	None
point	tuple[float, float] | None	A (lat, lon) point; combine with radius_m.	None
radius_m	float	Radius in metres around point.	0.0
bbox	tuple[float, float, float, float] | None	A (minx, miny, maxx, maxy) bounding box (WGS84).	None
shapefile	str | Path | None	Path to a vector file used as the ROI.	None
buffer_m	float	Optional extra metric buffer around the ROI.	0.0
return_period	int | list[int] | None	One or more of 10/20/50/75/100/200/500. None returns all available return periods.	None
level	int | None	Optional NUTS level filter for place-name resolution.	None
shape	str	ROI shape derived from the resolved region — "exact" (default, the raw boundary), "bbox" (its bounding rectangle), or "hull" (its convex hull); buffer_m still applies on top.	'exact'
output_dir	str | Path | None	Directory the cached-download auto-detect scans (defaults to settings.output_dir).	None
settings	Settings | None	Optional configuration.	None

Returns:

Name	Type	Description
FloodFrame	FloodFrame	One row per return period; .download("out/") fetches maps.

Raises:

Type	Description
GeocodingError	If a place name cannot be resolved.
HazardError	If the hazard tile index cannot be located or read.

Examples:

>>> import euroflood as ef
>>> ef.hazard("Zutphen", return_period=100).download(
...     "hazard/"
... )
>>> ef.hazard("Zutphen", return_period=[100, 500])

Download rasters

download

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

Download + crop the rasters for a (possibly filtered) catalogue.

The functional equivalent of catalogue.download(...); works on any GeoDataFrame produced by floods or hazard (it routes by the collection column), even after heavy reshaping. Returns the file paths; prefer the download method (returns the catalogue itself) for the fluent, actionable workflow.

Parameters:

Name	Type	Description	Default
catalogue	FloodFrame	A catalogue from floods or hazard, or a filtered subset of one.	required
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 (outputs are otherwise cached and reused).	False
settings	Settings | None	Optional configuration.	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).	None

Returns:

Type	Description
list[Path]	The paths of the written GeoTIFFs — one per historic event, or one
list[Path]	hazard_RP{rp}_{roi}.tif per return period.

Raises:

Type	Description
HazardError	If a hazard mosaic/crop fails.

Examples:

>>> import euroflood as ef
>>> cat = ef.floods("Zutphen")
>>> ef.download(cat[cat["date"] >= "2021-01-01"], "out/")

Mirror hazard tiles

mirror_hazard

mirror_hazard(
    return_period: int | list[int] | None = None,
    *,
    settings: Settings | None = None
) -> int

Download every GLOFAS tile for the given return period(s) into the cache.

A bulk "download everything once" for fast local/offline access: it pre-populates settings.get_hazard_tiles_dir() so subsequent hazard(...).download() runs fully offline (cache hits skip re-downloads). Roughly 1.3 MB x 271 tiles x number of return periods (~350 MB per RP).

Parameters:

Name	Type	Description	Default
return_period	int | list[int] | None	Return period(s) to mirror. None mirrors all supported.	None
settings	Settings | None	Optional configuration. Defaults to get_settings.	None

Returns:

Name	Type	Description
int	int	The number of tiles available locally after the run.

Logging

setup_logging

setup_logging(
    level: str = "INFO",
    *,
    json: bool | None = None,
    stream: TextIO | None = None
) -> None

Configure structured logging for the euroflood logger.

Idempotent: repeated calls reset the handlers rather than stacking them. Only the euroflood logger is configured (with propagate=False), so this never attaches handlers to the root logger or changes the log level of unrelated libraries.

Parameters:

Name	Type	Description	Default
level	str	Log level name (e.g. "INFO", "DEBUG").	'INFO'
json	bool | None	Force JSON rendering (True) or console rendering (False). When None (default), auto-detect at call time: console when the output stream is a TTY, JSON otherwise.	None
stream	TextIO | None	Output stream. Defaults to stderr.	None