Add common alias coltypes (-f) for specifying i/o data types (#994)

Used to specify data types of input and/or output
columns (time or geographical data). See also:

- https://docs.generic-mapping-tools.org/6.1/gmt.html#f-full
- https://github.com/GenericMappingTools/gmt/blob/6.1.1/doc/rst/source/explain_-f.rst_
- https://github.com/GenericMappingTools/gmt/blob/master/doc/rst/source/explain_-f_full.rst_
- https://docs.generic-mapping-tools.org/6.1/cookbook/options.html#data-type-selection-the-f-option

Needed for the workaround datetime bugfix at #960

Author: weiji14

pygmt/helpers/decorators.py

@@ -72,6 +72,13 @@
             when the subplot was defined. **Note**: *row*, *col*, and *index*
             all start at 0.
          """,
+    "f": r"""
+        coltypes : str
+            [**i**\|\ **o**]\ *colinfo*.
+            Specify data types of input and/or output columns (time or
+            geographical data). Full documentation is at
+            :gmt-docs:`gmt.html#f-full`.
+         """,
     "j": r"""
         distcalc : str
             **e**\|\ **f**\|\ **g**.

pygmt/src/basemap.py

@@ -28,6 +28,7 @@
     X="xshift",
     Y="yshift",
     c="panel",
+    f="coltypes",
     p="perspective",
     t="transparency",
 )
@@ -69,6 +70,7 @@ def basemap(self, **kwargs):
     {V}
     {XY}
     {c}
+    {f}
     {p}
     {t}
     """

pygmt/src/blockmedian.py

@@ -16,7 +16,7 @@
 
 
 @fmt_docstring
-@use_alias(I="spacing", R="region", V="verbose")
+@use_alias(I="spacing", R="region", V="verbose", f="coltypes")
 @kwargs_to_strings(R="sequence")
 def blockmedian(table, outfile=None, **kwargs):
     r"""
@@ -52,6 +52,7 @@ def blockmedian(table, outfile=None, **kwargs):
         file.
 
     {V}
+    {f}
 
     Returns
     -------

pygmt/src/grdcontour.py

@@ -23,6 +23,7 @@
     X="xshift",
     Y="yshift",
     c="panel",
+    f="coltypes",
     p="perspective",
     t="transparency",
 )
@@ -84,6 +85,7 @@ def grdcontour(self, grid, **kwargs):
     {W}
     {XY}
     {c}
+    {f}
     label : str
         Add a legend entry for the contour being plotted. Normally, the
         annotated contour is selected for the legend. You can select the

pygmt/src/grdcut.py

@@ -22,6 +22,7 @@
     S="circ_subregion",
     V="verbose",
     Z="z_subregion",
+    f="coltypes",
 )
 @kwargs_to_strings(R="sequence")
 def grdcut(grid, **kwargs):
@@ -76,6 +77,7 @@ def grdcut(grid, **kwargs):
         area.
 
     {V}
+    {f}
 
     Returns
     -------

pygmt/src/grdfilter.py

@@ -23,6 +23,7 @@
     R="region",
     T="toggle",
     V="verbose",
+    f="coltypes",
 )
 @kwargs_to_strings(R="sequence")
 def grdfilter(grid, **kwargs):
@@ -108,6 +109,7 @@ def grdfilter(grid, **kwargs):
         opposite of the input grid. [Default gives the same registration as the
         input grid].
     {V}
+    {f}
 
     Returns
     -------

pygmt/src/grdimage.py

@@ -25,6 +25,7 @@
     Y="yshift",
     n="interpolation",
     c="panel",
+    f="coltypes",
     p="perspective",
     t="transparency",
     x="cores",
@@ -143,6 +144,7 @@ def grdimage(self, grid, **kwargs):
     {V}
     {XY}
     {c}
+    {f}
     {n}
     {p}
     {t}

pygmt/src/grdinfo.py

@@ -22,6 +22,7 @@
     R="region",
     T="nearest_multiple",
     V="verbose",
+    f="coltypes",
 )
 @kwargs_to_strings(D="sequence", I="sequence", R="sequence")
 def grdinfo(grid, **kwargs):
@@ -100,6 +101,7 @@ def grdinfo(grid, **kwargs):
         We report the result via the text string *zmin/zmax* or *zmin/zmax/dz*
         (if *dz* was given) as expected by :meth:`pygmt.makecpt`.
     {V}
+    {f}
 
     Returns
     -------

pygmt/src/grdtrack.py

@@ -15,7 +15,7 @@
 
 
 @fmt_docstring
-@use_alias(n="interpolation", V="verbose")
+@use_alias(V="verbose", f="coltypes", n="interpolation")
 def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs):
     """
     Sample grids at specified (x,y) locations.
@@ -55,7 +55,7 @@ def grdtrack(points, grid, newcolname=None, outfile=None, **kwargs):
         file.
 
     {V}
-
+    {f}
     {n}
 
     Returns

pygmt/src/grdview.py

@@ -33,6 +33,7 @@
     X="xshift",
     Y="yshift",
     c="panel",
+    f="coltypes",
     p="perspective",
     t="transparency",
 )
@@ -107,6 +108,7 @@ def grdview(self, grid, **kwargs):
     {V}
     {XY}
     {c}
+    {f}
     {p}
     {t}
     """

pygmt/src/info.py

@@ -7,7 +7,7 @@
 
 
 @fmt_docstring
-@use_alias(C="per_column", I="spacing", T="nearest_multiple", V="verbose")
+@use_alias(C="per_column", I="spacing", T="nearest_multiple", V="verbose", f="coltypes")
 def info(table, **kwargs):
     r"""
     Get information about data tables.
@@ -48,6 +48,7 @@ def info(table, **kwargs):
         of dz and output this in the form ``[zmin, zmax, dz]``.
 
     {V}
+    {f}
 
     Returns
     -------

pygmt/src/plot.py

@@ -39,6 +39,7 @@
     i="columns",
     l="label",
     c="panel",
+    f="coltypes",
     p="perspective",
     t="transparency",
 )
@@ -183,6 +184,7 @@ def plot(self, x=None, y=None, data=None, sizes=None, direction=None, **kwargs):
         ``color='+z'``. To apply it to the pen color, append **+z** to
         ``pen``.
     {c}
+    {f}
     columns : str or 1d array
         Choose which columns are x, y, color, and size, respectively if
         input is provided via *data*. E.g. ``columns = [0, 1]`` or

pygmt/src/plot3d.py

@@ -39,6 +39,7 @@
     i="columns",
     l="label",
     c="panel",
+    f="coltypes",
     p="perspective",
     t="transparency",
 )
@@ -153,6 +154,7 @@ def plot3d(
         ``color='+z'``. To apply it to the pen color, append **+z** to
         ``pen``.
     {c}
+    {f}
     label : str
         Add a legend entry for the symbol or line being plotted.
     {p}

pygmt/src/surface.py

@@ -17,7 +17,7 @@
 
 
 @fmt_docstring
-@use_alias(I="spacing", R="region", G="outfile", V="verbose")
+@use_alias(I="spacing", R="region", G="outfile", V="verbose", f="coltypes")
 @kwargs_to_strings(R="sequence")
 def surface(x=None, y=None, z=None, data=None, **kwargs):
     r"""
@@ -60,6 +60,7 @@ def surface(x=None, y=None, z=None, data=None, **kwargs):
         to store the grid in.
 
     {V}
+    {f}
 
     Returns
     -------

pygmt/src/text.py

@@ -29,6 +29,7 @@
     X="xshift",
     Y="yshift",
     c="panel",
+    f="coltypes",
     p="perspective",
     t="transparency",
 )
@@ -143,6 +144,7 @@ def text_(
     {V}
     {XY}
     {c}
+    {f}
     {p}
     {t}
     """