Merge branch 'main' into AliasSystem/panel

Author: seisman

pygmt/src/grdclip.py

@@ -6,14 +6,14 @@
 
 import xarray as xr
 from pygmt._typing import PathLike
+from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers import (
     build_arg_list,
     deprecate_parameter,
     fmt_docstring,
     kwargs_to_strings,
-    sequence_join,
     use_alias,
 )
 
@@ -23,9 +23,7 @@
 # TODO(PyGMT>=0.19.0): Remove the deprecated "new" parameter.
 @fmt_docstring
 @deprecate_parameter("new", "replace", "v0.15.0", remove_version="v0.19.0")
-@use_alias(
-    R="region", Sa="above-", Sb="below-", Si="between-", Sr="replace-", V="verbose"
-)
+@use_alias(R="region", V="verbose")
 @kwargs_to_strings(R="sequence")
 def grdclip(
     grid: PathLike | xr.DataArray,
@@ -54,6 +52,10 @@ def grdclip(
     Full GMT docs at :gmt-docs:`grdclip.html`.
 
     {aliases}
+       - Sa=above
+       - Sb=below
+       - Si=between
+       - Sr=replace
 
     Parameters
     ----------
@@ -113,19 +115,20 @@ def grdclip(
         )
         raise GMTInvalidInput(msg)
 
-    # Parse the -S option.
-    kwargs["Sa"] = sequence_join(above, size=2, name="above")
-    kwargs["Sb"] = sequence_join(below, size=2, name="below")
-    kwargs["Si"] = sequence_join(between, size=3, ndim=2, name="between")
-    kwargs["Sr"] = sequence_join(replace, size=2, ndim=2, name="replace")
+    aliasdict = AliasSystem(
+        Sa=Alias(above, name="above", sep="/", size=2),
+        Sb=Alias(below, name="below", sep="/", size=2),
+        Si=Alias(between, name="between", sep="/", size=3, ndim=2),
+        Sr=Alias(replace, name="replace", sep="/", size=2, ndim=2),
+    ).merge(kwargs)
 
     with Session() as lib:
         with (
             lib.virtualfile_in(check_kind="raster", data=grid) as vingrd,
             lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd,
         ):
-            kwargs["G"] = voutgrd
+            aliasdict["G"] = voutgrd
             lib.call_module(
-                module="grdclip", args=build_arg_list(kwargs, infile=vingrd)
+                module="grdclip", args=build_arg_list(aliasdict, infile=vingrd)
             )
             return lib.virtualfile_to_raster(vfname=voutgrd, outgrid=outgrid)

pygmt/src/grdfill.py

@@ -7,6 +7,7 @@
 import numpy as np
 import xarray as xr
 from pygmt._typing import PathLike
+from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers import (
@@ -71,52 +72,11 @@ def _validate_params(
         raise GMTInvalidInput(msg)
 
 
-def _parse_fill_mode(
-    constantfill=None, gridfill=None, neighborfill=None, splinefill=None
-) -> str | None:
-    """
-    Parse the fill parameters and return the appropriate string for the -A option.
-
-    >>> import numpy as np
-    >>> import xarray as xr
-    >>> _parse_fill_mode(constantfill=20.0)
-    'c20.0'
-    >>> _parse_fill_mode(gridfill="bggrid.nc")
-    'g'
-    >>> _parse_fill_mode(gridfill=xr.DataArray(np.zeros((10, 10))))
-    'g'
-    >>> _parse_fill_mode(neighborfill=20)
-    'n20'
-    >>> _parse_fill_mode(neighborfill=True)
-    'n'
-    >>> _parse_fill_mode(splinefill=0.5)
-    's0.5'
-    >>> _parse_fill_mode(splinefill=True)
-    's'
-    """
-    if constantfill is not None:
-        return f"c{constantfill}"
-    if gridfill is not None:
-        return "g"  # Append grid file name later to support xarray.DataArray.
-    if neighborfill is not None and neighborfill is not False:
-        return "n" if neighborfill is True else f"n{neighborfill}"
-    if splinefill is not None and splinefill is not False:
-        return "s" if splinefill is True else f"s{splinefill}"
-    return None
-
-
 @fmt_docstring
 # TODO(PyGMT>=0.19.0): Remove the deprecated 'no_data' parameter.
 # TODO(PyGMT>=0.19.0): Remove the deprecated 'mode' parameter.
 @deprecate_parameter("no_data", "hole", "v0.15.0", remove_version="v0.19.0")
-@use_alias(
-    A="constantfill/gridfill/neighborfill/splinefill/mode-",
-    L="inquire-",
-    N="hole",
-    R="region",
-    V="verbose",
-    f="coltypes",
-)
+@use_alias(N="hole", R="region", V="verbose", f="coltypes")
 @kwargs_to_strings(R="sequence")
 def grdfill(
     grid: PathLike | xr.DataArray,
@@ -141,6 +101,11 @@ def grdfill(
     Full GMT docs at :gmt-docs:`grdfill.html`.
 
     {aliases}
+       - Ac=constantfill
+       - Ag=gridfill
+       - An=neighborfill
+       - As=splinefill
+       - L=inquire
 
     Parameters
     ----------
@@ -209,21 +174,24 @@ def grdfill(
     # Validate the fill/inquire parameters.
     _validate_params(constantfill, gridfill, neighborfill, splinefill, inquire, mode)
 
-    # Parse the fill parameters and return the appropriate string for the -A option.
-    kwargs["A"] = (
-        _parse_fill_mode(constantfill, gridfill, neighborfill, splinefill)
-        if mode is None
-        else mode
-    )
+    # _validate_params has already ensured that only one of the parameters is set.
+    aliasdict = AliasSystem(
+        A=Alias(mode, name="mode"),
+        Ac=Alias(constantfill, name="constantfill"),
+        # For grdfill, append the actual or virtual grid file name later.
+        Ag=Alias(gridfill is not None, name="gridfill"),
+        An=Alias(neighborfill, name="neighborfill"),
+        As=Alias(splinefill, name="splinefill"),
+        L=Alias(inquire, name="inquire"),
+    ).merge(kwargs)
 
     with Session() as lib:
         with lib.virtualfile_in(check_kind="raster", data=grid) as vingrd:
             if inquire:  # Inquire mode.
-                kwargs["L"] = True
                 with lib.virtualfile_out(kind="dataset") as vouttbl:
                     lib.call_module(
                         module="grdfill",
-                        args=build_arg_list(kwargs, infile=vingrd, outfile=vouttbl),
+                        args=build_arg_list(aliasdict, infile=vingrd, outfile=vouttbl),
                     )
                     return lib.virtualfile_to_dataset(
                         vfname=vouttbl, output_type="numpy"
@@ -238,9 +206,9 @@ def grdfill(
             ):
                 if gridfill is not None:
                     # Fill by a grid. Append the actual or virtual grid file name.
-                    kwargs["A"] = f"g{vbggrd}"
-                kwargs["G"] = voutgrd
+                    aliasdict["Ag"] = vbggrd
+                aliasdict["G"] = voutgrd
                 lib.call_module(
-                    module="grdfill", args=build_arg_list(kwargs, infile=vingrd)
+                    module="grdfill", args=build_arg_list(aliasdict, infile=vingrd)
                 )
                 return lib.virtualfile_to_raster(vfname=voutgrd, outgrid=outgrid)

pygmt/src/grdlandmask.py

@@ -7,13 +7,13 @@
 
 import xarray as xr
 from pygmt._typing import PathLike
+from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers import (
     build_arg_list,
     fmt_docstring,
     kwargs_to_strings,
-    sequence_join,
     use_alias,
 )
 from pygmt.src._common import _parse_coastline_resolution
@@ -25,9 +25,7 @@
 @use_alias(
     A="area_thresh",
     D="resolution-",
-    E="bordervalues-",
     I="spacing",
-    N="maskvalues-",
     R="region",
     V="verbose",
     r="registration",
@@ -55,6 +53,8 @@ def grdlandmask(
     Full GMT docs at :gmt-docs:`grdlandmask.html`.
 
     {aliases}
+       - E=bordervalues
+       - N=maskvalues
 
     Parameters
     ----------
@@ -119,11 +119,14 @@ def grdlandmask(
         raise GMTInvalidInput(msg)
 
     kwargs["D"] = kwargs.get("D", _parse_coastline_resolution(resolution))
-    kwargs["N"] = sequence_join(maskvalues, size=(2, 5), name="maskvalues")
-    kwargs["E"] = sequence_join(bordervalues, size=(1, 4), name="bordervalues")
+
+    aliasdict = AliasSystem(
+        N=Alias(maskvalues, name="maskvalues", sep="/", size=(2, 5)),
+        E=Alias(bordervalues, name="bordervalues", sep="/", size=4),
+    ).merge(kwargs)
 
     with Session() as lib:
         with lib.virtualfile_out(kind="grid", fname=outgrid) as voutgrd:
-            kwargs["G"] = voutgrd
-            lib.call_module(module="grdlandmask", args=build_arg_list(kwargs))
+            aliasdict["G"] = voutgrd
+            lib.call_module(module="grdlandmask", args=build_arg_list(aliasdict))
             return lib.virtualfile_to_raster(vfname=voutgrd, outgrid=outgrid)

pygmt/src/ternary.py

@@ -15,7 +15,6 @@
     B="frame",
     C="cmap",
     G="fill",
-    L="alabel/blabel/clabel-",
     JX="width",
     R="region",
     S="style",
@@ -48,6 +47,7 @@ def ternary(
     Full GMT docs at :gmt-docs:`ternary.html`.
 
     {aliases}
+       - L=alabel/blabel/clabel
        - c=panel
 
     Parameters
@@ -87,19 +87,19 @@ def ternary(
     self._activate_figure()
 
     # -Lalabel/blabel/clabel. '-' means skipping the label.
-    labels = (alabel, blabel, clabel)
-    if any(v is not None for v in labels):
-        kwargs["L"] = "/".join(str(v) if v is not None else "-" for v in labels)
+    _labels = [v if v is not None else "-" for v in (alabel, blabel, clabel)]
+    labels = _labels if any(v != "-" for v in _labels) else None
+
+    aliasdict = AliasSystem(
+        L=Alias(labels, name="alabel/blabel/clabel", sep="/", size=3),
+        c=Alias(panel, name="panel", sep=",", size=2),
+    ).merge(kwargs)
 
     # TODO(GMT>=6.5.0): Remove the patch for upstream bug fixed in GMT 6.5.0.
     # See https://github.com/GenericMappingTools/pygmt/pull/2138
     if Version(__gmt_version__) < Version("6.5.0") and isinstance(data, pd.DataFrame):
         data = data.to_numpy()
 
-    aliasdict = AliasSystem(
-        c=Alias(panel, name="panel", sep=",", size=2),
-    ).merge(kwargs)
-
     with Session() as lib:
         with lib.virtualfile_in(check_kind="vector", data=data) as vintbl:
             lib.call_module(

pygmt/src/timestamp.py

@@ -7,13 +7,13 @@
 
 from packaging.version import Version
 from pygmt._typing import AnchorCode
+from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session, __gmt_version__
-from pygmt.helpers import build_arg_list, kwargs_to_strings
+from pygmt.helpers import build_arg_list
 
 __doctest_skip__ = ["timestamp"]
 
 
-@kwargs_to_strings(offset="sequence")
 def timestamp(
     self,
     text: str | None = None,
@@ -78,39 +78,42 @@ def timestamp(
     """
     self._activate_figure()
 
-    # Build the options passed to the "plot" module
-    kwdict: dict = {"T": True, "U": ""}
-    if label is not None:
-        kwdict["U"] += f"{label}"
-    kwdict["U"] += f"+j{justify}"
+    if text is not None and len(str(text)) > 64:
+        msg = (
+            "Parameter 'text' expects a string no longer than 64 characters. "
+            "The given text string will be truncated to 64 characters."
+        )
+        warnings.warn(message=msg, category=RuntimeWarning, stacklevel=2)
+        text = str(text)[:64]
 
-    # TODO(GMT>=6.5.0): Remove the patch for upstream bug fixed in GMT 6.5.0.
-    if Version(__gmt_version__) < Version("6.5.0") and "/" not in str(offset):
-        # Giving a single offset doesn't work in GMT < 6.5.0.
-        # See https://github.com/GenericMappingTools/gmt/issues/7107.
-        offset = f"{offset}/{offset}"
-    kwdict["U"] += f"+o{offset}"
+    # TODO(GMT>=6.5.0): Remove the patch for upstream "offset" bug fixed in GMT 6.5.0.
+    # TODO(GMT>=6.5.0): Remove the workaround for the '+t' modifier added in GMT 6.5.0.
+    # Related issues:
+    # - https://github.com/GenericMappingTools/gmt/issues/7107
+    # - https://github.com/GenericMappingTools/gmt/pull/7127
+    if Version(__gmt_version__) < Version("6.5.0"):
+        if "/" not in str(offset):  # Giving a single offset doesn't work in GMT<6.5.0
+            offset = f"{offset}/{offset}"
+        if text is not None:
+            # Workaround for GMT<6.5.0 by overriding the 'timefmt' parameter and
+            # unsetting 'text'.
+            timefmt = str(text)
+            text = None
 
-    # The +t modifier was added in GMT 6.5.0.
-    # See https://github.com/GenericMappingTools/gmt/pull/7127.
-    if text is not None:
-        if len(str(text)) > 64:
-            msg = (
-                "Argument of 'text' must be no longer than 64 characters. "
-                "The given text string will be truncated to 64 characters."
-            )
-            warnings.warn(message=msg, category=RuntimeWarning, stacklevel=2)
-        # TODO(GMT>=6.5.0): Remove the workaround for the new '+t' modifier.
-        if Version(__gmt_version__) < Version("6.5.0"):
-            # Workaround for GMT<6.5.0 by overriding the 'timefmt' parameter
-            timefmt = text[:64]
-        else:
-            kwdict["U"] += f"+t{text}"
+    aliasdict = AliasSystem(
+        U=[
+            Alias(label, name="label"),
+            Alias(justify, name="justify", prefix="+j"),
+            Alias(offset, name="offset", prefix="+o", sep="/", size=2),
+            Alias(text, name="text", prefix="+t"),
+        ]
+    )
+    aliasdict["T"] = ""  # Add '-T' to the "plot" module.
 
     with Session() as lib:
         lib.call_module(
             module="plot",
             args=build_arg_list(
-                kwdict, confdict={"FONT_LOGO": font, "FORMAT_TIME_STAMP": timefmt}
+                aliasdict, confdict={"FONT_LOGO": font, "FORMAT_TIME_STAMP": timefmt}
             ),
         )