AliasSystem: Migrate the 'outcols' parameter to the new alias system (#4211)

Author: seisman

pygmt/alias.py

@@ -337,6 +337,8 @@ def add_common(self, **kwargs):  # noqa: PLR0912
                         name="registration",
                         mapping={"gridline": "g", "pixel": "p"},
                     )
+                case "o":
+                    alias = Alias(value, name="outcols", sep=",")
                 case "p":
                     alias = Alias(value, name="perspective", sep="/", size={2, 3})
                 case "t":

pygmt/helpers/decorators.py

@@ -204,28 +204,35 @@
             Prepend **i** to the *nodata* value for input columns only. Prepend
             **o** to the *nodata* value for output columns only.""",
     "outcols": r"""
-        outcols : str or 1-D array
+        outcols
             *cols*\ [,...][,\ **t**\ [*word*]].
-            Specify data columns for primary output in arbitrary order. Columns
-            can be repeated and columns not listed will be skipped [Default
-            writes all columns in order, starting with the first (i.e., column
-            0)].
-
-            - For *1-D array*: specify individual columns in output order (e.g.,
-              ``outcols=[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., ``outcols="0:2,4"`` to output the
-              first three columns followed by the 5th column).
-              To write from a given column until the end of the record, leave
-              off *stop* when specifying the column range. To write trailing
-              text, add the column **t**. Append the word number to **t** to
-              write only a single word from the trailing text. Instead of
-              specifying columns, use ``outcols="n"`` to simply read numerical
-              input and skip trailing text. **Note**: If ``incols`` is also
-              used then the columns given to ``outcols`` correspond to the
-              order after the ``incols`` selection has taken place.""",
+
+            Specify data columns for primary output in arbitrary order. Columns can be
+            repeated and columns not listed will be skipped [Default writes all columns
+            in order, starting with the first (i.e., column 0)].
+
+            - For a sequence: specify individual columns in output order (e.g.,
+              ``outcols=(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.,
+              ``outcols="0:2,4"`` to output the first three columns followed by the 5th
+              column). To write from a given column until the end of the record, leave
+              off *stop* when specifying the column range. To write trailing text, add
+              the column **t**. Append the word number to **t** to write only a single
+              word from the trailing text. Instead of specifying columns, use
+              ``outcols="n"`` to simply read numerical input and skip trailing text.
+              **Note**: If ``incols`` is also used then the columns given to ``outcols``
+              correspond to the order after the ``incols`` selection has taken place.
+
+              Optionally, append one of the following modifiers to any column or column
+              range to transform the output columns:
+
+              - **+l** to take the *log10* of the input values.
+              - **+d** to divide the output values by the factor *divisor* [Default is
+                1].
+              - **+s** to multiply the output values by the factor *scale* [Default is 1].
+              - **+o** to add the given *offset* to the output values [Default is 0].""",
     "outfile": """
         outfile
             File name for saving the result data. Required if ``output_type="file"``.

pygmt/src/blockm.py

@@ -13,7 +13,6 @@
 from pygmt.helpers import (
     build_arg_list,
     fmt_docstring,
-    kwargs_to_strings,
     use_alias,
     validate_output_table_type,
 )
@@ -80,10 +79,8 @@ def _blockm(
     e="find",
     f="coltypes",
     h="header",
-    o="outcols",
     w="wrap",
 )
-@kwargs_to_strings(o="sequence_comma")
 def blockmean(  # noqa: PLR0913
     data: PathLike | TableLike | None = None,
     x=None,
@@ -97,6 +94,7 @@ def blockmean(  # noqa: PLR0913
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     incols: int | str | Sequence[int | str] | None = None,
+    outcols: int | str | Sequence[int | str] | None = None,
     **kwargs,
 ) -> pd.DataFrame | np.ndarray | None:
     r"""
@@ -118,6 +116,7 @@ def blockmean(  # noqa: PLR0913
        - R = region
        - V = verbose
        - i = incols
+       - o = outcols
        - r = registration
 
     Parameters
@@ -176,6 +175,7 @@ def blockmean(  # noqa: PLR0913
         R=region,
         V=verbose,
         i=incols,
+        o=outcols,
         r=registration,
     )
     aliasdict.merge(kwargs)
@@ -194,16 +194,8 @@ def blockmean(  # noqa: PLR0913
 
 @fmt_docstring
 @use_alias(
-    a="aspatial",
-    b="binary",
-    d="nodata",
-    e="find",
-    f="coltypes",
-    h="header",
-    o="outcols",
-    w="wrap",
+    a="aspatial", b="binary", d="nodata", e="find", f="coltypes", h="header", w="wrap"
 )
-@kwargs_to_strings(o="sequence_comma")
 def blockmedian(  # noqa: PLR0913
     data: PathLike | TableLike | None = None,
     x=None,
@@ -217,6 +209,7 @@ def blockmedian(  # noqa: PLR0913
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     incols: int | str | Sequence[int | str] | None = None,
+    outcols: int | str | Sequence[int | str] | None = None,
     **kwargs,
 ) -> pd.DataFrame | np.ndarray | None:
     r"""
@@ -238,6 +231,7 @@ def blockmedian(  # noqa: PLR0913
        - R = region
        - V = verbose
        - i = incols
+       - o = outcols
        - r = registration
 
     Parameters
@@ -290,6 +284,7 @@ def blockmedian(  # noqa: PLR0913
         R=region,
         V=verbose,
         i=incols,
+        o=outcols,
         r=registration,
     )
     aliasdict.merge(kwargs)
@@ -314,10 +309,8 @@ def blockmedian(  # noqa: PLR0913
     e="find",
     f="coltypes",
     h="header",
-    o="outcols",
     w="wrap",
 )
-@kwargs_to_strings(o="sequence_comma")
 def blockmode(  # noqa: PLR0913
     data: PathLike | TableLike | None = None,
     x=None,
@@ -331,6 +324,7 @@ def blockmode(  # noqa: PLR0913
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     incols: int | str | Sequence[int | str] | None = None,
+    outcols: int | str | Sequence[int | str] | None = None,
     **kwargs,
 ) -> pd.DataFrame | np.ndarray | None:
     r"""
@@ -352,6 +346,7 @@ def blockmode(  # noqa: PLR0913
        - R = region
        - V = verbose
        - i = incols
+       - o = outcols
        - r = registration
 
     Parameters
@@ -402,6 +397,7 @@ def blockmode(  # noqa: PLR0913
         R=region,
         V=verbose,
         i=incols,
+        o=outcols,
         r=registration,
     )
     aliasdict.merge(kwargs)

pygmt/src/grd2xyz.py

@@ -15,7 +15,6 @@
 from pygmt.helpers import (
     build_arg_list,
     fmt_docstring,
-    kwargs_to_strings,
     use_alias,
     validate_output_table_type,
 )
@@ -32,17 +31,16 @@
     d="nodata",
     f="coltypes",
     h="header",
-    o="outcols",
     s="skiprows",
 )
-@kwargs_to_strings(o="sequence_comma")
 def grd2xyz(
     grid: PathLike | xr.DataArray,
     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,
+    outcols: int | str | Sequence[int | str] | None = None,
     **kwargs,
 ) -> pd.DataFrame | np.ndarray | None:
     r"""
@@ -56,6 +54,7 @@ def grd2xyz(
     {aliases}
        - R = region
        - V = verbose
+       - o = outcols
 
     Parameters
     ----------
@@ -149,7 +148,7 @@ def grd2xyz(
     """
     output_type = validate_output_table_type(output_type, outfile=outfile)
 
-    if kwargs.get("o") is not None and output_type == "pandas":
+    if kwargs.get("o", outcols) is not None and output_type == "pandas":
         raise GMTValueError(
             output_type,
             description="value for parameter 'output_type'",
@@ -165,6 +164,7 @@ def grd2xyz(
     aliasdict = AliasSystem().add_common(
         R=region,
         V=verbose,
+        o=outcols,
     )
     aliasdict.merge(kwargs)
 

pygmt/src/grdtrack.py

@@ -43,11 +43,10 @@
     h="header",
     j="distcalc",
     n="interpolation",
-    o="outcols",
     s="skiprows",
     w="wrap",
 )
-@kwargs_to_strings(S="sequence", o="sequence_comma")
+@kwargs_to_strings(S="sequence")
 def grdtrack(
     grid: PathLike | xr.DataArray,
     points: PathLike | TableLike | None = None,
@@ -58,6 +57,7 @@ def grdtrack(
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     incols: int | str | Sequence[int | str] | None = None,
+    outcols: int | str | Sequence[int | str] | None = None,
     **kwargs,
 ) -> pd.DataFrame | np.ndarray | None:
     r"""
@@ -83,6 +83,7 @@ def grdtrack(
        - R = region
        - V = verbose
        - i = incols
+       - o = outcols
 
     Parameters
     ----------
@@ -319,6 +320,7 @@ def grdtrack(
         R=region,
         V=verbose,
         i=incols,
+        o=outcols,
     )
     aliasdict.merge(kwargs)
 

pygmt/src/select.py

@@ -37,11 +37,10 @@
     f="coltypes",
     g="gap",
     h="header",
-    o="outcols",
     s="skiprows",
     w="wrap",
 )
-@kwargs_to_strings(N="sequence", o="sequence_comma")
+@kwargs_to_strings(N="sequence")
 def select(
     data: PathLike | TableLike | None = None,
     output_type: Literal["pandas", "numpy", "file"] = "pandas",
@@ -54,6 +53,7 @@ def select(
     verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
     | bool = False,
     incols: int | str | Sequence[int | str] | None = None,
+    outcols: int | str | Sequence[int | str] | None = None,
     **kwargs,
 ) -> pd.DataFrame | np.ndarray | None:
     r"""
@@ -83,6 +83,7 @@ def select(
        - R = region
        - V = verbose
        - i = incols
+       - o = outcols
 
     Parameters
     ----------
@@ -239,6 +240,7 @@ def select(
         R=region,
         V=verbose,
         i=incols,
+        o=outcols,
     )
     aliasdict.merge(kwargs)