diff --git a/pygmt/alias.py b/pygmt/alias.py index 01024c28dd2..339a0d20803 100644 --- a/pygmt/alias.py +++ b/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": diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py index 52d3e426e52..13c0d1c8683 100644 --- a/pygmt/helpers/decorators.py +++ b/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 multiple 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"``. diff --git a/pygmt/src/blockm.py b/pygmt/src/blockm.py index 4c8b83df223..2b402e53479 100644 --- a/pygmt/src/blockm.py +++ b/pygmt/src/blockm.py @@ -81,11 +81,10 @@ def _blockm( e="find", f="coltypes", h="header", - o="outcols", w="wrap", ) -@kwargs_to_strings(I="sequence", o="sequence_comma") -def blockmean( +@kwargs_to_strings(I="sequence") +def blockmean( # noqa: PLR0913 data: PathLike | TableLike | None = None, x=None, y=None, @@ -97,6 +96,7 @@ def blockmean( 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""" @@ -117,6 +117,7 @@ def blockmean( - R = region - V = verbose - i = incols + - o = outcols - r = registration Parameters @@ -173,6 +174,7 @@ def blockmean( R=region, V=verbose, i=incols, + o=outcols, r=registration, ) aliasdict.merge(kwargs) @@ -198,11 +200,10 @@ def blockmean( e="find", f="coltypes", h="header", - o="outcols", w="wrap", ) -@kwargs_to_strings(I="sequence", o="sequence_comma") -def blockmedian( +@kwargs_to_strings(I="sequence") +def blockmedian( # noqa: PLR0913 data: PathLike | TableLike | None = None, x=None, y=None, @@ -214,6 +215,7 @@ def blockmedian( 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""" @@ -234,6 +236,7 @@ def blockmedian( - R = region - V = verbose - i = incols + - o = outcols - r = registration Parameters @@ -284,6 +287,7 @@ def blockmedian( R=region, V=verbose, i=incols, + o=outcols, r=registration, ) aliasdict.merge(kwargs) @@ -309,11 +313,10 @@ def blockmedian( e="find", f="coltypes", h="header", - o="outcols", w="wrap", ) -@kwargs_to_strings(I="sequence", o="sequence_comma") -def blockmode( +@kwargs_to_strings(I="sequence") +def blockmode( # noqa: PLR0913 data: PathLike | TableLike | None = None, x=None, y=None, @@ -325,6 +328,7 @@ def blockmode( 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""" @@ -345,6 +349,7 @@ def blockmode( - R = region - V = verbose - i = incols + - o = outcols - r = registration Parameters @@ -393,6 +398,7 @@ def blockmode( R=region, V=verbose, i=incols, + o=outcols, r=registration, ) aliasdict.merge(kwargs) diff --git a/pygmt/src/grd2xyz.py b/pygmt/src/grd2xyz.py index 662fe228c81..eee6fe751d4 100644 --- a/pygmt/src/grd2xyz.py +++ b/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,10 +31,8 @@ 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", @@ -43,6 +40,7 @@ def grd2xyz( 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) diff --git a/pygmt/src/grdtrack.py b/pygmt/src/grdtrack.py index 993552a8e61..4afac0589aa 100644 --- a/pygmt/src/grdtrack.py +++ b/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) diff --git a/pygmt/src/select.py b/pygmt/src/select.py index 6569ad2d60e..5c932393508 100644 --- a/pygmt/src/select.py +++ b/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)