AliasSystem: Migrate the 'spacing' parameter to the new alias system (#4213)

Author: seisman

pygmt/src/binstats.py

@@ -9,24 +9,23 @@
 from pygmt._typing import PathLike, TableLike
 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
+from pygmt.helpers import build_arg_list, fmt_docstring, use_alias
 
 
 @fmt_docstring
 @use_alias(
     E="empty",
-    I="spacing",
     N="normalize",
     S="search_radius",
     W="weight",
     a="aspatial",
     b="binary",
     h="header",
 )
-@kwargs_to_strings(I="sequence")
 def binstats(
     data: PathLike | TableLike,
     outgrid: PathLike | None = None,
+    spacing: Sequence[float | str] | None = None,
     statistic: Literal[
         "mean",
         "mad",
@@ -68,6 +67,7 @@ def binstats(
 
     {aliases}
        - C = statistic
+       - I = spacing
        - R = region
        - V = verbose
        - i = incols
@@ -157,6 +157,7 @@ def binstats(
                 "sum": "z",
             },
         ),
+        I=Alias(spacing, name="spacing", sep="/", size=2),
     ).add_common(
         R=region,
         V=verbose,

pygmt/src/blockm.py

@@ -8,7 +8,7 @@
 import numpy as np
 import pandas as pd
 from pygmt._typing import PathLike, TableLike
-from pygmt.alias import AliasSystem
+from pygmt.alias import Alias, AliasSystem
 from pygmt.clib import Session
 from pygmt.helpers import (
     build_arg_list,
@@ -73,7 +73,6 @@ def _blockm(
 
 @fmt_docstring
 @use_alias(
-    I="spacing",
     S="summary",
     a="aspatial",
     b="binary",
@@ -84,14 +83,15 @@ def _blockm(
     o="outcols",
     w="wrap",
 )
-@kwargs_to_strings(I="sequence", o="sequence_comma")
-def blockmean(
+@kwargs_to_strings(o="sequence_comma")
+def blockmean(  # noqa: PLR0913
     data: PathLike | TableLike | None = None,
     x=None,
     y=None,
     z=None,
     output_type: Literal["pandas", "numpy", "file"] = "pandas",
     outfile: PathLike | None = None,
+    spacing: Sequence[float | str] | None = None,
     region: Sequence[float | str] | str | None = None,
     registration: Literal["gridline", "pixel"] | bool = False,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
@@ -114,6 +114,7 @@ def blockmean(
     Full GMT docs at :gmt-docs:`blockmean.html`.
 
     {aliases}
+       - I = spacing
        - R = region
        - V = verbose
        - i = incols
@@ -169,7 +170,9 @@ def blockmean(
     >>> # Calculate block mean values within 5 by 5 arc-minute bins
     >>> data_bmean = pygmt.blockmean(data=data, region=[245, 255, 20, 30], spacing="5m")
     """
-    aliasdict = AliasSystem().add_common(
+    aliasdict = AliasSystem(
+        I=Alias(spacing, name="spacing", sep="/", size=2),
+    ).add_common(
         R=region,
         V=verbose,
         i=incols,
@@ -191,7 +194,6 @@ def blockmean(
 
 @fmt_docstring
 @use_alias(
-    I="spacing",
     a="aspatial",
     b="binary",
     d="nodata",
@@ -201,14 +203,15 @@ def blockmean(
     o="outcols",
     w="wrap",
 )
-@kwargs_to_strings(I="sequence", o="sequence_comma")
-def blockmedian(
+@kwargs_to_strings(o="sequence_comma")
+def blockmedian(  # noqa: PLR0913
     data: PathLike | TableLike | None = None,
     x=None,
     y=None,
     z=None,
     output_type: Literal["pandas", "numpy", "file"] = "pandas",
     outfile: PathLike | None = None,
+    spacing: Sequence[float | str] | None = None,
     region: Sequence[float | str] | str | None = None,
     registration: Literal["gridline", "pixel"] | bool = False,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
@@ -231,6 +234,7 @@ def blockmedian(
     Full GMT docs at :gmt-docs:`blockmedian.html`.
 
     {aliases}
+       - I = spacing
        - R = region
        - V = verbose
        - i = incols
@@ -280,7 +284,9 @@ def blockmedian(
     ...     data=data, region=[245, 255, 20, 30], spacing="5m"
     ... )
     """
-    aliasdict = AliasSystem().add_common(
+    aliasdict = AliasSystem(
+        I=Alias(spacing, name="spacing", sep="/", size=2),
+    ).add_common(
         R=region,
         V=verbose,
         i=incols,
@@ -302,7 +308,6 @@ def blockmedian(
 
 @fmt_docstring
 @use_alias(
-    I="spacing",
     a="aspatial",
     b="binary",
     d="nodata",
@@ -312,14 +317,15 @@ def blockmedian(
     o="outcols",
     w="wrap",
 )
-@kwargs_to_strings(I="sequence", o="sequence_comma")
-def blockmode(
+@kwargs_to_strings(o="sequence_comma")
+def blockmode(  # noqa: PLR0913
     data: PathLike | TableLike | None = None,
     x=None,
     y=None,
     z=None,
     output_type: Literal["pandas", "numpy", "file"] = "pandas",
     outfile: PathLike | None = None,
+    spacing: Sequence[float | str] | None = None,
     region: Sequence[float | str] | str | None = None,
     registration: Literal["gridline", "pixel"] | bool = False,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
@@ -342,6 +348,7 @@ def blockmode(
     Full GMT docs at :gmt-docs:`blockmode.html`.
 
     {aliases}
+       - I = spacing
        - R = region
        - V = verbose
        - i = incols
@@ -389,7 +396,9 @@ def blockmode(
     >>> # Calculate block mode values within 5 by 5 arc-minute bins
     >>> data_bmode = pygmt.blockmode(data=data, region=[245, 255, 20, 30], spacing="5m")
     """
-    aliasdict = AliasSystem().add_common(
+    aliasdict = AliasSystem(
+        I=Alias(spacing, name="spacing", sep="/", size=2),
+    ).add_common(
         R=region,
         V=verbose,
         i=incols,

pygmt/src/dimfilter.py

@@ -7,20 +7,20 @@
 
 import xarray as xr
 from pygmt._typing import PathLike
-from pygmt.alias import AliasSystem
+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
+from pygmt.helpers import build_arg_list, fmt_docstring, use_alias
 
 __doctest_skip__ = ["dimfilter"]
 
 
 @fmt_docstring
-@use_alias(D="distance", F="filter", I="spacing", N="sectors")
-@kwargs_to_strings(I="sequence")
+@use_alias(D="distance", F="filter", N="sectors")
 def dimfilter(
     grid: PathLike | xr.DataArray,
     outgrid: PathLike | None = None,
+    spacing: Sequence[float | str] | None = None,
     region: Sequence[float | str] | str | None = None,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
@@ -48,6 +48,7 @@ def dimfilter(
     Full GMT docs at :gmt-docs:`dimfilter.html`.
 
     {aliases}
+       - I = spacing
        - R = region
        - V = verbose
 
@@ -102,7 +103,7 @@ def dimfilter(
           If more than one mode is found we return their average
           value. Append **+l** or **+h** to the sectors if you rather want to
           return the smallest or largest of the modal values.
-    spacing : str or list
+    spacing
         *x_inc* [and optionally *y_inc*] is the output increment. Append
         **m** to indicate minutes, or **c** to indicate seconds. If the new
         *x_inc*, *y_inc* are **not** integer multiples of the old ones (in the
@@ -148,7 +149,9 @@ def dimfilter(
         )
         raise GMTInvalidInput(msg)
 
-    aliasdict = AliasSystem().add_common(
+    aliasdict = AliasSystem(
+        I=Alias(spacing, name="spacing", sep="/", size=2),
+    ).add_common(
         R=region,
         V=verbose,
     )

pygmt/src/grdfilter.py

@@ -9,16 +9,16 @@
 from pygmt._typing import PathLike
 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
+from pygmt.helpers import build_arg_list, fmt_docstring, use_alias
 
 
 @fmt_docstring
-@use_alias(D="distance", F="filter", I="spacing", N="nans", f="coltypes")
-@kwargs_to_strings(I="sequence")
+@use_alias(D="distance", F="filter", N="nans", f="coltypes")
 def grdfilter(
     grid: PathLike | xr.DataArray,
     outgrid: PathLike | None = None,
     toggle: bool = False,
+    spacing: Sequence[float | str] | None = None,
     region: Sequence[float | str] | str | None = None,
     registration: Literal["gridline", "pixel"] | bool = False,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
@@ -42,6 +42,7 @@ def grdfilter(
     Full GMT docs at :gmt-docs:`grdfilter.html`.
 
     {aliases}
+       - I = spacing
        - R = region
        - T = toggle
        - V = verbose
@@ -136,6 +137,7 @@ def grdfilter(
     >>> smooth_field = pygmt.grdfilter(grid=grid, filter="g600", distance="4")
     """
     aliasdict = AliasSystem(
+        I=Alias(spacing, name="spacing", sep="/", size=2),
         T=Alias(toggle, name="toggle"),
     ).add_common(
         R=region,

pygmt/src/grdinfo.py

@@ -77,7 +77,7 @@ def grdinfo(
         Report grid domain and x/y-increments in world mapping format.
         The default value is ``False``. This cannot be called if
         ``per_column`` is also set.
-    spacing : str or list
+    spacing
         *dx*\ [/*dy*]\|\ **b**\|\ **i**\|\ **r**.
         Report the min/max of the region to the nearest multiple of dx and dy,
         and output this in the form w/e/s/n (unless ``per_column`` is set). To

pygmt/src/grdlandmask.py

@@ -10,16 +10,16 @@
 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
+from pygmt.helpers import build_arg_list, fmt_docstring, use_alias
 
 __doctest_skip__ = ["grdlandmask"]
 
 
 @fmt_docstring
-@use_alias(A="area_thresh", I="spacing")
-@kwargs_to_strings(I="sequence")
+@use_alias(A="area_thresh")
 def grdlandmask(
     outgrid: PathLike | None = None,
+    spacing: Sequence[float | str] | None = None,
     maskvalues: Sequence[float] | None = None,
     bordervalues: bool | float | Sequence[float] | None = None,
     resolution: Literal[
@@ -46,6 +46,7 @@ def grdlandmask(
     {aliases}
        - D = resolution
        - E = bordervalues
+       - I = spacing
        - N = maskvalues
        - R = region
        - V = verbose
@@ -110,7 +111,7 @@ def grdlandmask(
     >>> # latitude range of 30° N to 35° N, and a grid spacing of 1 arc-degree
     >>> landmask = pygmt.grdlandmask(spacing=1, region=[125, 130, 30, 35])
     """
-    if kwargs.get("I") is None or kwargs.get("R", region) is None:
+    if kwargs.get("I", spacing) is None or kwargs.get("R", region) is None:
         msg = "Both 'region' and 'spacing' must be specified."
         raise GMTInvalidInput(msg)
 
@@ -127,6 +128,7 @@ def grdlandmask(
                 "crude": "c",
             },
         ),
+        I=Alias(spacing, name="spacing", sep="/", size=2),
         N=Alias(maskvalues, name="maskvalues", sep="/", size=(2, 5)),
         E=Alias(bordervalues, name="bordervalues", sep="/", size=4),
     ).add_common(

pygmt/src/grdsample.py

@@ -14,7 +14,6 @@
     build_arg_list,
     deprecate_parameter,
     fmt_docstring,
-    kwargs_to_strings,
     use_alias,
 )
 
@@ -24,12 +23,12 @@
 # TODO(PyGMT>=0.21.0): Remove the deprecated "translate" parameter.
 @fmt_docstring
 @deprecate_parameter("translate", "toggle", "v0.18.0", remove_version="v0.21.0")
-@use_alias(I="spacing", f="coltypes", n="interpolation")
-@kwargs_to_strings(I="sequence")
+@use_alias(f="coltypes", n="interpolation")
 def grdsample(
     grid: PathLike | xr.DataArray,
     outgrid: PathLike | None = None,
     toggle: bool = False,
+    spacing: Sequence[float | str] | None = None,
     region: Sequence[float | str] | str | None = None,
     registration: Literal["gridline", "pixel"] | bool = False,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
@@ -56,6 +55,7 @@ def grdsample(
     Full GMT docs at :gmt-docs:`grdsample.html`.
 
     {aliases}
+       - I = spacing
        - R = region
        - V = verbose
        - r = registration
@@ -105,6 +105,7 @@ def grdsample(
         raise GMTInvalidInput(msg)
 
     aliasdict = AliasSystem(
+        I=Alias(spacing, name="spacing", sep="/", size=2),
         T=Alias(toggle, name="toggle"),
     ).add_common(
         R=region,