Figure.plot: Reorder input parameters to "data, x, y" (#1547)

* Update plot.py
* add decorator
* adjust test_plot_datetime
* adjust gallery examples

Author: michaelgrund

examples/gallery/symbols/datetime_inputs.py

@@ -41,26 +41,26 @@
 # numpy.datetime64 types
 x = np.array(["2010-06-01", "2011-06-01T12", "2012-01-01T12:34:56"], dtype="datetime64")
 y = [1, 2, 3]
-fig.plot(x, y, style="c0.4c", pen="1p", color="red3")
+fig.plot(x=x, y=y, style="c0.4c", pen="1p", color="red3")
 
 # pandas.DatetimeIndex
 x = pd.date_range("2013", periods=3, freq="YS")
 y = [4, 5, 6]
-fig.plot(x, y, style="t0.4c", pen="1p", color="gold")
+fig.plot(x=x, y=y, style="t0.4c", pen="1p", color="gold")
 
 # xarray.DataArray
 x = xr.DataArray(data=pd.date_range(start="2015-03", periods=3, freq="QS"))
 y = [7.5, 6, 4.5]
-fig.plot(x, y, style="s0.4c", pen="1p")
+fig.plot(x=x, y=y, style="s0.4c", pen="1p")
 
 # raw datetime strings
 x = ["2016-02-01", "2016-06-04T14", "2016-10-04T00:00:15"]
 y = [7, 8, 9]
-fig.plot(x, y, style="a0.4c", pen="1p", color="dodgerblue")
+fig.plot(x=x, y=y, style="a0.4c", pen="1p", color="dodgerblue")
 
 # the Python built-in datetime and date
 x = [datetime.date(2018, 1, 1), datetime.datetime(2019, 6, 1, 20, 5, 45)]
 y = [6.5, 4.5]
-fig.plot(x, y, style="i0.4c", pen="1p", color="seagreen")
+fig.plot(x=x, y=y, style="i0.4c", pen="1p", color="seagreen")
 
 fig.show()

examples/gallery/symbols/points.py

@@ -19,5 +19,5 @@
 # data region
 fig.basemap(region=region, projection="X15c", frame=True)
 # Plot using inverted triangles (i) of 0.5 cm size
-fig.plot(x, y, style="i0.5c", color="black")
+fig.plot(x=x, y=y, style="i0.5c", color="black")
 fig.show()

pygmt/src/plot.py

@@ -5,6 +5,7 @@
 from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers import (
     build_arg_string,
+    check_data_input_order,
     data_kind,
     deprecate_parameter,
     fmt_docstring,
@@ -18,6 +19,7 @@
 @fmt_docstring
 @deprecate_parameter("sizes", "size", "v0.4.0", remove_version="v0.6.0")
 @deprecate_parameter("columns", "incols", "v0.4.0", remove_version="v0.6.0")
+@check_data_input_order("v0.5.0", remove_version="v0.7.0")
 @use_alias(
     A="straight_line",
     B="frame",
@@ -53,7 +55,7 @@
     w="wrap",
 )
 @kwargs_to_strings(R="sequence", c="sequence_comma", i="sequence_comma", p="sequence")
-def plot(self, x=None, y=None, data=None, size=None, direction=None, **kwargs):
+def plot(self, data=None, x=None, y=None, size=None, direction=None, **kwargs):
     r"""
     Plot lines, polygons, and symbols in 2-D.
 
@@ -81,14 +83,14 @@ def plot(self, x=None, y=None, data=None, size=None, direction=None, **kwargs):
 
     Parameters
     ----------
-    x/y : float or 1d arrays
-        The x and y coordinates, or arrays of x and y coordinates of the
-        data points
     data : str or {table-like}
         Pass in either a file name to an ASCII data table, a 2D
         {table-classes}.
         Use parameter ``incols`` to choose which columns are x, y, color, and
         size, respectively.
+    x/y : float or 1d arrays
+        The x and y coordinates, or arrays of x and y coordinates of the
+        data points
     size : 1d array
         The size of the data points in units specified using ``style``.
         Only valid if using ``x``/``y``.

pygmt/tests/test_plot.py

@@ -435,27 +435,27 @@ def test_plot_datetime():
         ["2010-06-01", "2011-06-01T12", "2012-01-01T12:34:56"], dtype="datetime64"
     )
     y = [1.0, 2.0, 3.0]
-    fig.plot(x, y, style="c0.2c", pen="1p")
+    fig.plot(x=x, y=y, style="c0.2c", pen="1p")
 
     # pandas.DatetimeIndex
     x = pd.date_range("2013", freq="YS", periods=3)
     y = [4, 5, 6]
-    fig.plot(x, y, style="t0.2c", pen="1p")
+    fig.plot(x=x, y=y, style="t0.2c", pen="1p")
 
     # xarray.DataArray
     x = xr.DataArray(data=pd.date_range(start="2015-03", freq="QS", periods=3))
     y = [7.5, 6, 4.5]
-    fig.plot(x, y, style="s0.2c", pen="1p")
+    fig.plot(x=x, y=y, style="s0.2c", pen="1p")
 
     # raw datetime strings
     x = ["2016-02-01", "2017-03-04T00:00"]
     y = [7, 8]
-    fig.plot(x, y, style="a0.2c", pen="1p")
+    fig.plot(x=x, y=y, style="a0.2c", pen="1p")
 
     # the Python built-in datetime and date
     x = [datetime.date(2018, 1, 1), datetime.datetime(2019, 1, 1)]
     y = [8.5, 9.5]
-    fig.plot(x, y, style="i0.2c", pen="1p")
+    fig.plot(x=x, y=y, style="i0.2c", pen="1p")
     return fig