Migrate the panel parameter to the new alias system

pygmt/alias.py

@@ -226,8 +226,10 @@ class AliasSystem(UserDict):
     ...         ],
     ...         B=Alias(frame, name="frame"),
     ...         D=Alias(repeat, name="repeat"),
-    ...         c=Alias(panel, name="panel", sep=","),
-    ...     ).merge(kwargs)
+    ...     ).add_common(
+    ...         c=panel,
+    ...     )
+    ...     aliasdict.merge(kwargs)
     ...     return build_arg_list(aliasdict)
     >>> func(
     ...     "infile",
@@ -268,6 +270,21 @@ def __init__(self, **kwargs):
                 kwdict[option] = aliases._value
         super().__init__(kwdict)
 
+    def add_common(self, **kwargs):
+        """
+        Add common parameters to the alias dictionary.
+        """
+        for key, value in kwargs.items():
+            match key:
+                case "c":
+                    alias = Alias(value, name="panel", sep=",", size=2)
+                case _:
+                    raise GMTValueError(key, description="common parameter")
+            self.aliasdict[key] = alias
+            if alias._value is not None:
+                self[key] = alias._value
+        return self
+
     def merge(self, kwargs: Mapping[str, Any]):
         """
         Update the dictionary with additional keyword arguments.

pygmt/helpers/decorators.py

@@ -261,7 +261,7 @@
             :gmt-docs:`gmt.html#grd-inout-full` for the available modifiers.
         """,
     "panel": r"""
-        panel : bool, int, or list
+        panel
             Select a specific subplot panel. Only allowed when used in
             :meth:`Figure.subplot` mode.
 

pygmt/src/basemap.py

@@ -18,13 +18,14 @@
     Td="rose",
     Tm="compass",
     V="verbose",
-    c="panel",
     f="coltypes",
     p="perspective",
     t="transparency",
 )
-@kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
-def basemap(self, projection=None, **kwargs):
+@kwargs_to_strings(R="sequence", p="sequence")
+def basemap(
+    self, projection=None, panel: int | tuple[int, int] | bool = False, **kwargs
+):
     r"""
     Plot base maps and frames.
 
@@ -40,6 +41,7 @@ def basemap(self, projection=None, **kwargs):
 
     {aliases}
        - J = projection
+       - c = panel
 
     Parameters
     ----------
@@ -84,8 +86,13 @@ def basemap(self, projection=None, **kwargs):
     {transparency}
     """
     self._activate_figure()
+
     aliasdict = AliasSystem(
         J=Alias(projection, name="projection"),
-    ).merge(kwargs)
+    ).add_common(
+        c=panel,
+    )
+    aliasdict.merge(kwargs)
+
     with Session() as lib:
         lib.call_module(module="basemap", args=build_arg_list(aliasdict))

pygmt/src/coast.py

@@ -33,17 +33,17 @@
     S="water",
     V="verbose",
     W="shorelines",
-    c="panel",
     p="perspective",
     t="transparency",
 )
-@kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
+@kwargs_to_strings(R="sequence", p="sequence")
 def coast(
     self,
     projection=None,
     resolution: Literal[
         "auto", "full", "high", "intermediate", "low", "crude", None
     ] = None,
+    panel: int | tuple[int, int] | bool = False,
     **kwargs,
 ):
     r"""
@@ -68,6 +68,7 @@ def coast(
     {aliases}
        - D = resolution
        - J = projection
+       - c = panel
 
     Parameters
     ----------
@@ -227,7 +228,10 @@ def coast(
             },
         ),
         J=Alias(projection, name="projection"),
-    ).merge(kwargs)
+    ).add_common(
+        c=panel,
+    )
+    aliasdict.merge(kwargs)
 
     with Session() as lib:
         lib.call_module(module="coast", args=build_arg_list(aliasdict))

pygmt/src/colorbar.py

@@ -23,14 +23,13 @@
     V="verbose",
     W="scale",
     Z="zfile",
-    c="panel",
     p="perspective",
     t="transparency",
 )
-@kwargs_to_strings(
-    R="sequence", G="sequence", I="sequence", c="sequence_comma", p="sequence"
-)
-def colorbar(self, projection=None, **kwargs):
+@kwargs_to_strings(R="sequence", G="sequence", I="sequence", p="sequence")
+def colorbar(
+    self, projection=None, panel: int | tuple[int, int] | bool = False, **kwargs
+):
     r"""
     Plot gray scale or color scale bar.
 
@@ -46,6 +45,7 @@ def colorbar(self, projection=None, **kwargs):
 
     {aliases}
        - J = projection
+       - c = panel
 
     Parameters
     ----------
@@ -149,6 +149,10 @@ def colorbar(self, projection=None, **kwargs):
 
     aliasdict = AliasSystem(
         J=Alias(projection, name="projection"),
-    ).merge(kwargs)
+    ).add_common(
+        c=panel,
+    )
+    aliasdict.merge(kwargs)
+
     with Session() as lib:
         lib.call_module(module="colorbar", args=build_arg_list(aliasdict))

pygmt/src/contour.py

@@ -27,7 +27,6 @@
     V="verbose",
     W="pen",
     b="binary",
-    c="panel",
     d="nodata",
     e="find",
     f="coltypes",
@@ -37,14 +36,15 @@
     p="perspective",
     t="transparency",
 )
-@kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence")
+@kwargs_to_strings(R="sequence", i="sequence_comma", p="sequence")
 def contour(
     self,
     data: PathLike | TableLike | None = None,
     x=None,
     y=None,
     z=None,
     projection=None,
+    panel: int | tuple[int, int] | bool = False,
     **kwargs,
 ):
     r"""
@@ -59,6 +59,7 @@ def contour(
 
     {aliases}
        - J = projection
+       - c = panel
 
     Parameters
     ----------
@@ -155,7 +156,10 @@ def contour(
 
     aliasdict = AliasSystem(
         J=Alias(projection, name="projection"),
-    ).merge(kwargs)
+    ).add_common(
+        c=panel,
+    )
+    aliasdict.merge(kwargs)
 
     with Session() as lib:
         with lib.virtualfile_in(

pygmt/src/grdcontour.py

@@ -32,13 +32,18 @@
     V="verbose",
     W="pen",
     l="label",
-    c="panel",
     f="coltypes",
     p="perspective",
     t="transparency",
 )
-@kwargs_to_strings(R="sequence", L="sequence", c="sequence_comma", p="sequence")
-def grdcontour(self, grid: PathLike | xr.DataArray, projection=None, **kwargs):
+@kwargs_to_strings(R="sequence", L="sequence", p="sequence")
+def grdcontour(
+    self,
+    grid: PathLike | xr.DataArray,
+    projection=None,
+    panel: int | tuple[int, int] | bool = False,
+    **kwargs,
+):
     r"""
     Make contour map using a grid.
 
@@ -48,6 +53,7 @@ def grdcontour(self, grid: PathLike | xr.DataArray, projection=None, **kwargs):
 
     {aliases}
        - J = projection
+       - c = panel
 
     Parameters
     ----------
@@ -154,7 +160,10 @@ def grdcontour(self, grid: PathLike | xr.DataArray, projection=None, **kwargs):
 
     aliasdict = AliasSystem(
         J=Alias(projection, name="projection"),
-    ).merge(kwargs)
+    ).add_common(
+        c=panel,
+    )
+    aliasdict.merge(kwargs)
 
     with Session() as lib:
         with lib.virtualfile_in(check_kind="raster", data=grid) as vingrd:

pygmt/src/grdimage.py

@@ -31,14 +31,19 @@
     R="region",
     V="verbose",
     n="interpolation",
-    c="panel",
     f="coltypes",
     p="perspective",
     t="transparency",
     x="cores",
 )
-@kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
-def grdimage(self, grid: PathLike | xr.DataArray, projection=None, **kwargs):
+@kwargs_to_strings(R="sequence", p="sequence")
+def grdimage(
+    self,
+    grid: PathLike | xr.DataArray,
+    projection=None,
+    panel: int | tuple[int, int] | bool = False,
+    **kwargs,
+):
     r"""
     Project and plot grids or images.
 
@@ -74,6 +79,7 @@ def grdimage(self, grid: PathLike | xr.DataArray, projection=None, **kwargs):
 
     {aliases}
        - J = projection
+       - c = panel
 
     Parameters
     ----------
@@ -169,7 +175,10 @@ def grdimage(self, grid: PathLike | xr.DataArray, projection=None, **kwargs):
 
     aliasdict = AliasSystem(
         J=Alias(projection, name="projection"),
-    ).merge(kwargs)
+    ).add_common(
+        c=panel,
+    )
+    aliasdict.merge(kwargs)
 
     with Session() as lib:
         with (

pygmt/src/grdview.py

@@ -26,14 +26,19 @@
     Wf="facadepen",
     I="shading",
     V="verbose",
-    c="panel",
     f="coltypes",
     n="interpolation",
     p="perspective",
     t="transparency",
 )
-@kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
-def grdview(self, grid: PathLike | xr.DataArray, projection=None, **kwargs):
+@kwargs_to_strings(R="sequence", p="sequence")
+def grdview(
+    self,
+    grid: PathLike | xr.DataArray,
+    projection=None,
+    panel: int | tuple[int, int] | bool = False,
+    **kwargs,
+):
     r"""
     Create 3-D perspective image or surface mesh from a grid.
 
@@ -47,6 +52,7 @@ def grdview(self, grid: PathLike | xr.DataArray, projection=None, **kwargs):
 
     {aliases}
        - J = projection
+       - c = panel
 
     Parameters
     ----------
@@ -145,7 +151,10 @@ def grdview(self, grid: PathLike | xr.DataArray, projection=None, **kwargs):
 
     aliasdict = AliasSystem(
         J=Alias(projection, name="projection"),
-    ).merge(kwargs)
+    ).add_common(
+        c=panel,
+    )
+    aliasdict.merge(kwargs)
 
     with Session() as lib:
         with (

pygmt/src/histogram.py

@@ -27,7 +27,6 @@
     W="pen",
     Z="histtype",
     b="binary",
-    c="panel",
     d="nodata",
     e="find",
     h="header",
@@ -37,17 +36,22 @@
     t="transparency",
     w="wrap",
 )
-@kwargs_to_strings(
-    R="sequence", T="sequence", c="sequence_comma", i="sequence_comma", p="sequence"
-)
-def histogram(self, data: PathLike | TableLike, projection=None, **kwargs):
+@kwargs_to_strings(R="sequence", T="sequence", i="sequence_comma", p="sequence")
+def histogram(
+    self,
+    data: PathLike | TableLike,
+    projection=None,
+    panel: int | tuple[int, int] | bool = False,
+    **kwargs,
+):
     r"""
     Calculate and plot histograms.
 
     Full GMT docs at :gmt-docs:`histogram.html`.
 
     {aliases}
        - J = projection
+       - c = panel
 
     Parameters
     ----------
@@ -140,7 +144,10 @@ def histogram(self, data: PathLike | TableLike, projection=None, **kwargs):
 
     aliasdict = AliasSystem(
         J=Alias(projection, name="projection"),
-    ).merge(kwargs)
+    ).add_common(
+        c=panel,
+    )
+    aliasdict.merge(kwargs)
 
     with Session() as lib:
         with lib.virtualfile_in(check_kind="vector", data=data) as vintbl: