Migrate the 'projection' parameter to the new alias system (#4024)

Author: seisman

pygmt/src/basemap.py

@@ -2,14 +2,14 @@
 basemap - Plot base maps and frames.
 """
 
+from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
 
 
 @fmt_docstring
 @use_alias(
     R="region",
-    J="projection",
     Jz="zscale",
     JZ="zsize",
     B="frame",
@@ -24,7 +24,7 @@
     t="transparency",
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
-def basemap(self, **kwargs):
+def basemap(self, projection=None, **kwargs):
     r"""
     Plot base maps and frames.
 
@@ -39,6 +39,7 @@ def basemap(self, **kwargs):
     Full GMT docs at :gmt-docs:`basemap.html`.
 
     {aliases}
+       - J=projection
 
     Parameters
     ----------
@@ -83,5 +84,8 @@ def basemap(self, **kwargs):
     {transparency}
     """
     self._activate_figure()
+    aliasdict = AliasSystem(
+        J=Alias(projection, name="projection"),
+    ).merge(kwargs)
     with Session() as lib:
-        lib.call_module(module="basemap", args=build_arg_list(kwargs))
+        lib.call_module(module="basemap", args=build_arg_list(aliasdict))

pygmt/src/coast.py

@@ -4,6 +4,7 @@
 
 from typing import Literal
 
+from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers import (
@@ -28,7 +29,6 @@
     F="box",
     G="land",
     I="rivers",
-    J="projection",
     L="map_scale",
     N="borders",
     R="region",
@@ -42,6 +42,7 @@
 @kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
 def coast(
     self,
+    projection=None,
     resolution: Literal[
         "auto", "full", "high", "intermediate", "low", "crude", None
     ] = None,
@@ -67,6 +68,7 @@ def coast(
     Full GMT docs at :gmt-docs:`coast.html`.
 
     {aliases}
+       - J=projection
 
     Parameters
     ----------
@@ -214,5 +216,9 @@ def coast(
 
     kwargs["D"] = kwargs.get("D", _parse_coastline_resolution(resolution))
 
+    aliasdict = AliasSystem(
+        J=Alias(projection, name="projection"),
+    ).merge(kwargs)
+
     with Session() as lib:
-        lib.call_module(module="coast", args=build_arg_list(kwargs))
+        lib.call_module(module="coast", args=build_arg_list(aliasdict))

pygmt/src/colorbar.py

@@ -2,6 +2,7 @@
 colorbar - Plot gray scale or color scale bar.
 """
 
+from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias
 
@@ -16,7 +17,6 @@
     F="box",
     G="truncate",
     I="shading",
-    J="projection",
     L="equalsize",
     Q="log",
     R="region",
@@ -30,7 +30,7 @@
 @kwargs_to_strings(
     R="sequence", G="sequence", I="sequence", c="sequence_comma", p="sequence"
 )
-def colorbar(self, **kwargs):
+def colorbar(self, projection=None, **kwargs):
     r"""
     Plot gray scale or color scale bar.
 
@@ -45,6 +45,7 @@ def colorbar(self, **kwargs):
     Full GMT docs at :gmt-docs:`colorbar.html`.
 
     {aliases}
+       - J=projection
 
     Parameters
     ----------
@@ -145,5 +146,9 @@ def colorbar(self, **kwargs):
     >>> fig.show()
     """
     self._activate_figure()
+
+    aliasdict = AliasSystem(
+        J=Alias(projection, name="projection"),
+    ).merge(kwargs)
     with Session() as lib:
-        lib.call_module(module="colorbar", args=build_arg_list(kwargs))
+        lib.call_module(module="colorbar", args=build_arg_list(aliasdict))

pygmt/src/contour.py

@@ -3,6 +3,7 @@
 """
 
 from pygmt._typing import PathLike, TableLike
+from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.helpers import (
     build_arg_list,
@@ -19,7 +20,6 @@
     B="frame",
     C="levels",
     G="label_placement",
-    J="projection",
     L="triangular_mesh_pen",
     N="no_clip",
     R="region",
@@ -39,7 +39,13 @@
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence")
 def contour(
-    self, data: PathLike | TableLike | None = None, x=None, y=None, z=None, **kwargs
+    self,
+    data: PathLike | TableLike | None = None,
+    x=None,
+    y=None,
+    z=None,
+    projection=None,
+    **kwargs,
 ):
     r"""
     Contour table data by direct triangulation.
@@ -52,6 +58,7 @@ def contour(
     Full GMT docs at :gmt-docs:`contour.html`.
 
     {aliases}
+       - J=projection
 
     Parameters
     ----------
@@ -146,10 +153,14 @@ def contour(
             else:  # Multiple levels
                 kwargs[arg] = ",".join(f"{item}" for item in kwargs[arg])
 
+    aliasdict = AliasSystem(
+        J=Alias(projection, name="projection"),
+    ).merge(kwargs)
+
     with Session() as lib:
         with lib.virtualfile_in(
             check_kind="vector", data=data, x=x, y=y, z=z, mincols=3
         ) as vintbl:
             lib.call_module(
-                module="contour", args=build_arg_list(kwargs, infile=vintbl)
+                module="contour", args=build_arg_list(aliasdict, infile=vintbl)
             )

pygmt/src/grdcontour.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.helpers import (
     build_arg_list,
@@ -24,7 +25,6 @@
     B="frame",
     C="levels",
     G="label_placement",
-    J="projection",
     L="limit",
     Q="cut",
     R="region",
@@ -38,7 +38,7 @@
     t="transparency",
 )
 @kwargs_to_strings(R="sequence", L="sequence", c="sequence_comma", p="sequence")
-def grdcontour(self, grid: PathLike | xr.DataArray, **kwargs):
+def grdcontour(self, grid: PathLike | xr.DataArray, projection=None, **kwargs):
     r"""
     Make contour map using a grid.
 
@@ -47,6 +47,7 @@ def grdcontour(self, grid: PathLike | xr.DataArray, **kwargs):
     Full GMT docs at :gmt-docs:`grdcontour.html`.
 
     {aliases}
+       - J=projection
 
     Parameters
     ----------
@@ -151,8 +152,12 @@ def grdcontour(self, grid: PathLike | xr.DataArray, **kwargs):
             else:  # Multiple levels
                 kwargs[arg] = ",".join(f"{item}" for item in kwargs[arg])
 
+    aliasdict = AliasSystem(
+        J=Alias(projection, name="projection"),
+    ).merge(kwargs)
+
     with Session() as lib:
         with lib.virtualfile_in(check_kind="raster", data=grid) as vingrd:
             lib.call_module(
-                module="grdcontour", args=build_arg_list(kwargs, infile=vingrd)
+                module="grdcontour", args=build_arg_list(aliasdict, infile=vingrd)
             )

pygmt/src/grdcut.py

@@ -6,6 +6,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 GMTTypeError, GMTValueError
 from pygmt.helpers import (
@@ -22,7 +23,6 @@
 @fmt_docstring
 @use_alias(
     R="region",
-    J="projection",
     N="extend",
     S="circ_subregion",
     V="verbose",
@@ -34,6 +34,7 @@ def grdcut(
     grid: PathLike | xr.DataArray,
     kind: Literal["grid", "image"] = "grid",
     outgrid: PathLike | None = None,
+    projection=None,
     **kwargs,
 ) -> xr.DataArray | None:
     r"""
@@ -51,6 +52,7 @@ def grdcut(
     Full GMT docs at :gmt-docs:`grdcut.html`.
 
     {aliases}
+      - J=projection
 
     Parameters
     ----------
@@ -124,13 +126,19 @@ def grdcut(
         case _:
             raise GMTTypeError(type(grid))
 
+    aliasdict = AliasSystem(
+        J=Alias(projection, name="projection"),
+    ).merge(kwargs)
+
     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))
+            aliasdict["G"] = voutgrd
+            lib.call_module(
+                module="grdcut", args=build_arg_list(aliasdict, infile=vingrd)
+            )
             return lib.virtualfile_to_raster(
                 vfname=voutgrd, kind=outkind, outgrid=outgrid
             )

pygmt/src/grdimage.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 (
@@ -24,7 +25,6 @@
     E="dpi",
     G="bitcolor",
     I="shading",
-    J="projection",
     M="monochrome",
     N="no_clip",
     Q="nan_transparent",
@@ -38,7 +38,7 @@
     x="cores",
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", p="sequence")
-def grdimage(self, grid: PathLike | xr.DataArray, **kwargs):
+def grdimage(self, grid: PathLike | xr.DataArray, projection=None, **kwargs):
     r"""
     Project and plot grids or images.
 
@@ -73,6 +73,7 @@ def grdimage(self, grid: PathLike | xr.DataArray, **kwargs):
     Full GMT docs at :gmt-docs:`grdimage.html`.
 
     {aliases}
+       - J=projection
 
     Parameters
     ----------
@@ -166,14 +167,18 @@ def grdimage(self, grid: PathLike | xr.DataArray, **kwargs):
         )
         raise GMTInvalidInput(msg)
 
+    aliasdict = AliasSystem(
+        J=Alias(projection, name="projection"),
+    ).merge(kwargs)
+
     with Session() as lib:
         with (
             lib.virtualfile_in(check_kind="raster", data=grid) as vingrd,
             lib.virtualfile_in(
                 check_kind="raster", data=kwargs.get("I"), required=False
             ) as vshadegrid,
         ):
-            kwargs["I"] = vshadegrid
+            aliasdict["I"] = vshadegrid
             lib.call_module(
-                module="grdimage", args=build_arg_list(kwargs, infile=vingrd)
+                module="grdimage", args=build_arg_list(aliasdict, infile=vingrd)
             )