AliasSystem: Migrate the 'incols' parameter to the new alias system

pygmt/alias.py

@@ -301,7 +301,7 @@ def __init__(self, **kwargs):
                 kwdict[option] = aliases._value
         super().__init__(kwdict)
 
-    def add_common(self, **kwargs):
+    def add_common(self, **kwargs):  # noqa: PLR0912
         """
         Add common parameters to the alias dictionary.
         """
@@ -329,6 +329,8 @@ def add_common(self, **kwargs):
                     )
                 case "c":
                     alias = Alias(value, name="panel", sep=",", size=2)
+                case "i":
+                    alias = Alias(value, name="incols", sep=",")
                 case "r":
                     alias = Alias(
                         value,

pygmt/helpers/decorators.py

@@ -159,27 +159,24 @@
 
             Blank lines and lines starting with \# are always skipped.""",
     "incols": r"""
-        incols : str or 1-D array
-            Specify data columns for primary input in arbitrary order. Columns
-            can be repeated and columns not listed will be skipped [Default
-            reads all columns in order, starting with the first (i.e., column
-            0)].
-
-            - For *1-D array*: specify individual columns in input order (e.g.,
-              ``incols=[1,0]`` for the 2nd column followed by the 1st column).
-            - For :py:class:`str`: specify individual columns or column
-              ranges in the format *start*\ [:*inc*]:*stop*, where *inc*
-              defaults to 1 if not specified, with columns and/or column ranges
-              separated by commas (e.g., ``incols="0:2,4+l"`` to input the
-              first three columns followed by the log-transformed 5th column).
-              To read from a given column until the end of the record, leave
-              off *stop* when specifying the column range. To read trailing
-              text, add the column **t**. Append the word number to **t** to
-              ingest only a single word from the trailing text. Instead of
-              specifying columns, use ``incols="n"`` to simply read numerical
-              input and skip trailing text. Optionally, append one of the
-              following modifiers to any column or column range to transform
-              the input columns:
+        incols
+            Specify data columns for primary input in arbitrary order. Columns can be
+            repeated and columns not listed will be skipped [Default reads all columns
+            in order, starting with the first (i.e., column 0)].
+
+            - For a sequence: specify individual columns in input order (e.g.,
+              ``incols=(1, 0)`` for the 2nd column followed by the 1st column).
+            - For a string: specify individual columns or column ranges in the format
+              *start*\ [:*inc*]:*stop*, where *inc* defaults to 1 if not specified, with
+              columns and/or column ranges separated by commas (e.g.,
+              ``incols="0:2,4+l"`` to input the first three columns followed by the
+              log10-transformed 5th column). To read from a given column until the end of
+              the record, leave off *stop* when specifying the column range. To read
+              trailing text, add the column **t**. Append the word number to **t** to
+              ingest only a single word from the trailing text. Instead of specifying
+              columns, use ``incols="n"`` to simply read numerical input and skip
+              trailing text. Optionally, append one of the following modifiers to any
+              column or column range to transform the input columns:
 
               - **+l** to take the *log10* of the input values.
               - **+d** to divide the input values by the factor *divisor* [Default is 1].

pygmt/src/binstats.py

@@ -22,9 +22,8 @@
     a="aspatial",
     b="binary",
     h="header",
-    i="incols",
 )
-@kwargs_to_strings(I="sequence", i="sequence_comma")
+@kwargs_to_strings(I="sequence")
 def binstats(
     data: PathLike | TableLike,
     outgrid: PathLike | None = None,
@@ -51,6 +50,7 @@ def binstats(
     registration: Literal["gridline", "pixel"] | bool = False,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
+    incols: int | str | Sequence[int | str] | None = None,
     **kwargs,
 ) -> xr.DataArray | None:
     r"""
@@ -70,6 +70,7 @@ def binstats(
        - C = statistic
        - R = region
        - V = verbose
+       - i = incols
        - r = registration
 
     Parameters
@@ -159,6 +160,7 @@ def binstats(
     ).add_common(
         R=region,
         V=verbose,
+        i=incols,
         r=registration,
     )
     aliasdict.merge(kwargs)

pygmt/src/blockm.py

@@ -81,11 +81,10 @@ def _blockm(
     e="find",
     f="coltypes",
     h="header",
-    i="incols",
     o="outcols",
     w="wrap",
 )
-@kwargs_to_strings(I="sequence", i="sequence_comma", o="sequence_comma")
+@kwargs_to_strings(I="sequence", o="sequence_comma")
 def blockmean(
     data: PathLike | TableLike | None = None,
     x=None,
@@ -97,6 +96,7 @@ def blockmean(
     registration: Literal["gridline", "pixel"] | bool = False,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
+    incols: int | str | Sequence[int | str] | None = None,
     **kwargs,
 ) -> pd.DataFrame | np.ndarray | None:
     r"""
@@ -116,6 +116,7 @@ def blockmean(
     {aliases}
        - R = region
        - V = verbose
+       - i = incols
        - r = registration
 
     Parameters
@@ -171,6 +172,7 @@ def blockmean(
     aliasdict = AliasSystem().add_common(
         R=region,
         V=verbose,
+        i=incols,
         r=registration,
     )
     aliasdict.merge(kwargs)
@@ -196,11 +198,10 @@ def blockmean(
     e="find",
     f="coltypes",
     h="header",
-    i="incols",
     o="outcols",
     w="wrap",
 )
-@kwargs_to_strings(I="sequence", i="sequence_comma", o="sequence_comma")
+@kwargs_to_strings(I="sequence", o="sequence_comma")
 def blockmedian(
     data: PathLike | TableLike | None = None,
     x=None,
@@ -212,6 +213,7 @@ def blockmedian(
     registration: Literal["gridline", "pixel"] | bool = False,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
+    incols: int | str | Sequence[int | str] | None = None,
     **kwargs,
 ) -> pd.DataFrame | np.ndarray | None:
     r"""
@@ -231,6 +233,7 @@ def blockmedian(
     {aliases}
        - R = region
        - V = verbose
+       - i = incols
        - r = registration
 
     Parameters
@@ -280,6 +283,7 @@ def blockmedian(
     aliasdict = AliasSystem().add_common(
         R=region,
         V=verbose,
+        i=incols,
         r=registration,
     )
     aliasdict.merge(kwargs)
@@ -305,11 +309,10 @@ def blockmedian(
     e="find",
     f="coltypes",
     h="header",
-    i="incols",
     o="outcols",
     w="wrap",
 )
-@kwargs_to_strings(I="sequence", i="sequence_comma", o="sequence_comma")
+@kwargs_to_strings(I="sequence", o="sequence_comma")
 def blockmode(
     data: PathLike | TableLike | None = None,
     x=None,
@@ -321,6 +324,7 @@ def blockmode(
     registration: Literal["gridline", "pixel"] | bool = False,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
+    incols: int | str | Sequence[int | str] | None = None,
     **kwargs,
 ) -> pd.DataFrame | np.ndarray | None:
     r"""
@@ -340,6 +344,7 @@ def blockmode(
     {aliases}
        - R = region
        - V = verbose
+       - i = incols
        - r = registration
 
     Parameters
@@ -387,6 +392,7 @@ def blockmode(
     aliasdict = AliasSystem().add_common(
         R=region,
         V=verbose,
+        i=incols,
         r=registration,
     )
     aliasdict.merge(kwargs)

pygmt/src/contour.py

@@ -12,7 +12,6 @@
     build_arg_list,
     fmt_docstring,
     is_nonstr_iter,
-    kwargs_to_strings,
     use_alias,
 )
 
@@ -30,10 +29,8 @@
     e="find",
     f="coltypes",
     h="header",
-    i="incols",
     l="label",
 )
-@kwargs_to_strings(i="sequence_comma")
 def contour(  # noqa: PLR0913
     self,
     data: PathLike | TableLike | None = None,
@@ -49,6 +46,7 @@ def contour(  # noqa: PLR0913
     panel: int | Sequence[int] | bool = False,
     transparency: float | None = None,
     perspective: float | Sequence[float] | str | bool = False,
+    incols: int | str | Sequence[int | str] | None = None,
     **kwargs,
 ):
     r"""
@@ -68,6 +66,7 @@ def contour(  # noqa: PLR0913
        - R = region
        - V = verbose
        - c = panel
+       - i = incols
        - p = perspective
        - t = transparency
 
@@ -172,6 +171,7 @@ def contour(  # noqa: PLR0913
         R=region,
         V=verbose,
         c=panel,
+        i=incols,
         p=perspective,
         t=transparency,
     )

pygmt/src/grdtrack.py

@@ -41,14 +41,13 @@
     f="coltypes",
     g="gap",
     h="header",
-    i="incols",
     j="distcalc",
     n="interpolation",
     o="outcols",
     s="skiprows",
     w="wrap",
 )
-@kwargs_to_strings(S="sequence", i="sequence_comma", o="sequence_comma")
+@kwargs_to_strings(S="sequence", o="sequence_comma")
 def grdtrack(
     grid: PathLike | xr.DataArray,
     points: PathLike | TableLike | None = None,
@@ -58,6 +57,7 @@ def grdtrack(
     region: Sequence[float | str] | str | None = None,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
+    incols: int | str | Sequence[int | str] | None = None,
     **kwargs,
 ) -> pd.DataFrame | np.ndarray | None:
     r"""
@@ -82,6 +82,7 @@ def grdtrack(
     {aliases}
        - R = region
        - V = verbose
+       - i = incols
 
     Parameters
     ----------
@@ -317,6 +318,7 @@ def grdtrack(
     aliasdict = AliasSystem().add_common(
         R=region,
         V=verbose,
+        i=incols,
     )
     aliasdict.merge(kwargs)
 

pygmt/src/histogram.py

@@ -30,11 +30,10 @@
     d="nodata",
     e="find",
     h="header",
-    i="incols",
     l="label",
     w="wrap",
 )
-@kwargs_to_strings(T="sequence", i="sequence_comma")
+@kwargs_to_strings(T="sequence")
 def histogram(
     self,
     data: PathLike | TableLike,
@@ -46,6 +45,7 @@ def histogram(
     panel: int | Sequence[int] | bool = False,
     transparency: float | None = None,
     perspective: float | Sequence[float] | str | bool = False,
+    incols: int | str | Sequence[int | str] | None = None,
     **kwargs,
 ):
     r"""
@@ -59,6 +59,7 @@ def histogram(
        - R = region
        - V = verbose
        - c = panel
+       - i = incols
        - p = perspective
        - t = transparency
 
@@ -157,6 +158,7 @@ def histogram(
         R=region,
         V=verbose,
         c=panel,
+        i=incols,
         p=perspective,
         t=transparency,
     )

pygmt/src/info.py

@@ -2,6 +2,7 @@
 info - Get information about data tables.
 """
 
+from collections.abc import Sequence
 from typing import Literal
 
 import numpy as np
@@ -19,19 +20,15 @@
 
 @fmt_docstring
 @use_alias(
-    C="per_column",
-    I="spacing",
-    T="nearest_multiple",
-    a="aspatial",
-    f="coltypes",
-    i="incols",
+    C="per_column", I="spacing", T="nearest_multiple", a="aspatial", f="coltypes"
 )
-@kwargs_to_strings(I="sequence", i="sequence_comma")
+@kwargs_to_strings(I="sequence")
 def info(
     data: PathLike | TableLike,
     registration: Literal["gridline", "pixel"] | bool = False,
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
+    incols: int | str | Sequence[int | str] | None = None,
     **kwargs,
 ) -> np.ndarray | str:
     r"""
@@ -54,6 +51,7 @@ def info(
 
     {aliases}
        - V = verbose
+       - i = incols
        - r = registration
 
     Parameters
@@ -92,6 +90,7 @@ def info(
     """
     aliasdict = AliasSystem().add_common(
         V=verbose,
+        i=incols,
         r=registration,
     )
     aliasdict.merge(kwargs)