From 8a1945bb6ff6ee841335808cf71254902056c6ea Mon Sep 17 00:00:00 2001
From: Wei Ji <23487320+weiji14@users.noreply.github.com>
Date: Thu, 4 Mar 2021 08:09:23 +1300
Subject: [PATCH] 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 https://github.com/GenericMappingTools/pygmt/pull/960
---
 pygmt/helpers/decorators.py | 7 +++++++
 pygmt/src/basemap.py        | 2 ++
 pygmt/src/blockmedian.py    | 3 ++-
 pygmt/src/grdcontour.py     | 2 ++
 pygmt/src/grdcut.py         | 2 ++
 pygmt/src/grdfilter.py      | 2 ++
 pygmt/src/grdimage.py       | 2 ++
 pygmt/src/grdinfo.py        | 2 ++
 pygmt/src/grdtrack.py       | 4 ++--
 pygmt/src/grdview.py        | 2 ++
 pygmt/src/info.py           | 3 ++-
 pygmt/src/plot.py           | 2 ++
 pygmt/src/plot3d.py         | 2 ++
 pygmt/src/surface.py        | 3 ++-
 pygmt/src/text.py           | 2 ++
 15 files changed, 35 insertions(+), 5 deletions(-)

diff --git a/pygmt/helpers/decorators.py b/pygmt/helpers/decorators.py
index 36b1a87dd9a..af56d5ab98f 100644
--- a/pygmt/helpers/decorators.py
+++ b/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**.
diff --git a/pygmt/src/basemap.py b/pygmt/src/basemap.py
index 95a2406d448..1a742ea4d59 100644
--- a/pygmt/src/basemap.py
+++ b/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}
     """
diff --git a/pygmt/src/blockmedian.py b/pygmt/src/blockmedian.py
index 23147c68205..190717e8ceb 100644
--- a/pygmt/src/blockmedian.py
+++ b/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
     -------
diff --git a/pygmt/src/grdcontour.py b/pygmt/src/grdcontour.py
index 15193cd0767..5514a98c57e 100644
--- a/pygmt/src/grdcontour.py
+++ b/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
diff --git a/pygmt/src/grdcut.py b/pygmt/src/grdcut.py
index 0140898b90a..353b82bc3a5 100644
--- a/pygmt/src/grdcut.py
+++ b/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
     -------
diff --git a/pygmt/src/grdfilter.py b/pygmt/src/grdfilter.py
index ce1e3b23d5e..7a60d990f25 100644
--- a/pygmt/src/grdfilter.py
+++ b/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
     -------
diff --git a/pygmt/src/grdimage.py b/pygmt/src/grdimage.py
index 1fbe26160c6..2d8f41ce703 100644
--- a/pygmt/src/grdimage.py
+++ b/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}
diff --git a/pygmt/src/grdinfo.py b/pygmt/src/grdinfo.py
index be481758497..44aea01f31a 100644
--- a/pygmt/src/grdinfo.py
+++ b/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
     -------
diff --git a/pygmt/src/grdtrack.py b/pygmt/src/grdtrack.py
index ea80d5c409d..f67cc842ba7 100644
--- a/pygmt/src/grdtrack.py
+++ b/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
diff --git a/pygmt/src/grdview.py b/pygmt/src/grdview.py
index bf176738fe0..0810a2a06bd 100644
--- a/pygmt/src/grdview.py
+++ b/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}
     """
diff --git a/pygmt/src/info.py b/pygmt/src/info.py
index e6f2e9aac61..ca059952e57 100644
--- a/pygmt/src/info.py
+++ b/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
     -------
diff --git a/pygmt/src/plot.py b/pygmt/src/plot.py
index cdceba2bcec..f367d816562 100644
--- a/pygmt/src/plot.py
+++ b/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
diff --git a/pygmt/src/plot3d.py b/pygmt/src/plot3d.py
index 8c42b5eae7b..3b7ad917bdb 100644
--- a/pygmt/src/plot3d.py
+++ b/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}
diff --git a/pygmt/src/surface.py b/pygmt/src/surface.py
index e4672ea4063..0c6fc85f0d0 100644
--- a/pygmt/src/surface.py
+++ b/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
     -------
diff --git a/pygmt/src/text.py b/pygmt/src/text.py
index e21bcc8b6e4..4c7b5421410 100644
--- a/pygmt/src/text.py
+++ b/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}
     """