Merge branch 'master' into plot-depr-columns

Author: michaelgrund

doc/maintenance.md

@@ -173,21 +173,21 @@ When making incompatible changes, we should follow the process:
   3-12 months.
 - Remove the old usage and warning when reaching the declared version.
 
-To rename a function parameter, add the `@deprecated_parameter` decorator
-before the function definition (but after the `@use_alias` decorator if it exists).
-Here is an example:
+To rename a function parameter, add the `@deprecate_parameter` decorator near
+the top after the `@fmt_docstring` decorator but before the `@use_alias`
+decorator (if those two exists). Here is an example:
 
 ```
 @fmt_docstring
-@use_alias(J="projection", R="region", V="verbose")
-@kwargs_to_strings(R="sequence")
-@deprecate_parameter("sizes", "size", "v0.4.0", remove_version="v0.6.0")
+@deprecate_parameter("columns", "incols", "v0.4.0", remove_version="v0.6.0")
+@use_alias(J="projection", R="region", V="verbose", i="incols")
+@kwargs_to_strings(R="sequence", i='sequence_comma')
 def plot(self, x=None, y=None, data=None, size=None, direction=None, **kwargs):
     pass
 ```
 
-In this case, the old parameter name `sizes` is deprecated since v0.4.0, and will be
-fully removed in v0.6.0. The new parameter name is `size`.
+In this case, the old parameter name `columns` is deprecated since v0.4.0, and
+will be fully removed in v0.6.0. The new parameter name is `incols`.
 
 
 ## Making a Release

pygmt/helpers/decorators.py

@@ -118,6 +118,36 @@
             geographical data). Full documentation is at
             :gmt-docs:`gmt.html#f-full`.
          """,
+    "i": r"""
+        incols : str or 1d 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 *1d 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:
+
+                - **+l** to take the *log10* of the input values.
+                - **+d** to divide the input values by the factor *divisor*
+                  [default is 1].
+                - **+s** to multiple the input values by the factor *scale*
+                  [default is 1].
+                - **+o** to add the given *offset* to the input values [default
+                  is 0].""",
     "j": r"""
         distcalc : str
             **e**\|\ **f**\|\ **g**.
@@ -505,7 +535,7 @@ def deprecate_parameter(oldname, newname, deprecate_version, remove_version):
     name, and users will receive a FutureWarning to inform them of the pending
     deprecation.
 
-    Use this decorator below the ``use_alias`` decorator.
+    Use this decorator above the ``use_alias`` decorator.
 
     Parameters
     ----------

pygmt/src/blockm.py

@@ -69,6 +69,7 @@ def _blockm(block_method, table, outfile, **kwargs):
     V="verbose",
     a="aspatial",
     f="coltypes",
+    i="incols",
     r="registration",
 )
 @kwargs_to_strings(R="sequence")
@@ -103,6 +104,7 @@ def blockmean(table, outfile=None, **kwargs):
 
     {V}
     {a}
+    {i}
     {f}
     {r}
 
@@ -126,6 +128,7 @@ def blockmean(table, outfile=None, **kwargs):
     V="verbose",
     a="aspatial",
     f="coltypes",
+    i="incols",
     r="registration",
 )
 @kwargs_to_strings(R="sequence")
@@ -161,6 +164,7 @@ def blockmedian(table, outfile=None, **kwargs):
     {V}
     {a}
     {f}
+    {i}
     {r}
 
     Returns