Merge branch 'main' into alias-system

seisman · seisman · commit a854e0d001e7 · 2025-03-12T17:12:04.000+08:00
diff --git a/.github/workflows/ci_tests.yaml b/.github/workflows/ci_tests.yaml
@@ -151,7 +151,7 @@ jobs:
           GH_TOKEN: ${{ github.token }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5.2.2
+        uses: astral-sh/setup-uv@v5.3.1
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -182,7 +182,7 @@ jobs:
 
       # Upload coverage to Codecov
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v5.3.1
+        uses: codecov/codecov-action@v5.4.0
         if: success() || failure()
         with:
           use_oidc: true
diff --git a/pygmt/datasets/earth_age.py b/pygmt/datasets/earth_age.py
@@ -40,7 +40,7 @@ def load_earth_age(
     **@earth_age**\_\ *res*\_\ *reg*. *res* is the grid resolution; *reg* is the grid
     registration type (**p** for pixel registration, **g** for gridline registration).
     If *reg* is omitted (e.g., ``@earth_age_01d``), the gridline-registered grid will be
-    loaded for grid proccessing functions and the pixel-registered grid will be loaded
+    loaded for grid processing functions and the pixel-registered grid will be loaded
     for plotting functions. If *res* is also omitted (i.e., ``@earth_age``), GMT
     automatically selects a suitable resolution based on the current region and
     projection settings.
diff --git a/pygmt/datasets/earth_deflection.py b/pygmt/datasets/earth_deflection.py
@@ -49,7 +49,7 @@ def load_earth_deflection(
     the grid resolution; *reg* is the grid registration type (**p** for pixel
     registration, **g** for gridline registration). If *reg* is omitted (e.g.,
     ``@earth_edefl_01d``), the gridline-registered grid will be loaded for grid
-    proccessing functions and the pixel-registered grid will be loaded for plotting
+    processing functions and the pixel-registered grid will be loaded for plotting
     functions. If *res* is also omitted (i.e., ``@earth_edefl``), GMT automatically
     selects a suitable resolution based on the current region and projection settings.
 
diff --git a/pygmt/datasets/earth_dist.py b/pygmt/datasets/earth_dist.py
@@ -40,7 +40,7 @@ def load_earth_dist(
     **@earth_dist**\_\ *res*\_\ *reg*. *res* is the grid resolution; *reg* is the grid
     registration type (**p** for pixel registration, **g** for gridline registration).
     If *reg* is omitted (e.g., ``@earth_dist_01d``), the gridline-registered grid will
-    be loaded for grid proccessing functions and the pixel-registered grid will be
+    be loaded for grid processing functions and the pixel-registered grid will be
     loaded for plotting functions. If *res* is also omitted (i.e., ``@earth_dist``), GMT
     automatically selects a suitable resolution based on the current region and
     projection settings.
diff --git a/pygmt/datasets/earth_free_air_anomaly.py b/pygmt/datasets/earth_free_air_anomaly.py
@@ -49,7 +49,7 @@ def load_earth_free_air_anomaly(
     the grid resolution; *reg* is the grid registration type (**p** for pixel
     registration, **g** for gridline registration). If *reg* is omitted (e.g.,
     ``@earth_faa_01d``), the gridline-registered grid will be loaded for grid
-    proccessing functions and the pixel-registered grid will be loaded for plotting
+    processing functions and the pixel-registered grid will be loaded for plotting
     functions. If *res* is also omitted (i.e., ``@earth_faa``), GMT automatically
     selects a suitable resolution based on the current region and projection settings.
 
diff --git a/pygmt/datasets/earth_geoid.py b/pygmt/datasets/earth_geoid.py
@@ -40,7 +40,7 @@ def load_earth_geoid(
     **@earth_geoid**\_\ *res*\_\ *reg*. *res* is the grid resolution; *reg* is the grid
     registration type (**p** for pixel registration, **g** for gridline registration).
     If *reg* is omitted (e.g., ``@earth_geoid_01d``), the gridline-registered grid will
-    be loaded for grid proccessing functions and the pixel-registered grid will be
+    be loaded for grid processing functions and the pixel-registered grid will be
     loaded for plotting functions. If *res* is also omitted (i.e., ``@earth_geoid``),
     GMT automatically selects a suitable resolution based on the current region and
     projection settings.
diff --git a/pygmt/datasets/earth_magnetic_anomaly.py b/pygmt/datasets/earth_magnetic_anomaly.py
@@ -49,7 +49,7 @@ def load_earth_magnetic_anomaly(
     **earth_wdmam**; *res* is the grid resolution; *reg* is the grid
     registration type (**p** for pixel registration, **g** for gridline registration).
     If *reg* is omitted (e.g., ``@earth_mag_01d``), the gridline-registered grid will be
-    loaded for grid proccessing functions and the pixel-registered grid will be loaded
+    loaded for grid processing functions and the pixel-registered grid will be loaded
     for plotting functions. If *res* is also omitted (i.e., ``@earth_mag``), GMT
     automatically selects a suitable resolution based on the current region and
     projection settings.
diff --git a/pygmt/datasets/earth_mask.py b/pygmt/datasets/earth_mask.py
@@ -52,7 +52,7 @@ def load_earth_mask(
     **@earth_mask**\_\ *res*\_\ *reg*. *res* is the grid resolution; *reg* is the grid
     registration type (**p** for pixel registration, **g** for gridline registration).
     If *reg* is omitted (e.g., ``@earth_mask_01d``), the gridline-registered grid will
-    be loaded for grid proccessing functions and the pixel-registered grid will be
+    be loaded for grid processing functions and the pixel-registered grid will be
     loaded for plotting functions. If *res* is also omitted (i.e., ``@earth_mask``), GMT
     automatically selects a suitable resolution based on the current region and
     projection settings.
diff --git a/pygmt/datasets/earth_mean_dynamic_topography.py b/pygmt/datasets/earth_mean_dynamic_topography.py
@@ -38,7 +38,7 @@ def load_earth_mean_dynamic_topography(
     **@earth_mdt**\_\ *res*\_\ *reg*. *res* is the grid resolution; *reg* is the grid
     registration type (**p** for pixel registration, **g** for gridline registration).
     If *reg* is omitted (e.g., ``@earth_mdt_01d``), the gridline-registered grid will be
-    loaded for grid proccessing functions and the pixel-registered grid will be loaded
+    loaded for grid processing functions and the pixel-registered grid will be loaded
     for plotting functions. If *res* is also omitted (i.e., ``@earth_mdt``), GMT
     automatically selects a suitable resolution based on the current region and
     projection settings.
diff --git a/pygmt/datasets/earth_mean_sea_surface.py b/pygmt/datasets/earth_mean_sea_surface.py
@@ -40,7 +40,7 @@ def load_earth_mean_sea_surface(
     **@earth_mss**\_\ *res*\_\ *reg*. *res* is the grid resolution; *reg* is the grid
     registration type (**p** for pixel registration, **g** for gridline registration).
     If *reg* is omitted (e.g., ``@earth_mss_01d``), the gridline-registered grid will be
-    loaded for grid proccessing functions and the pixel-registered grid will be loaded
+    loaded for grid processing functions and the pixel-registered grid will be loaded
     for plotting functions. If *res* is also omitted (i.e., ``@earth_mss``), GMT
     automatically selects a suitable resolution based on the current region and
     projection settings.
diff --git a/pygmt/datasets/earth_relief.py b/pygmt/datasets/earth_relief.py
@@ -62,7 +62,7 @@ def load_earth_relief(
     **earth_gebcosi**\, and **earth_synbath**\. *res* is the grid resolution; *reg* is
     the grid registration type (**p** for pixel registration, **g** for gridline
     registration). If *reg* is omitted (e.g., ``@earth_relief_01d``), the
-    gridline-registered grid will be loaded for grid proccessing functions and the
+    gridline-registered grid will be loaded for grid processing functions and the
     pixel-registered grid willcbe loaded for plotting functions. If *res* is also
     omitted (i.e., ``@earth_relief``), GMT automatically selects a suitable resolution
     based on the current region and projection settings.
diff --git a/pygmt/datasets/earth_vertical_gravity_gradient.py b/pygmt/datasets/earth_vertical_gravity_gradient.py
@@ -40,7 +40,7 @@ def load_earth_vertical_gravity_gradient(
     **@earth_vgg**\_\ *res*\_\ *reg*. *res* is the grid resolution; *reg* is the grid
     registration type (**p** for pixel registration, **g** for gridline registration).
     If *reg* is omitted (e.g., ``@earth_vgg_01d``), the gridline-registered grid will be
-    loaded for grid proccessing functions and the pixel-registered grid will be loaded
+    loaded for grid processing functions and the pixel-registered grid will be loaded
     for plotting functions. If *res* is also omitted (i.e., ``@earth_vgg``), GMT
     automatically selects a suitable resolution based on the current region and
     projection settings.
diff --git a/pygmt/datasets/mars_relief.py b/pygmt/datasets/mars_relief.py
@@ -53,7 +53,7 @@ def load_mars_relief(
     **@mars_relief**\_\ *res*\_\ *reg*. *res* is the grid resolution; *reg* is the grid
     registration type (**p** for pixel registration, **g** for gridline registration).
     If *reg* is omitted (e.g., ``@mars_relief_01d``), the gridline-registered grid will
-    be loaded for grid proccessing functions and the pixel-registered grid will be
+    be loaded for grid processing functions and the pixel-registered grid will be
     loaded for plotting functions. If *res* is also omitted (i.e., ``@mars_relief``),
     GMT automatically selects a suitable resolution based on the current region and
     projection settings.
diff --git a/pygmt/datasets/mercury_relief.py b/pygmt/datasets/mercury_relief.py
@@ -52,7 +52,7 @@ def load_mercury_relief(
     **@mercury_relief**\_\ *res*\_\ *reg*. *res* is the grid resolution; *reg* is the
     grid registration type (**p** for pixel registration, **g** for gridline
     registration). If *reg* is omitted (e.g., ``@mercury_relief_01d``), the
-    gridline-registered grid will be loaded for grid proccessing functions and the
+    gridline-registered grid will be loaded for grid processing functions and the
     pixel-registered grid will be loaded for plotting functions. If *res* is also
     omitted (i.e., ``@mercury_relief``), GMT automatically selects a suitable resolution
     based on the current region and projection settings.
diff --git a/pygmt/datasets/moon_relief.py b/pygmt/datasets/moon_relief.py
@@ -53,7 +53,7 @@ def load_moon_relief(
     **@moon_relief**\_\ *res*\_\ *reg*. *res* is the grid resolution; *reg* is the grid
     registration type (**p** for pixel registration, **g** for gridline registration).
     If *reg* is omitted (e.g., ``@moon_relief_01d``), the gridline-registered grid will
-    be loaded for grid proccessing functions and the pixel-registered grid will be
+    be loaded for grid processing functions and the pixel-registered grid will be
     loaded for plotting functions. If *res* is also omitted (i.e., ``@moon_relief``),
     GMT automatically selects a suitable resolution based on the current region and
     projection settings.
diff --git a/pygmt/datasets/pluto_relief.py b/pygmt/datasets/pluto_relief.py
@@ -51,7 +51,7 @@ def load_pluto_relief(
     **@pluto_relief**\_\ *res*\_\ *reg*. *res* is the grid resolution; *reg* is the grid
     registration type (**p** for pixel registration, **g** for gridline registration).
     If *reg* is omitted (e.g., ``@pluto_relief_01d``), the gridline-registered grid will
-    be loaded for grid proccessing functions and the pixel-registered grid will be
+    be loaded for grid processing functions and the pixel-registered grid will be
     loaded for plotting functions. If *res* is also omitted (i.e., ``@pluto_relief``),
     GMT automatically selects a suitable resolution based on the current region and
     projection settings.
diff --git a/pygmt/datasets/venus_relief.py b/pygmt/datasets/venus_relief.py
@@ -40,7 +40,7 @@ def load_venus_relief(
     **@venus_relief**\_\ *res*\_\ *reg*. *res* is the grid resolution; *reg* is the grid
     registration type (**p** for pixel registration, **g** for gridline registration).
     If *reg* is omitted (e.g., ``@venus_relief_01d``), the gridline-registered grid will
-    be loaded for grid proccessing functions and the pixel-registered grid will be
+    be loaded for grid processing functions and the pixel-registered grid will be
     loaded for plotting functions. If *res* is also omitted (i.e., ``@venus_relief``),
     GMT automatically selects a suitable resolution based on the current region and
     projection settings.
diff --git a/pygmt/src/grdcut.py b/pygmt/src/grdcut.py
@@ -2,23 +2,24 @@
 grdcut - Extract subregion from a grid.
 """
 
+from typing import Literal
+
 import xarray as xr
 from pygmt.clib import Session
+from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers import (
-    GMTTempFile,
     build_arg_list,
+    data_kind,
     fmt_docstring,
     kwargs_to_strings,
     use_alias,
 )
-from pygmt.io import load_dataarray
 
 __doctest_skip__ = ["grdcut"]
 
 
 @fmt_docstring
 @use_alias(
-    G="outgrid",
     R="region",
     J="projection",
     N="extend",
@@ -28,9 +29,11 @@
     f="coltypes",
 )
 @kwargs_to_strings(R="sequence")
-def grdcut(grid, **kwargs) -> xr.DataArray | None:
+def grdcut(
+    grid, kind: Literal["grid", "image"] = "grid", outgrid: str | None = None, **kwargs
+) -> xr.DataArray | None:
     r"""
-    Extract subregion from a grid.
+    Extract subregion from a grid or image.
 
     Produce a new ``outgrid`` file which is a subregion of ``grid``. The
     subregion is specified with ``region``; the specified range must not exceed
@@ -48,6 +51,11 @@ def grdcut(grid, **kwargs) -> xr.DataArray | None:
     Parameters
     ----------
     {grid}
+    kind
+        The raster data kind. Valid values are ``"grid"`` and ``"image"``. When the
+        input ``grid`` is a file name, it's difficult to determine if the file is a grid
+        or an image, so we need to specify the raster kind explicitly. The default is
+        ``"grid"``.
     {outgrid}
     {projection}
     {region}
@@ -100,13 +108,27 @@ def grdcut(grid, **kwargs) -> xr.DataArray | None:
     >>> # 12° E to 15° E and a latitude range of 21° N to 24° N
     >>> new_grid = pygmt.grdcut(grid=grid, region=[12, 15, 21, 24])
     """
-    with GMTTempFile(suffix=".nc") as tmpfile:
-        with Session() as lib:
-            with lib.virtualfile_in(check_kind="raster", data=grid) as vingrd:
-                if (outgrid := kwargs.get("G")) is None:
-                    kwargs["G"] = outgrid = tmpfile.name  # output to tmpfile
-                lib.call_module(
-                    module="grdcut", args=build_arg_list(kwargs, infile=vingrd)
-                )
+    if kind not in {"grid", "image"}:
+        msg = f"Invalid raster kind: '{kind}'. Valid values are 'grid' and 'image'."
+        raise GMTInvalidInput(msg)
+
+    # Determine the output data kind based on the input data kind.
+    match inkind := data_kind(grid):
+        case "grid" | "image":
+            outkind = inkind
+        case "file":
+            outkind = kind
+        case _:
+            msg = f"Unsupported data type {type(grid)}."
+            raise GMTInvalidInput(msg)
 
-        return load_dataarray(outgrid) if outgrid == tmpfile.name else None
+    with Session() as lib:
+        with (
+            lib.virtualfile_in(check_kind="raster", data=grid) as vingrd,
+            lib.virtualfile_out(kind=outkind, fname=outgrid) as voutgrd,
+        ):
+            kwargs["G"] = voutgrd
+            lib.call_module(module="grdcut", args=build_arg_list(kwargs, infile=vingrd))
+            return lib.virtualfile_to_raster(
+                vfname=voutgrd, kind=outkind, outgrid=outgrid
+            )
diff --git a/pygmt/src/meca.py b/pygmt/src/meca.py
@@ -2,6 +2,9 @@
 meca - Plot focal mechanisms.
 """
 
+from collections.abc import Sequence
+from typing import Literal
+
 import numpy as np
 import pandas as pd
 from pygmt.clib import Session
@@ -131,14 +134,14 @@ def meca(  # noqa: PLR0913
     self,
     spec,
     scale,
-    convention=None,
-    component="full",
-    longitude=None,
-    latitude=None,
-    depth=None,
-    plot_longitude=None,
-    plot_latitude=None,
-    event_name=None,
+    convention: Literal["aki", "gcmt", "mt", "partial", "principal_axis"] | None = None,
+    component: Literal["full", "dc", "deviatoric"] = "full",
+    longitude: float | Sequence[float] | None = None,
+    latitude: float | Sequence[float] | None = None,
+    depth: float | Sequence[float] | None = None,
+    plot_longitude: float | Sequence[float] | None = None,
+    plot_latitude: float | Sequence[float] | None = None,
+    event_name: str | Sequence[str] | None = None,
     **kwargs,
 ):
     r"""
@@ -248,28 +251,32 @@ def meca(  # noqa: PLR0913
         to change its font (size,fontname,color); append **+j**\ *justify* to change
         the text location relative to the beachball [Default is ``"TC"``, i.e., Top
         Center]; append **+o** to offset the text string by *dx*\ /*dy*.
-    convention : str
-        Focal mechanism convention. See the table above for the supported conventions.
-        Ignored if ``spec`` is a dict or :class:`pandas.DataFrame`.
-    component : str
-        The component of the seismic moment tensor to plot.
+    convention
+        Specify the focal mechanism convention of the input data. Ignored if ``spec`` is
+        a dict or :class:`pandas.DataFrame`. See the table above for the supported
+        conventions.
+    component
+        The component of the seismic moment tensor to plot. Valid values are:
 
         - ``"full"``: the full seismic moment tensor
-        - ``"dc"``: the closest double couple defined from the moment tensor (zero
-          trace and zero determinant)
+        - ``"dc"``: the closest double couple defined from the moment tensor (zero trace
+          and zero determinant)
         - ``"deviatoric"``: deviatoric part of the moment tensor (zero trace)
-    longitude/latitude/depth : float, list, or 1-D numpy array
-        Longitude(s) / latitude(s) / depth(s) of the event(s). Length must match the
-        number of events. Overrides the ``longitude`` / ``latitude`` / ``depth`` values
-        in ``spec`` if ``spec`` is a dict or :class:`pandas.DataFrame`.
-    plot_longitude/plot_latitude : float, str, list, or 1-D numpy array
-        Longitude(s) / Latitude(s) at which to place the beachball(s). Length must match
-        the number of events. Overrides the ``plot_longitude`` / ``plot_latitude``
-        values in ``spec`` if ``spec`` is a dict or :class:`pandas.DataFrame`.
-    event_name : str, list of str, or 1-D numpy array
-        Text string(s), e.g., event name(s) to appear near the beachball(s). Length
-        must match the number of events. Overrides the ``event_name`` labels in ``spec``
-        if ``spec`` is a dict or :class:`pandas.DataFrame`.
+    longitude/latitude/depth
+        Longitude(s), latitude(s), and depth(s) of the event(s). The length of each must
+        match the number of events. These parameters are only used if ``spec`` is a
+        dictionary or a :class:`pandas.DataFrame`, and they override any existing
+        ``longitude``, ``latitude``, or ``depth`` values in ``spec``.
+    plot_longitude/plot_latitude
+        Longitude(s) and latitude(s) at which to place the beachball(s). The length of
+        each must match the number of events. These parameters are only used if ``spec``
+        is a dictionary or a :class:`pandas.DataFrame`, and they override any existing
+        ``plot_longitude`` or ``plot_latitude`` values in ``spec``.
+    event_name
+        Text string(s), such as event name(s), to appear near the beachball(s). The
+        length must match the number of events. This parameter is only used if ``spec``
+        is a dictionary or a :class:`pandas.DataFrame`, and it overrides any existing
+        ``event_name`` labels in ``spec``.
     labelbox : bool or str
         [*fill*].
         Draw a box behind the label if given via ``event_name``. Use *fill* to give a
diff --git a/pygmt/tests/test_grdcut.py b/pygmt/tests/test_grdcut.py
@@ -70,3 +70,11 @@ def test_grdcut_fails():
     """
     with pytest.raises(GMTInvalidInput):
         grdcut(np.arange(10).reshape((5, 2)))
+
+
+def test_grdcut_invalid_kind(grid, region):
+    """
+    Check that grdcut fails with incorrect 'kind'.
+    """
+    with pytest.raises(GMTInvalidInput):
+        grdcut(grid, kind="invalid", region=region)
diff --git a/pygmt/tests/test_grdcut_image.py b/pygmt/tests/test_grdcut_image.py
