Merge branch 'main' into add-remote-earth-mdt

yvonnefroehlich · web-flow · commit ce979dbe7b33 · 2024-12-26T09:39:40.000+01:00
diff --git a/.github/ISSUE_TEMPLATE/4-release_checklist.md b/.github/ISSUE_TEMPLATE/4-release_checklist.md
@@ -1,6 +1,6 @@
 ---
 name: PyGMT release checklist
-about: Checklist for a new PyGMT release.
+about: Checklist for a new PyGMT release. [For project maintainers only!]
 title: Release PyGMT vX.Y.Z
 labels: maintenance
 assignees: ''
diff --git a/.github/ISSUE_TEMPLATE/5-bump_gmt_checklist.md b/.github/ISSUE_TEMPLATE/5-bump_gmt_checklist.md
@@ -1,6 +1,6 @@
 ---
 name: Bump GMT version checklist
-about: Checklist for bumping the minimum required GMT version.
+about: Checklist for bumping the minimum required GMT version. [For project maintainers only!]
 title: Bump to GMT X.Y.Z
 labels: maintenance
 assignees: ''
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -20,7 +20,6 @@ Fixes #
 - [ ] Write detailed docstrings for all functions/methods.
 - [ ] If wrapping a new module, open a 'Wrap new GMT module' issue and submit reasonably-sized PRs.
 - [ ] If adding new functionality, add an example to docstrings or tutorials.
-- [ ] Use underscores (not hyphens) in names of Python files and directories.
 
 **Slash Commands**
 
diff --git a/.github/workflows/ci_tests.yaml b/.github/workflows/ci_tests.yaml
@@ -187,7 +187,7 @@ jobs:
 
       # Upload coverage to Codecov
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v5.1.1
+        uses: codecov/codecov-action@v5.1.2
         if: success() || failure()
         with:
           use_oidc: true
diff --git a/.github/workflows/format-command.yml b/.github/workflows/format-command.yml
@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       # Generate token from GenericMappingTools bot
-      - uses: actions/create-github-app-token@v1.11.0
+      - uses: actions/create-github-app-token@v1.11.1
         id: generate-token
         with:
           app-id: ${{ secrets.APP_ID }}
diff --git a/.github/workflows/style_checks.yaml b/.github/workflows/style_checks.yaml
@@ -52,3 +52,15 @@ jobs:
             rm output.txt
             exit $nfiles
           fi
+
+      - name: Ensure hyphens are not used in names of directories and Python files
+        run: |
+          git ls-files '*.py' | grep '-' > output.txt || true
+          git ls-tree -rd --name-only HEAD | grep '-' >> output.txt || true
+          nfiles=$(wc --lines output.txt | awk '{print $1}')
+          if [[ $nfiles > 0 ]]; then
+            echo "Following directories/files use hyphens in file names:"
+            cat output.txt
+            rm output.txt
+            exit $nfiles
+          fi
diff --git a/doc/api/index.rst b/doc/api/index.rst
@@ -233,6 +233,7 @@ and store them in GMT's user data directory.
     datasets.load_black_marble
     datasets.load_blue_marble
     datasets.load_earth_age
+    datasets.load_earth_dist
     datasets.load_earth_free_air_anomaly
     datasets.load_earth_geoid
     datasets.load_earth_magnetic_anomaly
diff --git a/doc/contributing.md b/doc/contributing.md
@@ -130,9 +130,9 @@ our tests. This way, the *main* branch is always stable.
     integrated separately.
   - Bug fixes should be submitted in separate PRs.
 * How to write and submit a PR
-  - Use underscores for all Python (*.py) files as per
-    [PEP8](https://www.python.org/dev/peps/pep-0008/), not hyphens. Directory
-    names should also use underscores instead of hyphens.
+  - Use underscores for all Python (\*.py) files as per
+    [PEP8](https://www.python.org/dev/peps/pep-0008/), not hyphens. Directory names
+    should also use underscores instead of hyphens.
   - Describe what your PR changes and *why* this is a good thing. Be as
     specific as you can. The PR description is how we keep track of the changes
     made to the project over time.
diff --git a/doc/external_resources.md b/doc/external_resources.md
@@ -13,7 +13,7 @@ to submit a pull request with your recommended addition to the
 :::::{grid} 1 2 2 3
 
 ::::{grid-item-card} 2024 AGU PREWS9: Mastering Geospatial Visualizations with GMT/PyGMT
-:link: https://github.com/GenericMappingTools/agu24workshop
+:link: https://www.generic-mapping-tools.org/agu24workshop/
 :text-align: center
 :margin: 0 3 0 0
 
diff --git a/pygmt/datasets/__init__.py b/pygmt/datasets/__init__.py
@@ -6,6 +6,7 @@
 
 from pygmt.datasets.earth_age import load_earth_age
 from pygmt.datasets.earth_day import load_blue_marble
+from pygmt.datasets.earth_dist import load_earth_dist
 from pygmt.datasets.earth_free_air_anomaly import load_earth_free_air_anomaly
 from pygmt.datasets.earth_geoid import load_earth_geoid
 from pygmt.datasets.earth_magnetic_anomaly import load_earth_magnetic_anomaly
diff --git a/pygmt/datasets/earth_dist.py b/pygmt/datasets/earth_dist.py
@@ -0,0 +1,105 @@
+"""
+Function to download the GSHHG Earth distance to shoreline dataset from the GMT data
+server, and load as :class:`xarray.DataArray`.
+
+The grids are available in various resolutions.
+"""
+
+from collections.abc import Sequence
+from typing import Literal
+
+import xarray as xr
+from pygmt.datasets.load_remote_dataset import _load_remote_dataset
+
+__doctest_skip__ = ["load_earth_dist"]
+
+
+def load_earth_dist(
+    resolution: Literal[
+        "01d", "30m", "20m", "15m", "10m", "06m", "05m", "04m", "03m", "02m", "01m"
+    ] = "01d",
+    region: Sequence[float] | str | None = None,
+    registration: Literal["gridline", "pixel"] = "gridline",
+) -> xr.DataArray:
+    r"""
+    Load the GSHHG Earth distance to shoreline dataset in various resolutions.
+
+    .. figure:: https://www.generic-mapping-tools.org/remote-datasets/_images/GMT_earth_dist.jpg
+       :width: 80 %
+       :align: center
+
+       GSHHG Earth distance to shoreline dataset.
+
+    The grids are downloaded to a user data directory (usually
+    ``~/.gmt/server/earth/earth_dist/``) the first time you invoke this function.
+    Afterwards, it will load the grid from the data directory. So you'll need an
+    internet connection the first time around.
+
+    These grids can also be accessed by passing in the file name
+    **@earth_dist**\_\ *res*\[_\ *reg*] to any grid processing function or plotting
+    method. *res* is the grid resolution (see below), and *reg* is the grid registration
+    type (**p** for pixel registration or **g** for gridline registration).
+
+    The default color palette table (CPT) for this dataset is *@earth_dist.cpt*. It's
+    implicitly used when passing in the file name of the dataset to any grid plotting
+    method if no CPT is explicitly specified. When the dataset is loaded and plotted
+    as an :class:`xarray.DataArray` object, the default CPT is ignored, and GMT's
+    default CPT (*turbo*) is used. To use the dataset-specific CPT, you need to
+    explicitly set ``cmap="@earth_dist.cpt"``.
+
+    Refer to :gmt-datasets:`earth-dist.html` for more details about available datasets,
+    including version information and references.
+
+    Parameters
+    ----------
+    resolution
+        The grid resolution. The suffix ``d`` and ``m`` stand for arc-degrees and
+        arc-minutes.
+    region
+        The subregion of the grid to load, in the form of a sequence [*xmin*, *xmax*,
+        *ymin*, *ymax*] or an ISO country code. Required for grids with resolutions
+        higher than 5 arc-minutes (i.e., ``"05m"``).
+    registration
+        Grid registration type. Either ``"pixel"`` for pixel registration or
+        ``"gridline"`` for gridline registration.
+
+    Returns
+    -------
+    grid
+        The GSHHG Earth distance to shoreline grid. Coordinates are latitude and
+        longitude in degrees. Distances are in kilometers, where positive (negative)
+        values mean land to coastline (ocean to coastline).
+
+    Note
+    ----
+    The registration and coordinate system type of the returned
+    :class:`xarray.DataArray` grid can be accessed via the GMT accessors (i.e.,
+    ``grid.gmt.registration`` and ``grid.gmt.gtype`` respectively). However, these
+    properties may be lost after specific grid operations (such as slicing) and will
+    need to be manually set before passing the grid to any PyGMT data processing or
+    plotting functions. Refer to :class:`pygmt.GMTDataArrayAccessor` for detailed
+    explanations and workarounds.
+
+    Examples
+    --------
+
+    >>> from pygmt.datasets import load_earth_dist
+    >>> # load the default grid (gridline-registered 1 arc-degree grid)
+    >>> grid = load_earth_dist()
+    >>> # load the 30 arc-minutes grid with "gridline" registration
+    >>> grid = load_earth_dist(resolution="30m", registration="gridline")
+    >>> # load high-resolution (5 arc-minutes) grid for a specific region
+    >>> grid = load_earth_dist(
+    ...     resolution="05m",
+    ...     region=[120, 160, 30, 60],
+    ...     registration="gridline",
+    ... )
+    """
+    grid = _load_remote_dataset(
+        name="earth_dist",
+        prefix="earth_dist",
+        resolution=resolution,
+        region=region,
+        registration=registration,
+    )
+    return grid
diff --git a/pygmt/datasets/load_remote_dataset.py b/pygmt/datasets/load_remote_dataset.py
@@ -92,6 +92,24 @@ class GMTRemoteDataset(NamedTuple):
             "30s": Resolution("30s", registrations=["pixel"]),
         },
     ),
+    "earth_dist": GMTRemoteDataset(
+        description="GSHHG Earth distance to shoreline",
+        units="km",
+        extra_attributes={"horizontal_datum": "WGS84"},
+        resolutions={
+            "01d": Resolution("01d"),
+            "30m": Resolution("30m"),
+            "20m": Resolution("20m"),
+            "15m": Resolution("15m"),
+            "10m": Resolution("10m"),
+            "06m": Resolution("06m"),
+            "05m": Resolution("05m", tiled=True),
+            "04m": Resolution("04m", tiled=True),
+            "03m": Resolution("03m", tiled=True),
+            "02m": Resolution("02m", tiled=True),
+            "01m": Resolution("01m", registrations=["gridline"], tiled=True),
+        },
+    ),
     "earth_faa": GMTRemoteDataset(
         description="IGPP Earth free-air anomaly",
         units="mGal",
diff --git a/pygmt/datasets/mars_relief.py b/pygmt/datasets/mars_relief.py
@@ -67,7 +67,8 @@ def load_mars_relief(
     ----------
     resolution
         The grid resolution. The suffix ``d``, ``m`` and ``s`` stand for arc-degrees,
-        arc-minutes and arc-seconds.
+        arc-minutes and arc-seconds. Note that ``"12s"`` refers to a resolution of
+        12.1468873601 arc-seconds.
     region
         The subregion of the grid to load, in the form of a sequence [*xmin*, *xmax*,
         *ymin*, *ymax*] or an ISO country code. Required for grids with resolutions
diff --git a/pygmt/datasets/mercury_relief.py b/pygmt/datasets/mercury_relief.py
@@ -65,7 +65,8 @@ def load_mercury_relief(
     ----------
     resolution
         The grid resolution. The suffix ``d``, ``m`` and ``s`` stand for arc-degrees,
-        arc-minutes and arc-seconds.
+        arc-minutes and arc-seconds. Note that ``"56s"`` refers to a resolution of
+        56.25 arc-seconds.
     region
         The subregion of the grid to load, in the form of a sequence [*xmin*, *xmax*,
         *ymin*, *ymax*] or an ISO country code. Required for grids with resolutions
diff --git a/pygmt/datasets/moon_relief.py b/pygmt/datasets/moon_relief.py
@@ -67,7 +67,8 @@ def load_moon_relief(
     ----------
     resolution
         The grid resolution. The suffix ``d``, ``m`` and ``s`` stand for arc-degrees,
-        arc-minutes and arc-seconds.
+        arc-minutes and arc-seconds. Note that ``"14s"`` refers to a resolution of
+        14.0625 arc-seconds.
     region
         The subregion of the grid to load, in the form of a sequence [*xmin*, *xmax*,
         *ymin*, *ymax*] or an ISO country code. Required for grids with resolutions
diff --git a/pygmt/datasets/pluto_relief.py b/pygmt/datasets/pluto_relief.py
@@ -65,7 +65,8 @@ def load_pluto_relief(
     ----------
     resolution
         The grid resolution. The suffix ``d``, ``m`` and ``s`` stand for arc-degrees,
-        arc-minutes and arc-seconds.
+        arc-minutes and arc-seconds. Note that ``"52s"`` refers to a resolution of
+        52.0732883317 arc-seconds.
     region
         The subregion of the grid to load, in the form of a sequence [*xmin*, *xmax*,
         *ymin*, *ymax*] or an ISO country code. Required for grids with resolutions
diff --git a/pygmt/figure.py b/pygmt/figure.py
@@ -6,7 +6,7 @@
 import os
 from pathlib import Path, PurePath
 from tempfile import TemporaryDirectory
-from typing import Literal
+from typing import Literal, overload
 
 try:
     import IPython
@@ -353,6 +353,14 @@ def show(
                 )
                 raise GMTInvalidInput(msg)
 
+    @overload
+    def _preview(
+        self, fmt: str, dpi: int, as_bytes: Literal[True] = True, **kwargs
+    ) -> bytes: ...
+    @overload
+    def _preview(
+        self, fmt: str, dpi: int, as_bytes: Literal[False] = False, **kwargs
+    ) -> str: ...
     def _preview(self, fmt: str, dpi: int, as_bytes: bool = False, **kwargs):
         """
         Grab a preview of the figure.
@@ -380,7 +388,7 @@ def _preview(self, fmt: str, dpi: int, as_bytes: bool = False, **kwargs):
             return fname.read_bytes()
         return fname
 
-    def _repr_png_(self):
+    def _repr_png_(self) -> bytes:
         """
         Show a PNG preview if the object is returned in an interactive shell.
 
@@ -389,7 +397,7 @@ def _repr_png_(self):
         png = self._preview(fmt="png", dpi=70, anti_alias=True, as_bytes=True)
         return png
 
-    def _repr_html_(self):
+    def _repr_html_(self) -> str:
         """
         Show the PNG image embedded in HTML with a controlled width.
 
diff --git a/pygmt/helpers/caching.py b/pygmt/helpers/caching.py
@@ -14,6 +14,7 @@ def cache_data():
         # List of GMT remote datasets.
         "@earth_age_01d_g",
         "@earth_day_01d",
+        "@earth_dist_01d",
         "@earth_faa_01d_g",
         "@earth_gebco_01d_g",
         "@earth_gebcosi_01d_g",
@@ -47,6 +48,7 @@ def cache_data():
         "@N00W030.earth_age_01m_g.nc",
         "@N30E060.earth_age_01m_g.nc",
         "@N30E090.earth_age_01m_g.nc",
+        "@N00W030.earth_dist_01m_g.nc",
         "@N00W030.earth_faa_01m_p.nc",
         "@N00W030.earth_geoid_01m_g.nc",
         "@S30W060.earth_mag_02m_p.nc",
diff --git a/pygmt/tests/test_datasets_earth_dist.py b/pygmt/tests/test_datasets_earth_dist.py
@@ -0,0 +1,53 @@
+"""
+Test basic functionality for loading Earth distance to shoreline datasets.
+"""
+
+import numpy as np
+import numpy.testing as npt
+from pygmt.datasets import load_earth_dist
+
+
+def test_earth_dist_01d():
+    """
+    Test some properties of the Earth distance to shoreline 01d data.
+    """
+    data = load_earth_dist(resolution="01d")
+    assert data.name == "z"
+    assert data.attrs["description"] == "GSHHG Earth distance to shoreline"
+    assert data.attrs["units"] == "km"
+    assert data.attrs["horizontal_datum"] == "WGS84"
+    assert data.shape == (181, 361)
+    assert data.gmt.registration == 0
+    npt.assert_allclose(data.lat, np.arange(-90, 91, 1))
+    npt.assert_allclose(data.lon, np.arange(-180, 181, 1))
+    npt.assert_allclose(data.min(), -2655.7, atol=0.01)
+    npt.assert_allclose(data.max(), 2463.42, atol=0.01)
+
+
+def test_earth_dist_01d_with_region():
+    """
+    Test loading low-resolution Earth distance to shoreline with "region".
+    """
+    data = load_earth_dist(resolution="01d", region=[-10, 10, -5, 5])
+    assert data.shape == (11, 21)
+    assert data.gmt.registration == 0
+    npt.assert_allclose(data.lat, np.arange(-5, 6, 1))
+    npt.assert_allclose(data.lon, np.arange(-10, 11, 1))
+    npt.assert_allclose(data.min(), -1081.94, atol=0.01)
+    npt.assert_allclose(data.max(), 105.18, atol=0.01)
+
+
+def test_earth_dist_01m_default_registration():
+    """
+    Test that the grid returned by default for the 1 arc-minute resolution has a
+    "gridline" registration.
+    """
+    data = load_earth_dist(resolution="01m", region=[-10, -9, 3, 5])
+    assert data.shape == (121, 61)
+    assert data.gmt.registration == 0
+    assert data.coords["lat"].data.min() == 3.0
+    assert data.coords["lat"].data.max() == 5.0
+    assert data.coords["lon"].data.min() == -10.0
+    assert data.coords["lon"].data.max() == -9.0
+    npt.assert_allclose(data.min(), -243.62, atol=0.01)
+    npt.assert_allclose(data.max(), 2.94, atol=0.01)
