Merge branch 'main' into load_moon_relief

.github/ISSUE_TEMPLATE/release_checklist.md

@@ -48,7 +48,6 @@ assignees: ''
 - [ ] Announce the release on:
   - [ ] GMT [forum](https://forum.generic-mapping-tools.org/c/news/) (do this announcement first! draft on https://hackmd.io/@pygmt. requires moderator status)
   - [ ] [ResearchGate](https://www.researchgate.net) (after forum announcement, add new version as research item via the **code** category, be sure to include the corresponding new Zenodo DOI)
-  - [ ] [Twitter](https://twitter.com/gmt_dev) (after forum announcement)
 ---
 
 - [ ] Party :tada: (don't tick before all other checkboxes are ticked!)

.github/workflows/cache_data.yaml

@@ -38,7 +38,7 @@ jobs:
 
       # Install Micromamba with conda-forge dependencies
       - name: Setup Micromamba
-        uses: mamba-org/setup-micromamba@v1.7.3
+        uses: mamba-org/setup-micromamba@v1.8.0
         with:
           environment-name: pygmt
           condarc: |

.github/workflows/check-links.yml

@@ -55,7 +55,6 @@ jobs:
           --exclude "^https://doi.org"
           --exclude "^https://www.researchgate.net/project/"
           --exclude "^https://test.pypi.org/simple/"
-          --exclude "^https://twitter.com/"
           --verbose
           "repository/**/*.rst"
           "repository/**/*.md"

.github/workflows/ci_docs.yml

@@ -75,7 +75,7 @@ jobs:
 
       # Install Micromamba with conda-forge dependencies
       - name: Setup Micromamba
-        uses: mamba-org/setup-micromamba@v1.7.3
+        uses: mamba-org/setup-micromamba@v1.8.0
         with:
           environment-name: pygmt
           condarc: |

.github/workflows/ci_doctests.yaml

@@ -41,7 +41,7 @@ jobs:
 
       # Install Micromamba with conda-forge dependencies
       - name: Setup Micromamba
-        uses: mamba-org/setup-micromamba@v1.7.3
+        uses: mamba-org/setup-micromamba@v1.8.0
         with:
           environment-name: pygmt
           condarc: |

.github/workflows/ci_tests.yaml

@@ -93,7 +93,7 @@ jobs:
 
       # Install Micromamba with conda-forge dependencies
       - name: Setup Micromamba
-        uses: mamba-org/setup-micromamba@v1.7.3
+        uses: mamba-org/setup-micromamba@v1.8.0
         with:
           environment-name: pygmt
           condarc: |

.github/workflows/ci_tests_dev.yaml

@@ -53,7 +53,7 @@ jobs:
 
       # Install Micromamba with conda-forge dependencies
       - name: Setup Micromamba
-        uses: mamba-org/setup-micromamba@v1.7.3
+        uses: mamba-org/setup-micromamba@v1.8.0
         with:
           environment-name: pygmt
           condarc: |

.github/workflows/ci_tests_legacy.yaml

@@ -50,7 +50,7 @@ jobs:
 
       # Install Micromamba with conda-forge dependencies
       - name: Setup Micromamba
-        uses: mamba-org/setup-micromamba@v1.7.3
+        uses: mamba-org/setup-micromamba@v1.8.0
         with:
           environment-name: pygmt
           condarc: |

README.rst

@@ -46,9 +46,6 @@ PyGMT
 .. image:: https://img.shields.io/badge/Contributor%20Covenant-v2.1%20adopted-ff69b4.svg
     :alt: Contributor Code of Conduct
     :target: CODE_OF_CONDUCT.md
-.. image:: https://img.shields.io/twitter/follow/gmt_dev?style=social
-    :alt: Twitter URL
-    :target: https://twitter.com/gmt_dev
 
 .. placeholder-for-doc-index
 

doc/api/index.rst

@@ -226,6 +226,7 @@ and store them in GMT's user data directory.
     datasets.load_earth_mask
     datasets.load_earth_relief
     datasets.load_earth_vertical_gravity_gradient
+    datasets.load_mars_relief
     datasets.load_moon_relief
     datasets.load_sample_data
 

pygmt/datasets/__init__.py

@@ -13,6 +13,7 @@
 from pygmt.datasets.earth_vertical_gravity_gradient import (
     load_earth_vertical_gravity_gradient,
 )
+from pygmt.datasets.mars_relief import load_mars_relief
 from pygmt.datasets.moon_relief import load_moon_relief
 from pygmt.datasets.samples import list_sample_data, load_sample_data
 from pygmt.datasets.tile_map import load_tile_map

pygmt/datasets/load_remote_dataset.py

@@ -226,6 +226,29 @@ class GMTRemoteDataset(NamedTuple):
             "03m": Resolution("03m", registrations=["gridline"], tiled=True),
         },
     ),
+    "mars_relief": GMTRemoteDataset(
+        title="Mars relief",
+        name="mars_relief",
+        long_name="NASA Mars (MOLA) relief",
+        units="meters",
+        extra_attributes={},
+        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", tiled=True),
+            "30s": Resolution("30s", tiled=True),
+            "15s": Resolution("15s", tiled=True),
+            "12s": Resolution("12s", registrations=["pixel"], tiled=True),
+        },
+    ),
     "moon_relief": GMTRemoteDataset(
         title="Moon relief",
         name="moon_relief",

pygmt/datasets/mars_relief.py

@@ -0,0 +1,104 @@
+"""
+Function to download the Mars relief dataset from the GMT data server, and load as
+:class:`xarray.DataArray`.
+
+The grids are available in various resolutions.
+"""
+from typing import Literal
+
+from pygmt.datasets.load_remote_dataset import _load_remote_dataset
+from pygmt.helpers import kwargs_to_strings
+
+__doctest_skip__ = ["load_mars_relief"]
+
+
+@kwargs_to_strings(region="sequence")
+def load_mars_relief(
+    resolution="01d",
+    region=None,
+    registration: Literal["gridline", "pixel", None] = None,
+):
+    r"""
+    Load the Mars relief dataset in various resolutions.
+
+    .. figure:: https://www.generic-mapping-tools.org/remote-datasets/_images/GMT_mars_relief.jpg
+       :width: 80%
+       :align: center
+
+       Mars relief dataset.
+
+    The grids are downloaded to a user data directory (usually
+    ``~/.gmt/server/mars/mars_relief/``) 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
+    **@mars_relief**\_\ *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 *@mars_relief.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="@mars_relief.cpt"``.
+
+    Refer to :gmt-datasets:`mars-relief.html` for more details about available datasets,
+    including version information and references.
+
+    Parameters
+    ----------
+    resolution : str
+        The grid resolution. The suffix ``d``, ``m`` and ``s`` stand for arc-degrees,
+        arc-minutes and arc-seconds. It can be ``"01d"``, ``"30m"``, ``"20m"``,
+        ``"15m"``, ``"10m"``, ``"06m"``, ``"05m"``, ``"04m"``, ``"03m"``, ``"02m"``,
+        ``"01m"``, ``"30s"``, ``"15s"``, and ``"12s"``.
+    region : str or list
+        The subregion of the grid to load, in the form of a list
+        [*xmin*, *xmax*, *ymin*, *ymax*] or a string *xmin/xmax/ymin/ymax*. 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. Default is ``None``, means
+        ``"gridline"`` for all resolutions except for ``"12s"`` which is ``"pixel"``
+        only.
+
+    Returns
+    -------
+    grid : :class:`xarray.DataArray`
+        The Mars relief grid. Coordinates are latitude and longitude in degrees. Relief
+        is in meters.
+
+    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_mars_relief
+    >>> # load the default grid (gridline-registered 1 arc-degree grid)
+    >>> grid = load_mars_relief()
+    >>> # load the 30 arc-minutes grid with "gridline" registration
+    >>> grid = load_mars_relief(resolution="30m", registration="gridline")
+    >>> # load high-resolution (5 arc-minutes) grid for a specific region
+    >>> grid = load_mars_relief(
+    ...     resolution="05m",
+    ...     region=[120, 160, 30, 60],
+    ...     registration="gridline",
+    ... )
+    """
+    grid = _load_remote_dataset(
+        dataset_name="mars_relief",
+        dataset_prefix="mars_relief_",
+        resolution=resolution,
+        region=region,
+        registration=registration,
+    )
+    return grid

pygmt/helpers/caching.py

@@ -59,6 +59,9 @@ def cache_data():
         "@S90E000.earth_wdmam_03m_g.nc",  # Specific grid for 03m test
         # Earth day/night images
         "@earth_day_01d_p",
+        # Mars relief grids
+        "@mars_relief_01d_g",
+        "@N00W030.mars_relief_01m_g.nc",  # Specific grid for 01m tes
         # Moon relief grids
         "@moon_relief_01d_g",
         "@N00W030.moon_relief_01m_p.nc",  # Specific grid for 01m test

pygmt/tests/test_datasets_mars_relief.py

@@ -0,0 +1,51 @@
+"""
+Test basic functionality for loading Mars relief datasets.
+"""
+import numpy as np
+import numpy.testing as npt
+from pygmt.datasets import load_mars_relief
+
+
+def test_mars_relief_01d():
+    """
+    Test some properties of the Mars relief 01d data.
+    """
+    data = load_mars_relief(resolution="01d")
+    assert data.name == "mars_relief"
+    assert data.attrs["units"] == "meters"
+    assert data.attrs["long_name"] == "NASA Mars (MOLA) relief"
+    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(), -7421.0, atol=0.5)
+    npt.assert_allclose(data.max(), 19587.5, atol=0.5)
+
+
+def test_mars_relief_01d_with_region():
+    """
+    Test loading low-resolution Mars relief with 'region'.
+    """
+    data = load_mars_relief(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(), -2502.0, atol=0.5)
+    npt.assert_allclose(data.max(), -135.5, atol=0.5)
+
+
+def test_mars_relief_01m_default_registration():
+    """
+    Test that the grid returned by default for the 1 arc-minute resolution has
+    a "gridline" registration.
+    """
+    data = load_mars_relief(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(), -3374.0, atol=0.5)
+    npt.assert_allclose(data.max(), -1181.0, atol=0.5)