IO

Regions

bathy.list_regions()

List all available preset regions.

Returns:

Type	Description
list[str]	Sorted list of region names

Examples:

>>> from bathy import list_regions
>>> regions = list_regions()
>>> print(regions[:5])
['arabian_sea', 'baltic_sea', 'bay_of_bengal', 'black_sea', 'caribbean']

Source code in src/bathy/io.py

def list_regions() -> list[str]:
    """
    List all available preset regions.

    Returns
    -------
    list[str]
        Sorted list of region names

    Examples
    --------
    >>> from bathy import list_regions
    >>> regions = list_regions()
    >>> print(regions[:5])
    ['arabian_sea', 'baltic_sea', 'bay_of_bengal', 'black_sea', 'caribbean']
    """
    return sorted(REGIONS.keys())

Loading

bathy.load_bathymetry(filepath, lon_range=None, lat_range=None, region=None, var_name='elevation', lon_name='lon', lat_name='lat')

Load bathymetry data from a NetCDF or GeoTIFF file.

Parameters:

Name	Type	Description	Default
filepath	str	Path to the file	required
lon_range	tuple[float, float]	Longitude bounds (min, max). Cannot be used with 'region'.	None
lat_range	tuple[float, float]	Latitude bounds (min, max). Cannot be used with 'region'.	None
region	str	Preset region name. See bathy.list_regions(). Cannot be used with 'lon_range' or 'lat_range'.	None
var_name	str	Variable name	'elevation'
lon_name	str	Longitude coordinate name	'lon'
lat_name	str	Latitude coordinate name	'lat'

Returns:

Type	Description
DataArray	Elevation data with 'lon' and 'lat' coordinates

Examples:

>>> data = load_bathymetry('gebco.nc', lon_range=(-10, -5), lat_range=(50, 55))
>>> data = load_bathymetry('gebco.nc', region='mediterranean')

Source code in src/bathy/io.py

def load_bathymetry(
    filepath: str | Path,
    lon_range: tuple[float, float] | None = None,
    lat_range: tuple[float, float] | None = None,
    region: str | None = None,
    var_name: str = "elevation",
    lon_name: str = "lon",
    lat_name: str = "lat",
) -> xr.DataArray:
    """
    Load bathymetry data from a NetCDF or GeoTIFF file.

    Parameters
    ----------
    filepath : str
        Path to the file
    lon_range : tuple[float, float], optional
        Longitude bounds (min, max). Cannot be used with 'region'.
    lat_range : tuple[float, float], optional
        Latitude bounds (min, max). Cannot be used with 'region'.
    region : str, optional
        Preset region name. See `bathy.list_regions()`.
        Cannot be used with 'lon_range' or 'lat_range'.
    var_name : str, default 'elevation'
        Variable name
    lon_name : str, default 'lon'
        Longitude coordinate name
    lat_name : str, default 'lat'
        Latitude coordinate name

    Returns
    -------
    xr.DataArray
        Elevation data with 'lon' and 'lat' coordinates

    Examples
    --------
    >>> data = load_bathymetry('gebco.nc', lon_range=(-10, -5), lat_range=(50, 55))
    >>> data = load_bathymetry('gebco.nc', region='mediterranean')
    """
    lon_range, lat_range = _resolve_region(lon_range, lat_range, region)

    if not os.path.exists(filepath):
        raise FileNotFoundError(f"File not found: {filepath}")

    ext = os.path.splitext(filepath)[1].lower()
    if ext in [".tif", ".tiff"]:
        return _load_geotiff(filepath, lon_range, lat_range)
    return _load_netcdf(filepath, lon_range, lat_range, var_name, lon_name, lat_name)

bathy.load_emodnet_wcs(lon_range=None, lat_range=None, region=None, save_path=None)

Download bathymetry from the EMODnet Web Coverage Service.

EMODnet provides high-resolution (~115 m) gridded bathymetry for European seas. Coverage is limited to European maritime areas.

Parameters:

Name	Type	Description	Default
lon_range	tuple[float, float]	Longitude bounds (min, max). Cannot be used with 'region'.	None
lat_range	tuple[float, float]	Latitude bounds (min, max). Cannot be used with 'region'.	None
region	str	Preset region name. See bathy.list_regions(). Cannot be used with 'lon_range' or 'lat_range'.	None
save_path	str	If provided, save the downloaded GeoTIFF to this path for reuse. If the file already exists, it is loaded without downloading. If omitted, the data is downloaded to a temporary file that is automatically deleted after loading.	None

Returns:

Type	Description
DataArray	Elevation data with 'lon' and 'lat' coordinates

References

EMODnet Bathymetry Consortium (2024). EMODnet Digital Bathymetry (DTM). https://emodnet.ec.europa.eu/en/bathymetry

Examples:

>>> data = load_emodnet_wcs(lon_range=(-10, -5), lat_range=(50, 55))
>>> data = load_emodnet_wcs(region='north_sea')

Source code in src/bathy/io.py

def load_emodnet_wcs(
    lon_range: tuple[float, float] | None = None,
    lat_range: tuple[float, float] | None = None,
    region: str | None = None,
    save_path: str | None = None,
) -> xr.DataArray:
    """
    Download bathymetry from the EMODnet Web Coverage Service.

    EMODnet provides high-resolution (~115 m) gridded bathymetry for
    European seas. Coverage is limited to European maritime areas.

    Parameters
    ----------
    lon_range : tuple[float, float], optional
        Longitude bounds (min, max). Cannot be used with 'region'.
    lat_range : tuple[float, float], optional
        Latitude bounds (min, max). Cannot be used with 'region'.
    region : str, optional
        Preset region name. See `bathy.list_regions()`.
        Cannot be used with 'lon_range' or 'lat_range'.
    save_path : str, optional
        If provided, save the downloaded GeoTIFF to this path for reuse.
        If the file already exists, it is loaded without downloading.
        If omitted, the data is downloaded to a temporary file that is
        automatically deleted after loading.

    Returns
    -------
    xr.DataArray
        Elevation data with 'lon' and 'lat' coordinates

    References
    ----------
    EMODnet Bathymetry Consortium (2024). EMODnet Digital Bathymetry (DTM).
    https://emodnet.ec.europa.eu/en/bathymetry

    Examples
    --------
    >>> data = load_emodnet_wcs(lon_range=(-10, -5), lat_range=(50, 55))
    >>> data = load_emodnet_wcs(region='north_sea')
    """
    lon_range, lat_range = _resolve_region(
        lon_range, lat_range, region, require_bounds=True
    )

    assert lon_range is not None and lat_range is not None

    if save_path and os.path.exists(save_path):
        logger.info(f"Using existing file: {save_path}")
        filepath = save_path
    else:
        filepath = _download_emodnet(lon_range, lat_range, save_path)

    try:
        return load_bathymetry(filepath)
    finally:
        if save_path is None:
            Path(filepath).unlink(missing_ok=True)

bathy.load_gebco_opendap(lon_range=None, lat_range=None, region=None, year=2025, save_path=None)

Download GEBCO data from OPeNDAP server for a specific region.

Parameters:

Name	Type	Description	Default
lon_range	tuple[float, float]	Longitude bounds (min, max), range: -180 to 180. Cannot be used with 'region'.	None
lat_range	tuple[float, float]	Latitude bounds (min, max), range: -90 to 90. Cannot be used with 'region'.	None
region	str	Preset region name. See bathy.list_regions(). Cannot be used with 'lon_range' or 'lat_range'.	None
year	int	GEBCO dataset year. Valid years: 2019-2025.	2025
save_path	str	If provided, save the downloaded file to this path for reuse. If omitted, the data is downloaded to a temporary file that is automatically deleted after loading.	None

Returns:

Type	Description
DataArray	Elevation data

Notes

Download size scales with the requested area. The full global grid is ~8 GB. For regions larger than ~500 MB, save_path is required to avoid downloading to a temporary file. Large downloads will log a warning with the estimated size.

References

GEBCO Compilation Group (2025) GEBCO 2025 Grid (doi:10.5285/37c52e96-24ea-67ce-e063-7086abc05f29)

Examples:

>>> data = load_gebco_opendap(lon_range=(-10, -5), lat_range=(50, 55))
>>> data = load_gebco_opendap(region='mediterranean')
>>> # Large region — use save_path to keep the file
>>> data = load_gebco_opendap(region='pacific', save_path='pacific.nc')

Source code in src/bathy/io.py

def load_gebco_opendap(
    lon_range: tuple[float, float] | None = None,
    lat_range: tuple[float, float] | None = None,
    region: str | None = None,
    year: int = 2025,
    save_path: str | None = None,
) -> xr.DataArray:
    """
    Download GEBCO data from OPeNDAP server for a specific region.

    Parameters
    ----------
    lon_range : tuple[float, float], optional
        Longitude bounds (min, max), range: -180 to 180.
        Cannot be used with 'region'.
    lat_range : tuple[float, float], optional
        Latitude bounds (min, max), range: -90 to 90.
        Cannot be used with 'region'.
    region : str, optional
        Preset region name. See `bathy.list_regions()`.
        Cannot be used with 'lon_range' or 'lat_range'.
    year : int, default 2025
        GEBCO dataset year. Valid years: 2019-2025.
    save_path : str, optional
        If provided, save the downloaded file to this path for reuse.
        If omitted, the data is downloaded to a temporary file that is
        automatically deleted after loading.

    Returns
    -------
    xr.DataArray
        Elevation data

    Notes
    -----
    Download size scales with the requested area. The full global grid is
    ~8 GB. For regions larger than ~500 MB, ``save_path`` is required to
    avoid downloading to a temporary file. Large downloads will log a
    warning with the estimated size.

    References
    ----------
    GEBCO Compilation Group (2025) GEBCO 2025 Grid
    (doi:10.5285/37c52e96-24ea-67ce-e063-7086abc05f29)

    Examples
    --------
    >>> data = load_gebco_opendap(lon_range=(-10, -5), lat_range=(50, 55))
    >>> data = load_gebco_opendap(region='mediterranean')
    >>> # Large region — use save_path to keep the file
    >>> data = load_gebco_opendap(region='pacific', save_path='pacific.nc')
    """
    lon_range, lat_range = _resolve_region(
        lon_range, lat_range, region, require_bounds=True
    )

    assert lon_range is not None and lat_range is not None

    if save_path and os.path.exists(save_path):
        logger.info(f"Using existing file: {save_path}")
        filepath = save_path
    else:
        filepath = _download_gebco(lon_range, lat_range, year, save_path)

    try:
        return load_bathymetry(filepath)
    finally:
        if save_path is None:
            Path(filepath).unlink(missing_ok=True)

Exporting

bathy.to_geotiff(data, filepath, crs=None, **kwargs)

Save data to a GeoTIFF file.

Parameters:

Name	Type	Description	Default
data	DataArray	Elevation data	required
filepath	str or Path	Output GeoTIFF file path	required
crs	str	Coordinate reference system. Only used when the data has no CRS attached; defaults to "EPSG:4326" for geographic data.	None
**kwargs		Additional arguments passed to rioxarray.to_raster()	{}

Examples:

>>> to_geotiff(data, 'output.tif')

Source code in src/bathy/io.py

def to_geotiff(
    data: xr.DataArray,
    filepath: str | Path,
    crs: str | None = None,
    **kwargs,
) -> None:
    """
    Save data to a GeoTIFF file.

    Parameters
    ----------
    data : xr.DataArray
        Elevation data
    filepath : str or Path
        Output GeoTIFF file path
    crs : str, optional
        Coordinate reference system.  Only used when the data has no CRS
        attached; defaults to ``"EPSG:4326"`` for geographic data.
    **kwargs
        Additional arguments passed to rioxarray.to_raster()

    Examples
    --------
    >>> to_geotiff(data, 'output.tif')
    """
    parent = Path(filepath).parent
    if not parent.exists():
        raise FileNotFoundError(f"Output directory does not exist: {parent}")

    if data.rio.crs is None:
        data = data.rio.write_crs(crs or "EPSG:4326")
    data.rio.to_raster(filepath, **kwargs)