AliasSystem: Migrate the region parameter to the new alias system

pygmt/alias.py

@@ -300,6 +300,10 @@ def add_common(self, **kwargs):
         """
         for key, value in kwargs.items():
             match key:
+                case "J":
+                    alias = Alias(value, name="projection")
+                case "R":
+                    alias = Alias(value, name="region", sep="/", size=(4, 6))
                 case "V":
                     alias = Alias(
                         value,
@@ -314,8 +318,6 @@ def add_common(self, **kwargs):
                             "debug": "d",
                         },
                     )
-                case "J":
-                    alias = Alias(value, name="projection")
                 case "c":
                     alias = Alias(value, name="panel", sep=",", size=2)
                 case "t":

pygmt/src/basemap.py

@@ -2,6 +2,7 @@
 basemap - Plot base maps and frames.
 """
 
+from collections.abc import Sequence
 from typing import Literal
 
 from pygmt.alias import AliasSystem
@@ -11,7 +12,6 @@
 
 @fmt_docstring
 @use_alias(
-    R="region",
     Jz="zscale",
     JZ="zsize",
     B="frame",
@@ -22,10 +22,11 @@
     f="coltypes",
     p="perspective",
 )
-@kwargs_to_strings(R="sequence", p="sequence")
+@kwargs_to_strings(p="sequence")
 def basemap(
     self,
     projection=None,
+    region: Sequence[float | str] | str | None = None,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | tuple[int, int] | bool = False,
@@ -47,6 +48,7 @@ def basemap(
 
     {aliases}
        - J = projection
+       - R = region
        - V = verbose
        - c = panel
        - t = transparency
@@ -97,6 +99,7 @@ def basemap(
 
     aliasdict = AliasSystem().add_common(
         J=projection,
+        R=region,
         V=verbose,
         c=panel,
         t=transparency,

pygmt/src/binstats.py

@@ -2,6 +2,7 @@
 binstats - Bin spatial data and determine statistics per bin.
 """
 
+from collections.abc import Sequence
 from typing import Literal
 
 import xarray as xr
@@ -16,7 +17,6 @@
     E="empty",
     I="spacing",
     N="normalize",
-    R="region",
     S="search_radius",
     W="weight",
     a="aspatial",
@@ -25,7 +25,7 @@
     i="incols",
     r="registration",
 )
-@kwargs_to_strings(I="sequence", R="sequence", i="sequence_comma")
+@kwargs_to_strings(I="sequence", i="sequence_comma")
 def binstats(
     data: PathLike | TableLike,
     outgrid: PathLike | None = None,
@@ -48,6 +48,7 @@ def binstats(
         "sum",
     ] = "number",
     quantile_value: float = 50,
+    region: Sequence[float | str] | str | None = None,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     **kwargs,
@@ -67,6 +68,7 @@ def binstats(
 
     {aliases}
        - C = statistic
+       - R = region
        - V = verbose
 
     Parameters
@@ -154,6 +156,7 @@ def binstats(
             },
         ),
     ).add_common(
+        R=region,
         V=verbose,
     )
     aliasdict.merge(kwargs)

pygmt/src/blockm.py

@@ -2,6 +2,7 @@
 blockm - Block average (x, y, z) data tables by mean, median, or mode estimation.
 """
 
+from collections.abc import Sequence
 from typing import Literal
 
 import numpy as np
@@ -73,7 +74,6 @@ def _blockm(
 @fmt_docstring
 @use_alias(
     I="spacing",
-    R="region",
     S="summary",
     a="aspatial",
     b="binary",
@@ -86,14 +86,15 @@ def _blockm(
     r="registration",
     w="wrap",
 )
-@kwargs_to_strings(I="sequence", R="sequence", i="sequence_comma", o="sequence_comma")
+@kwargs_to_strings(I="sequence", i="sequence_comma", o="sequence_comma")
 def blockmean(
     data: PathLike | TableLike | None = None,
     x=None,
     y=None,
     z=None,
     output_type: Literal["pandas", "numpy", "file"] = "pandas",
     outfile: PathLike | None = None,
+    region: Sequence[float | str] | str | None = None,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     **kwargs,
@@ -113,6 +114,7 @@ def blockmean(
     Full GMT docs at :gmt-docs:`blockmean.html`.
 
     {aliases}
+       - R = region
        - V = verbose
 
     Parameters
@@ -166,6 +168,7 @@ def blockmean(
     >>> data_bmean = pygmt.blockmean(data=data, region=[245, 255, 20, 30], spacing="5m")
     """
     aliasdict = AliasSystem().add_common(
+        R=region,
         V=verbose,
     )
     aliasdict.merge(kwargs)
@@ -185,7 +188,6 @@ def blockmean(
 @fmt_docstring
 @use_alias(
     I="spacing",
-    R="region",
     a="aspatial",
     b="binary",
     d="nodata",
@@ -197,14 +199,15 @@ def blockmean(
     r="registration",
     w="wrap",
 )
-@kwargs_to_strings(I="sequence", R="sequence", i="sequence_comma", o="sequence_comma")
+@kwargs_to_strings(I="sequence", i="sequence_comma", o="sequence_comma")
 def blockmedian(
     data: PathLike | TableLike | None = None,
     x=None,
     y=None,
     z=None,
     output_type: Literal["pandas", "numpy", "file"] = "pandas",
     outfile: PathLike | None = None,
+    region: Sequence[float | str] | str | None = None,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     **kwargs,
@@ -224,6 +227,7 @@ def blockmedian(
     Full GMT docs at :gmt-docs:`blockmedian.html`.
 
     {aliases}
+       - R = region
        - V = verbose
 
     Parameters
@@ -271,6 +275,7 @@ def blockmedian(
     ... )
     """
     aliasdict = AliasSystem().add_common(
+        R=region,
         V=verbose,
     )
     aliasdict.merge(kwargs)
@@ -290,7 +295,6 @@ def blockmedian(
 @fmt_docstring
 @use_alias(
     I="spacing",
-    R="region",
     a="aspatial",
     b="binary",
     d="nodata",
@@ -302,14 +306,15 @@ def blockmedian(
     r="registration",
     w="wrap",
 )
-@kwargs_to_strings(I="sequence", R="sequence", i="sequence_comma", o="sequence_comma")
+@kwargs_to_strings(I="sequence", i="sequence_comma", o="sequence_comma")
 def blockmode(
     data: PathLike | TableLike | None = None,
     x=None,
     y=None,
     z=None,
     output_type: Literal["pandas", "numpy", "file"] = "pandas",
     outfile: PathLike | None = None,
+    region: Sequence[float | str] | str | None = None,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     **kwargs,
@@ -329,6 +334,7 @@ def blockmode(
     Full GMT docs at :gmt-docs:`blockmode.html`.
 
     {aliases}
+       - R = region
        - V = verbose
 
     Parameters
@@ -374,6 +380,7 @@ def blockmode(
     >>> data_bmode = pygmt.blockmode(data=data, region=[245, 255, 20, 30], spacing="5m")
     """
     aliasdict = AliasSystem().add_common(
+        R=region,
         V=verbose,
     )
     aliasdict.merge(kwargs)

pygmt/src/coast.py

@@ -2,6 +2,7 @@
 coast - Plot continents, countries, shorelines, rivers, and borders.
 """
 
+from collections.abc import Sequence
 from typing import Literal
 
 from pygmt.alias import Alias, AliasSystem
@@ -29,19 +30,19 @@
     I="rivers",
     L="map_scale",
     N="borders",
-    R="region",
     S="water",
     W="shorelines",
     p="perspective",
 )
-@kwargs_to_strings(R="sequence", p="sequence")
+@kwargs_to_strings(p="sequence")
 def coast(
     self,
     projection=None,
     resolution: Literal[
         "auto", "full", "high", "intermediate", "low", "crude", None
     ] = None,
     box: Box | bool = False,
+    region: Sequence[float | str] | str | None = None,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | tuple[int, int] | bool = False,
@@ -71,6 +72,7 @@ def coast(
        - D = resolution
        - F = box
        - J = projection
+       - R = region
        - V = verbose
        - c = panel
        - t = transparency
@@ -222,6 +224,7 @@ def coast(
         F=Alias(box, name="box"),
     ).add_common(
         J=projection,
+        R=region,
         V=verbose,
         c=panel,
         t=transparency,

pygmt/src/colorbar.py

@@ -2,6 +2,7 @@
 colorbar - Plot gray scale or color scale bar.
 """
 
+from collections.abc import Sequence
 from typing import Literal
 
 from pygmt.alias import Alias, AliasSystem
@@ -21,16 +22,16 @@
     I="shading",
     L="equalsize",
     Q="log",
-    R="region",
     W="scale",
     Z="zfile",
     p="perspective",
 )
-@kwargs_to_strings(R="sequence", G="sequence", I="sequence", p="sequence")
+@kwargs_to_strings(G="sequence", I="sequence", p="sequence")
 def colorbar(
     self,
     projection=None,
     box: Box | bool = False,
+    region: Sequence[float | str] | str | None = None,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | tuple[int, int] | bool = False,
@@ -53,6 +54,7 @@ def colorbar(
     {aliases}
        - F = box
        - J = projection
+       - R = region
        - V = verbose
        - c = panel
        - t = transparency
@@ -151,6 +153,7 @@ def colorbar(
         F=Alias(box, name="box"),
     ).add_common(
         J=projection,
+        R=region,
         V=verbose,
         c=panel,
         t=transparency,

pygmt/src/contour.py

@@ -2,6 +2,7 @@
 contour - Contour table data by direct triangulation.
 """
 
+from collections.abc import Sequence
 from typing import Literal
 
 from pygmt._typing import PathLike, TableLike
@@ -24,7 +25,6 @@
     G="label_placement",
     L="triangular_mesh_pen",
     N="no_clip",
-    R="region",
     S="skip",
     W="pen",
     b="binary",
@@ -36,14 +36,15 @@
     l="label",
     p="perspective",
 )
-@kwargs_to_strings(R="sequence", i="sequence_comma", p="sequence")
+@kwargs_to_strings(i="sequence_comma", p="sequence")
 def contour(
     self,
     data: PathLike | TableLike | None = None,
     x=None,
     y=None,
     z=None,
     projection=None,
+    region: Sequence[float | str] | str | None = None,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     panel: int | tuple[int, int] | bool = False,
@@ -62,6 +63,7 @@ def contour(
 
     {aliases}
        - J = projection
+       - R = region
        - V = verbose
        - c = panel
        - t = transparency
@@ -161,6 +163,7 @@ def contour(
 
     aliasdict = AliasSystem().add_common(
         J=projection,
+        R=region,
         V=verbose,
         c=panel,
         t=transparency,