makecpt/grd2cpt: Refactor parameters truncate/overrule_bg/no_bg/log/continuous to the new alias system (#4061)

Co-authored-by: Michael Grund <[email protected]>

Author: seisman

pygmt/src/grd2cpt.py

@@ -4,6 +4,7 @@
 
 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, use_alias
@@ -18,22 +19,25 @@
     D="background",
     F="color_model",
     E="nlevels",
-    G="truncate",
     H="output",
     I="reverse",
     L="limit",
-    M="overrule_bg",
-    N="no_bg",
-    Q="log",
     R="region",
     T="series",
     V="verbose",
     W="categorical",
     Ww="cyclic",
-    Z="continuous",
 )
-@kwargs_to_strings(G="sequence", L="sequence", R="sequence", T="sequence")
-def grd2cpt(grid: PathLike | xr.DataArray, **kwargs):
+@kwargs_to_strings(L="sequence", R="sequence", T="sequence")
+def grd2cpt(
+    grid: PathLike | xr.DataArray,
+    truncate: tuple[float, float] | None = None,
+    overrule_bg: bool = False,
+    no_bg: bool = False,
+    log: bool = False,
+    continuous: bool = False,
+    **kwargs,
+):
     r"""
     Make linear or histogram-equalized color palette table from grid.
 
@@ -78,6 +82,11 @@ def grd2cpt(grid: PathLike | xr.DataArray, **kwargs):
     Full GMT docs at :gmt-docs:`grd2cpt.html`.
 
     {aliases}
+       - G = truncate
+       - M = overrule_bg
+       - N = no_bg
+       - Q = log
+       - Z = continuous
 
     Parameters
     ----------
@@ -124,12 +133,12 @@ def grd2cpt(grid: PathLike | xr.DataArray, **kwargs):
         refers to the number of such boundaries and not the number of slices.
         For details on array creation, see
         :gmt-docs:`makecpt.html#generate-1d-array`.
-    truncate : list or str
-        *zlow/zhigh*.
-        Truncate the incoming CPT so that the lowest and highest z-levels are
-        to *zlow* and *zhigh*. If one of these equal NaN then we leave that
-        end of the CPT alone. The truncation takes place before any resampling.
-        See also :gmt-docs:`reference/features.html#manipulating-cpts`.
+    truncate
+        (*zlow*, *zhigh*).
+        Truncate the incoming CPT so that the lowest and highest z-levels are to *zlow*
+        and *zhigh*. If one of these equals NaN, then we leave that end of the CPT
+        alone. The truncation takes place before any resampling. See also
+        :gmt-docs:`reference/features.html#manipulating-cpts`.
     output : str
         Optional. The file name with extension .cpt to store the generated CPT
         file. If not given or ``False`` [Default], saves the CPT as the current
@@ -142,22 +151,22 @@ def grd2cpt(grid: PathLike | xr.DataArray, **kwargs):
         happens before ``truncate`` and ``series`` values are used so the
         latter must be compatible with the changed z-range. See also
         :gmt-docs:`reference/features.html#manipulating-cpts`.
-    overrule_bg : str
-        Overrule background, foreground, and NaN colors specified in the master
-        CPT with the values of the parameters :gmt-term:`COLOR_BACKGROUND`,
-        :gmt-term:`COLOR_FOREGROUND`, and :gmt-term:`COLOR_NAN` specified in
-        the :gmt-docs:`gmt.conf <gmt.conf>` file. When combined with
-        ``background``, only :gmt-term:`COLOR_NAN` is considered.
-    no_bg : bool
-        Do not write out the background, foreground, and NaN-color fields
-        [Default will write them, i.e. ``no_bg=False``].
-    log : bool
-        For logarithmic interpolation scheme with input given as logarithms.
-        Expects input z-values provided via ``series`` to be log10(*z*),
-        assigns colors, and writes out *z*.
-    continuous : bool
-        Force a continuous CPT when building from a list of colors and a list
-        of z-values [Default is None, i.e. discrete values].
+    overrule_bg
+        Overrule background, foreground, and NaN colors specified in the master CPT with
+        the values of the parameters :gmt-term:`COLOR_BACKGROUND`,
+        :gmt-term:`COLOR_FOREGROUND`, and :gmt-term:`COLOR_NAN` specified in the
+        :gmt-docs:`gmt.conf <gmt.conf>` file or by :func:`pygmt.config`. When combined
+        with ``background``, only :gmt-term:`COLOR_NAN` is considered.
+    no_bg
+        Do not write out the background, foreground, and NaN-color fields [Default will
+        write them, i.e. ``no_bg=False``].
+    log
+        For logarithmic interpolation scheme with input given as logarithms. Expects
+        input z-values provided via ``series`` to be log10(*z*), assigns colors, and
+        writes out *z*.
+    continuous
+        Force a continuous CPT when building from a list of colors and a list of
+        z-values [Default is False, i.e. discrete CPT].
     categorical : bool
         Do not interpolate the input color table but pick the output colors
         starting at the beginning of the color table, until colors for all
@@ -190,9 +199,17 @@ def grd2cpt(grid: PathLike | xr.DataArray, **kwargs):
     if (output := kwargs.pop("H", None)) is not None:
         kwargs["H"] = True
 
+    aliasdict = AliasSystem(
+        G=Alias(truncate, name="truncate", sep="/", size=2),
+        M=Alias(overrule_bg, name="overrule_bg"),
+        N=Alias(no_bg, name="no_bg"),
+        Q=Alias(log, name="log"),
+        Z=Alias(continuous, name="continuous"),
+    ).merge(kwargs)
+
     with Session() as lib:
         with lib.virtualfile_in(check_kind="raster", data=grid) as vingrd:
             lib.call_module(
                 module="grd2cpt",
-                args=build_arg_list(kwargs, infile=vingrd, outfile=output),
+                args=build_arg_list(aliasdict, infile=vingrd, outfile=output),
             )

pygmt/src/makecpt.py

@@ -2,6 +2,7 @@
 makecpt - Make GMT color palette tables.
 """
 
+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, use_alias
@@ -13,20 +14,22 @@
     C="cmap",
     D="background",
     F="color_model",
-    G="truncate",
     H="output",
     I="reverse",
-    M="overrule_bg",
-    N="no_bg",
-    Q="log",
     T="series",
     V="verbose",
     W="categorical",
     Ww="cyclic",
-    Z="continuous",
 )
-@kwargs_to_strings(T="sequence", G="sequence")
-def makecpt(**kwargs):
+@kwargs_to_strings(T="sequence")
+def makecpt(
+    truncate: tuple[float, float] | None = None,
+    overrule_bg: bool = False,
+    no_bg: bool = False,
+    log: bool = False,
+    continuous: bool = False,
+    **kwargs,
+):
     r"""
     Make GMT color palette tables.
 
@@ -67,6 +70,11 @@ def makecpt(**kwargs):
     Full GMT docs at :gmt-docs:`makecpt.html`.
 
     {aliases}
+       - G = truncate
+       - M = overrule_bg
+       - N = no_bg
+       - Q = log
+       - Z = continuous
 
     Parameters
     ----------
@@ -108,12 +116,12 @@ def makecpt(**kwargs):
         refers to the number of such boundaries and not the number of slices.
         For details on array creation, see
         :gmt-docs:`makecpt.html#generate-1d-array`.
-    truncate : list or str
-        *zlow/zhigh*.
-        Truncate the incoming CPT so that the lowest and highest z-levels are
-        to *zlow* and *zhigh*. If one of these equal NaN then we leave that
-        end of the CPT alone. The truncation takes place before any resampling.
-        See also :gmt-docs:`reference/features.html#manipulating-cpts`.
+    truncate
+        (*zlow*, *zhigh*).
+        Truncate the incoming CPT so that the lowest and highest z-levels are to *zlow*
+        and *zhigh*. If one of these equals NaN, then we leave that end of the CPT
+        alone. The truncation takes place before any resampling. See also
+        :gmt-docs:`reference/features.html#manipulating-cpts`.
     output : str
         Optional. The file name with extension .cpt to store the generated CPT
         file. If not given or ``False`` [Default], saves the CPT as the current
@@ -128,22 +136,22 @@ def makecpt(**kwargs):
         the ``truncate`` and ``series`` values are used, so the latter must be
         compatible with the changed z-range. See also
         :gmt-docs:`reference/features.html#manipulating-cpts`.
-    overrule_bg : str
-        Overrule background, foreground, and NaN colors specified in the master
-        CPT with the values of the parameters :gmt-term:`COLOR_BACKGROUND`,
-        :gmt-term:`COLOR_FOREGROUND`, and :gmt-term:`COLOR_NAN` specified in
-        the :gmt-docs:`gmt.conf <gmt.conf>` file. When combined with
-        ``background``, only :gmt-term:`COLOR_NAN` is considered.
-    no_bg : bool
-        Do not write out the background, foreground, and NaN-color fields
-        [Default will write them, i.e. ``no_bg=False``].
-    log : bool
-        For logarithmic interpolation scheme with input given as logarithms.
-        Expects input z-values provided via ``series`` to be log10(*z*),
-        assigns colors, and writes out *z*.
-    continuous : bool
-        Force a continuous CPT when building from a list of colors and a list
-        of z-values [Default is None, i.e. discrete values].
+    overrule_bg
+        Overrule background, foreground, and NaN colors specified in the master CPT with
+        the values of the parameters :gmt-term:`COLOR_BACKGROUND`,
+        :gmt-term:`COLOR_FOREGROUND`, and :gmt-term:`COLOR_NAN` specified in the
+        :gmt-docs:`gmt.conf <gmt.conf>` file or by :func:`pygmt.config`. When combined
+        with ``background``, only :gmt-term:`COLOR_NAN` is considered.
+    no_bg
+        Do not write out the background, foreground, and NaN-color fields [Default will
+        write them, i.e. ``no_bg=False``].
+    log
+        For logarithmic interpolation scheme with input given as logarithms. Expects
+        input z-values provided via ``series`` to be log10(*z*), assigns colors, and
+        writes out *z*.
+    continuous
+        Force a continuous CPT when building from a list of colors and a list of
+        z-values [Default is False, i.e. discrete CPT].
     {verbose}
     categorical : bool
         Do not interpolate the input color table but pick the output colors
@@ -162,5 +170,15 @@ def makecpt(**kwargs):
     if (output := kwargs.pop("H", None)) is not None:
         kwargs["H"] = True
 
+    aliasdict = AliasSystem(
+        G=Alias(truncate, name="truncate", sep="/", size=2),
+        M=Alias(overrule_bg, name="overrule_bg"),
+        N=Alias(no_bg, name="no_bg"),
+        Q=Alias(log, name="log"),
+        Z=Alias(continuous, name="continuous"),
+    ).merge(kwargs)
+
     with Session() as lib:
-        lib.call_module(module="makecpt", args=build_arg_list(kwargs, outfile=output))
+        lib.call_module(
+            module="makecpt", args=build_arg_list(aliasdict, outfile=output)
+        )