Add function to fetch Southern Africa topography (#27)

Add new function to Ensaio for fetching and caching a netCDF grid of
Southern Africa topography cropped from full-resolution ETOPO1.

doc/api/index.rst

@@ -19,3 +19,4 @@ List of functions and classes (API)
     ensaio.fetch_osborne_magnetic
     ensaio.fetch_sierra_negra_topography
     ensaio.fetch_southern_africa_gravity
+    ensaio.fetch_southern_africa_topography

doc/gallery_src/southern-africa-topography.py

@@ -0,0 +1,43 @@
+# Copyright (c) 2021 The Ensaio Developers.
+# Distributed under the terms of the BSD 3-Clause License.
+# SPDX-License-Identifier: BSD-3-Clause
+#
+# This code is part of the Fatiando a Terra project (https://www.fatiando.org)
+#
+"""
+Topography and bathymetry of Southern Africa
+--------------------------------------------
+
+This dataset consists in a regular grid with topography and bathymetry over
+Southern Africa. It was generated by cropping the ETOPO1 global topography
+grid to the desired area.
+The topography and bathymetry heights are referenced to sea level (what can be
+considered as the geoid).
+
+**Original source:** `ETOPO1
+<https://doi.org/10.7289/V5C8276M>`__
+
+"""
+import pygmt
+import xarray as xr
+
+import ensaio
+
+###############################################################################
+# Download and cache the data and return the path to it on disk
+fname = ensaio.fetch_southern_africa_topography(version=1)
+print(fname)
+
+###############################################################################
+# Load the netCDF file with xarray (netcdf4 is required)
+data = xr.load_dataarray(fname)
+data
+
+###############################################################################
+# Make a PyGMT map of the topography and bathymetry data
+fig = pygmt.Figure()
+fig.grdimage(data, cmap="etopo1", projection="M15c")
+fig.colorbar(frame='af+l"topography [m]"', position="JCR")
+fig.basemap(frame=True)
+fig.coast(shorelines="0.1p", area_thresh=1e4)
+fig.show()

ensaio/__init__.py

@@ -16,6 +16,7 @@
     fetch_osborne_magnetic,
     fetch_sierra_negra_topography,
     fetch_southern_africa_gravity,
+    fetch_southern_africa_topography,
     locate,
 )
 from ._version import __version__

ensaio/_fetchers.py

@@ -83,6 +83,13 @@
             "url": "https://github.com/fatiando-data/southern-africa-gravity/releases/download/v1",
         },
     },
+    "southern-africa-topography.nc": {
+        "v1": {
+            "hash": "md5:609d14fe4e551c5dcf320cdceedd30e8",
+            "doi": "doi:10.5281/zenodo.6481379",
+            "url": "https://github.com/fatiando-data/southern-africa-topography/releases/download/v1",
+        },
+    },
 }
 
 
@@ -651,3 +658,42 @@ def fetch_southern_africa_gravity(version):
     _check_versions(version, allowed={1}, name="Southern Africa gravity")
     fname = "southern-africa-gravity.csv.xz"
     return Path(_repository(fname, version).fetch(fname))
+
+
+def fetch_southern_africa_topography(version):
+    """
+    Topography and bathymetry data for Southern Africa
+
+    This is a topography and bathymetry grid with a resolution of 1 arc-minute
+    over Southern Africa. The grid was generated by cropping the ETOPO1 global
+    topography grid. The heights are referenced to the mean sea level.
+
+    **Format:** netCDF4 with zlib compression
+
+    **Load with:** :func:`xarray.load_dataarray` (requires the `netcdf4
+    <https://github.com/Unidata/netcdf4-python>`__ library)
+
+    **Original source:** `ETOPO1 <https://doi.org/10.7289/V5C8276M>`__
+
+    **Original license:** Public domain
+
+    **Versions:**
+
+    * `1
+      <https://github.com/fatiando-data/southern-africa-topography/releases/tag/v1>`_
+      (doi:`10.5281/zenodo.6481379 <https://doi.org/10.5281/zenodo.6481379>`__)
+
+    Parameters
+    ----------
+    version : int
+        The data version to fetch. See the available versions above.
+
+    Returns
+    -------
+    fname : :class:`pathlib.Path`
+        Path to the downloaded file on disk.
+
+    """
+    _check_versions(version, allowed={1}, name="Southern Africa topography")
+    fname = "southern-africa-topography.nc"
+    return Path(_repository(fname, version).fetch(fname))