Change the function definition to 'grid, points=None' in an compatibl…

…e way

pygmt/src/grdtrack.py

@@ -1,7 +1,10 @@
 """
 grdtrack - Sample grids at specified (x,y) locations.
 """
+import warnings
+
 import pandas as pd
+import xarray as xr
 from pygmt.clib import Session
 from pygmt.exceptions import GMTInvalidInput
 from pygmt.helpers import (
@@ -11,6 +14,7 @@
     kwargs_to_strings,
     use_alias,
 )
+from pygmt.src.which import which
 
 __doctest_skip__ = ["grdtrack"]
 
@@ -43,7 +47,7 @@
     w="wrap",
 )
 @kwargs_to_strings(R="sequence", S="sequence", i="sequence_comma", o="sequence_comma")
-def grdtrack(points=None, grid=None, newcolname=None, outfile=None, **kwargs):
+def grdtrack(grid, points=None, newcolname=None, outfile=None, **kwargs):
     r"""
     Sample grids at specified (x,y) locations.
 
@@ -67,14 +71,14 @@ def grdtrack(points=None, grid=None, newcolname=None, outfile=None, **kwargs):
 
     Parameters
     ----------
-    points : str or {table-like}
-        Pass in either a file name to an ASCII data table, a 2D
-        {table-classes}.
-
     grid : xarray.DataArray or str
         Gridded array from which to sample values from, or a filename (netcdf
         format).
 
+    points : str or {table-like}
+        Pass in either a file name to an ASCII data table, a 2D
+        {table-classes}.
+
     newcolname : str
         Required if ``points`` is a :class:`pandas.DataFrame`. The name for the
         new column in the track :class:`pandas.DataFrame` table where the
@@ -292,6 +296,29 @@ def grdtrack(points=None, grid=None, newcolname=None, outfile=None, **kwargs):
     if points is not None and kwargs.get("E") is not None:
         raise GMTInvalidInput("Can't set both 'points' and 'profile'.")
 
+    # Backward compatibility with old parameter order "points, grid".
+    # deprecated_version="0.7.0", remove_version="v0.9.0"
+    is_a_grid = True
+    if not isinstance(grid, (xr.DataArray, xr.Dataset, str)):
+        is_a_grid = False
+    elif isinstance(grid, str):
+        try:
+            xr.open_dataarray(which(grid, download="a"))
+            is_a_grid = True
+        except ValueError:
+            is_a_grid = False
+    if not is_a_grid:
+        msg = (
+            "Positional parameters 'points, grid' of pygmt.grdtrack() is changed "
+            "to 'grid, points=None' since v0.7.0. It's likely that you're NOT "
+            "passing an valid grid as the first positional argument or "
+            "passing an invalid grid to the 'grid' parameter. "
+            "Please check the order of arguments with the latest documentation. "
+            "The warning will be removed in v0.9.0."
+        )
+        grid, points = points, grid
+        warnings.warn(msg, category=FutureWarning, stacklevel=1)
+
     with GMTTempFile(suffix=".csv") as tmpfile:
         with Session() as lib:
             # Store the xarray.DataArray grid in virtualfile

pygmt/tests/test_grdtrack.py

@@ -176,3 +176,18 @@ def test_grdtrack_set_points_and_profile(dataarray, dataframe):
     """
     with pytest.raises(GMTInvalidInput):
         grdtrack(grid=dataarray, points=dataframe, profile="BL/TR")
+
+
+def test_grdtrack_old_parameter_order(dataframe, dataarray, expected_array):
+    """
+    Run grdtrack with the old parameter order 'points, grid'.
+
+    This test should be removed in v0.9.0.
+    """
+    for points in (POINTS_DATA, dataframe):
+        for grid in ("@static_earth_relief.nc", dataarray):
+            with pytest.warns(expected_warning=FutureWarning) as record:
+                output = grdtrack(points, grid)
+                assert len(record) == 1
+                assert isinstance(output, pd.DataFrame)
+                npt.assert_allclose(np.array(output), expected_array)