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 data for offline use

mirror

mirror(
    target: str,
    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,
    year: int | None = None,
    start: str | int | None = None,
    end: str | int | None = None,
    level: int | None = None,
    shape: str = "exact",
    dry_run: bool = False,
    settings: Settings | None = None
) -> MirrorResult | dict[str, MirrorResult]

Stage a data layer for offline/HPC use.

target selects what to mirror into the cache:

"index": the flood catalogue (global; enables offline floods() queries).
"floods": historic flood depth maps for the region (ensures the index).
"hazard": GLOFAS hazard tiles for the region.
"all": index + flood depths + hazard tiles for the region.

region/bbox/point/… scope the region for floods/hazard/all. return_period applies to hazard, year/start/end to floods. Pass dry_run=True to plan without downloading.

Returns:

Type	Description
`MirrorResult \| dict[str, MirrorResult]`	A `MirrorResult` (single target) or a `{layer: MirrorResult}` dict (`"all"`).

Examples:

>>> import euroflood as ef
>>> ef.mirror(
...     "hazard", bbox=(6.1, 52.0, 6.3, 52.2), return_period=100
... )
>>> ef.mirror("all", "Zutphen")

Verify a local mirror

verify

verify(
    target: str,
    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,
    year: int | None = None,
    start: str | int | None = None,
    end: str | int | None = None,
    level: int | None = None,
    shape: str = "exact",
    deep: bool = False,
    settings: Settings | None = None
) -> MirrorReport | dict[str, MirrorReport]

Report local-mirror readiness (present/missing/corrupt) for a data layer.

target mirrors mirror (index/floods/hazard/all). deep re-hashes each file's sha256 against the ledger (slower, catches silent corruption). Returns a MirrorReport (or a {layer: MirrorReport} dict for "all").

Toggle offline mode

offline

offline(enabled: bool = True) -> None

Flip EuroFlood into (or out of) fully-offline mode.

Sets the master offline switch on the global settings, forcing both collections cache-only (the index COG is not streamed, hazard tiles are not fetched) and the geocoder to the local NUTS backend, the programmatic equivalent of EUROFLOOD_OFFLINE=1. Mirror your data first (see mirror).

Examples:

>>> import euroflood as ef
>>> ef.offline()  # this node has no internet
>>> ef.hazard(
...     bbox=(6.1, 52.0, 6.3, 52.2), return_period=100
... ).download()

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`