From 2cbccd31d0f70f72c2246a90f84fbf2a47b4cd86 Mon Sep 17 00:00:00 2001
From: Michael Grund <23025878+michaelgrund@users.noreply.github.com>
Date: Sun, 3 Oct 2021 04:02:25 +0200
Subject: [PATCH] Figure.plot: Reorder input parameters to "data, x, y" (#1547)

* Update plot.py
* add decorator
* adjust test_plot_datetime
* adjust gallery examples
---
 examples/gallery/symbols/datetime_inputs.py | 10 +++++-----
 examples/gallery/symbols/points.py          |  2 +-
 pygmt/src/plot.py                           | 10 ++++++----
 pygmt/tests/test_plot.py                    | 10 +++++-----
 4 files changed, 17 insertions(+), 15 deletions(-)

diff --git a/examples/gallery/symbols/datetime_inputs.py b/examples/gallery/symbols/datetime_inputs.py
index 73bd35cdd0f..0592729d44a 100644
--- a/examples/gallery/symbols/datetime_inputs.py
+++ b/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()
diff --git a/examples/gallery/symbols/points.py b/examples/gallery/symbols/points.py
index 02942f3400b..e9c32aa914f 100644
--- a/examples/gallery/symbols/points.py
+++ b/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()
diff --git a/pygmt/src/plot.py b/pygmt/src/plot.py
index 024d71b5ea8..d684e1ceb94 100644
--- a/pygmt/src/plot.py
+++ b/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``.
diff --git a/pygmt/tests/test_plot.py b/pygmt/tests/test_plot.py
index dc6829b9ecf..46d7ae5bc33 100644
--- a/pygmt/tests/test_plot.py
+++ b/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