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  # noqa: S101

    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_etopo(lon_range=None, lat_range=None, region=None, resolution='60s', save_path=None)

Download NOAA ETOPO 2022 global relief data.

ETOPO provides integrated topography and bathymetry from NOAA NCEI, widely used by US-based and global researchers.

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
resolution	str	Grid resolution: '60s' (1 arc-minute), '30s', or '15s'.	'60s'
save_path	str	If provided, save the downloaded file to this path for reuse. If the file already exists, it is loaded without downloading.	None

Returns:

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

References

NOAA National Centers for Environmental Information (2022). ETOPO 2022 15 Arc-Second Global Relief Model. https://doi.org/10.25921/fd45-gt74

Examples:

>>> data = load_etopo(lon_range=(-10, -5), lat_range=(50, 55))
>>> data = load_etopo(region='mediterranean', resolution='30s')

Source code in src/bathy/io.py

def load_etopo(
    lon_range: tuple[float, float] | None = None,
    lat_range: tuple[float, float] | None = None,
    region: str | None = None,
    resolution: str = "60s",
    save_path: str | None = None,
) -> xr.DataArray:
    """
    Download NOAA ETOPO 2022 global relief data.

    ETOPO provides integrated topography and bathymetry from NOAA NCEI,
    widely used by US-based and global researchers.

    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'.
    resolution : str, default '60s'
        Grid resolution: '60s' (1 arc-minute), '30s', or '15s'.
    save_path : str, optional
        If provided, save the downloaded file to this path for reuse.
        If the file already exists, it is loaded without downloading.

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

    References
    ----------
    NOAA National Centers for Environmental Information (2022).
    ETOPO 2022 15 Arc-Second Global Relief Model.
    https://doi.org/10.25921/fd45-gt74

    Examples
    --------
    >>> data = load_etopo(lon_range=(-10, -5), lat_range=(50, 55))
    >>> data = load_etopo(region='mediterranean', resolution='30s')
    """
    valid_resolutions = {"60s", "30s", "15s"}
    if resolution not in valid_resolutions:
        raise ValueError(
            f"Invalid resolution: {resolution}. Valid: {sorted(valid_resolutions)}"
        )

    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  # noqa: S101

    if save_path and os.path.exists(save_path):
        logger.info(f"Using existing file: {save_path}")
        return _load_netcdf(save_path, lon_range, lat_range, "z", "lon", "lat")

    opendap_url = (
        f"{_ETOPO_OPENDAP_BASE}/{resolution}/"
        f"{resolution}_surface_elev_netcdf/"
        f"ETOPO_2022_v1_{resolution}_N90W180_surface.nc"
    )

    logger.info(f"Accessing ETOPO 2022 ({resolution}) via OPeNDAP...")

    try:
        with xr.open_dataset(opendap_url, engine="pydap") as ds:
            data = (
                ds["z"]
                .sel(lon=slice(*sorted(lon_range)), lat=slice(*sorted(lat_range)))
                .load()
            )
    except OSError as e:
        raise ConnectionError(
            f"Failed to access ETOPO OPeNDAP server. "
            f"Check your internet connection or try again later. "
            f"URL: {opendap_url}"
        ) from e

    if data.size == 0:
        raise ValueError(
            f"Data selection resulted in empty array. "
            f"Requested: lon={lon_range}, lat={lat_range}."
        )

    if save_path:
        data.to_netcdf(save_path)
        logger.info(f"Saved to {save_path}")

    return data

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  # noqa: S101

    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)

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

Load NOAA Coastal Relief Model (~3 arc-second / ~90 m) via OPeNDAP.

High-resolution bathymetry/topography for US coastal waters. The correct CRM volume is selected automatically based on the requested region.

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 subsetted data as NetCDF for reuse. If the file already exists, it is loaded without fetching.	None

Returns:

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

Notes

Coverage is limited to US coastal waters (10 regional volumes). Requesting a region outside US waters will raise a ValueError.

References

NOAA National Centers for Environmental Information. U.S. Coastal Relief Model. https://www.ngdc.noaa.gov/mgg/coastal/crm.html

Examples:

>>> data = load_noaa_crm(lon_range=(-72, -70), lat_range=(41, 43))
>>> data = load_noaa_crm(region='us_east_coast', save_path='crm.nc')

Source code in src/bathy/io.py

def load_noaa_crm(
    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:
    """
    Load NOAA Coastal Relief Model (~3 arc-second / ~90 m) via OPeNDAP.

    High-resolution bathymetry/topography for US coastal waters. The
    correct CRM volume is selected automatically based on the requested
    region.

    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 subsetted data as NetCDF for reuse.
        If the file already exists, it is loaded without fetching.

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

    Notes
    -----
    Coverage is limited to US coastal waters (10 regional volumes).
    Requesting a region outside US waters will raise a ``ValueError``.

    References
    ----------
    NOAA National Centers for Environmental Information.
    U.S. Coastal Relief Model.
    https://www.ngdc.noaa.gov/mgg/coastal/crm.html

    Examples
    --------
    >>> data = load_noaa_crm(lon_range=(-72, -70), lat_range=(41, 43))
    >>> data = load_noaa_crm(region='us_east_coast', save_path='crm.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  # noqa: S101

    if save_path and os.path.exists(save_path):
        logger.info(f"Using existing file: {save_path}")
        return _load_netcdf(save_path, lon_range, lat_range, "z", "lon", "lat")

    vol = _find_crm_volume(lon_range, lat_range)
    opendap_url = f"https://www.ngdc.noaa.gov/thredds/dodsC/crm/crm_vol{vol}.nc"

    logger.info(f"Accessing NOAA CRM volume {vol} via OPeNDAP...")

    try:
        with xr.open_dataset(opendap_url, engine="pydap") as ds:
            # CRM uses x/y coordinate names (geographic degrees despite the names)
            data = (
                ds["z"]
                .sel(x=slice(*sorted(lon_range)), y=slice(*sorted(lat_range)))
                .load()
            )
    except OSError as e:
        raise ConnectionError(
            f"Failed to access NOAA CRM OPeNDAP server. "
            f"Check your internet connection or try again later. "
            f"URL: {opendap_url}"
        ) from e

    if data.size == 0:
        raise ValueError(
            f"Data selection resulted in empty array. "
            f"Requested: lon={lon_range}, lat={lat_range}. "
            f"CRM volume {vol} may not fully cover this region."
        )

    # Rename x/y → lon/lat to match bathy conventions
    data = data.rename({"x": "lon", "y": "lat"})

    if save_path:
        data.to_netcdf(save_path)
        logger.info(f"Saved to {save_path}")

    return data

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)