Modify grdtrack parameter names according to code review

Rename 'table' parameter to 'points', remove default 'newcolname' parameter (require it to be explicitly set) and change the output 'ret' to 'track' in docstring. Unit tests updated accordingly.

Author: weiji14

pygmt/sampling.py

@@ -16,7 +16,9 @@
 
 
 @fmt_docstring
-def grdtrack(table: pd.DataFrame, grid: xr.DataArray, newcolname: str = "z_", **kwargs):
+def grdtrack(
+    points: pd.DataFrame, grid: xr.DataArray, newcolname: str = None, **kwargs
+):
     """
     Sample grids at specified (x,y) locations.
 
@@ -29,7 +31,7 @@ def grdtrack(table: pd.DataFrame, grid: xr.DataArray, newcolname: str = "z_", **
 
     Parameters
     ----------
-    table: pandas.DataFrame
+    points: pandas.DataFrame
         Table with (x, y) or (lon, lat) values in the first two columns. More columns
         may be present.
 
@@ -38,21 +40,26 @@ def grdtrack(table: pd.DataFrame, grid: xr.DataArray, newcolname: str = "z_", **
 
     newcolname: str
         Name for the new column in the table where the sampled values will be placed.
-        Defaults to "z_".
 
     Returns
     -------
-    ret: pandas.DataFrame
-        Table with (x, y, ..., z_) or (lon, lat, ..., z_) values.
+    track: pandas.DataFrame
+        Table with (x, y, ..., newcolname) or (lon, lat, ..., newcolname) values.
 
     """
+
+    try:
+        assert isinstance(newcolname, str)
+    except AssertionError:
+        raise GMTInvalidInput("Please pass in a str to 'newcolname'")
+
     with GMTTempFile(suffix=".csv") as tmpfile:
         with Session() as lib:
-            # Store the pandas.DataFrame table in virtualfile
-            if data_kind(table) == "matrix":
-                table_context = lib.virtualfile_from_matrix(table.values)
+            # Store the pandas.DataFrame points table in virtualfile
+            if data_kind(points) == "matrix":
+                table_context = lib.virtualfile_from_matrix(points.values)
             else:
-                raise GMTInvalidInput(f"Unrecognized data type {type(table)}")
+                raise GMTInvalidInput(f"Unrecognized data type {type(points)}")
 
             # Store the xarray.DataArray grid in virtualfile
             if data_kind(grid) == "grid":
@@ -62,7 +69,7 @@ def grdtrack(table: pd.DataFrame, grid: xr.DataArray, newcolname: str = "z_", **
             else:
                 raise GMTInvalidInput(f"Unrecognized data type {type(grid)}")
 
-            # Run grdtrack on the temporary (csv) table and (netcdf) grid virtualfiles
+            # Run grdtrack on the temp (csv) points table and (netcdf) grid virtualfiles
             with table_context as csvfile:
                 with grid_context as grdfile:
                     kwargs.update({"G": grdfile})
@@ -72,7 +79,7 @@ def grdtrack(table: pd.DataFrame, grid: xr.DataArray, newcolname: str = "z_", **
                     lib.call_module(module="grdtrack", args=arg_str)
 
         # Read temporary csv output to a pandas table
-        column_names = table.columns.to_list() + [newcolname]
+        column_names = points.columns.to_list() + [newcolname]
         result = pd.read_csv(tmpfile.name, sep="\t", names=column_names)
 
     return result

pygmt/tests/test_grdtrack.py

@@ -19,9 +19,9 @@ def test_grdtrack_input_dataframe_and_dataarray():
     dataframe = load_ocean_ridge_points()
     dataarray = load_east_pacific_rise_grid()
 
-    output = grdtrack(table=dataframe, grid=dataarray)
+    output = grdtrack(points=dataframe, grid=dataarray, newcolname="bathymetry")
     assert isinstance(output, pd.DataFrame)
-    assert output.columns.to_list() == ["longitude", "latitude", "z_"]
+    assert output.columns.to_list() == ["longitude", "latitude", "bathymetry"]
     assert output.iloc[0].to_list() == [-110.9536, -42.2489, -2950.49576833]
 
     return output
@@ -34,27 +34,28 @@ def test_grdtrack_input_dataframe_and_ncfile():
     dataframe = load_ocean_ridge_points()
     ncfile = which("@spac_33.nc", download="c")
 
-    output = grdtrack(table=dataframe, grid=ncfile)
+    output = grdtrack(points=dataframe, grid=ncfile, newcolname="bathymetry")
     assert isinstance(output, pd.DataFrame)
-    assert output.columns.to_list() == ["longitude", "latitude", "z_"]
+    assert output.columns.to_list() == ["longitude", "latitude", "bathymetry"]
+    assert output.iloc[0].to_list() == [-110.9536, -42.2489, -2950.49576833]
 
     return output
 
 
-def test_grdtrack_input_wrong_kind_of_table():
+def test_grdtrack_wrong_kind_of_points_input():
     """
-    Run grdtrack using table input that is not a pandas.DataFrame (matrix)
+    Run grdtrack using points input that is not a pandas.DataFrame (matrix)
     """
     dataframe = load_ocean_ridge_points()
-    invalid_table = dataframe.longitude.to_xarray()
+    invalid_points = dataframe.longitude.to_xarray()
     dataarray = load_east_pacific_rise_grid()
 
-    assert data_kind(invalid_table) == "grid"
+    assert data_kind(invalid_points) == "grid"
     with pytest.raises(GMTInvalidInput):
-        grdtrack(table=invalid_table, grid=dataarray)
+        grdtrack(points=invalid_points, grid=dataarray, newcolname="bathymetry")
 
 
-def test_grdtrack_input_wrong_kind_of_grid():
+def test_grdtrack_wrong_kind_of_grid_input():
     """
     Run grdtrack using grid input that is not as xarray.DataArray (grid) or file
     """
@@ -64,18 +65,15 @@ def test_grdtrack_input_wrong_kind_of_grid():
 
     assert data_kind(invalid_grid) == "matrix"
     with pytest.raises(GMTInvalidInput):
-        grdtrack(table=dataframe, grid=invalid_grid)
+        grdtrack(points=dataframe, grid=invalid_grid, newcolname="bathymetry")
 
 
-def test_grdtrack_newcolname_setting():
+def test_grdtrack_without_newcolname_setting():
     """
-    Run grdtrack by passing in a non-default newcolname parameter setting
+    Run grdtrack by not passing in newcolname parameter setting
     """
     dataframe = load_ocean_ridge_points()
     dataarray = load_east_pacific_rise_grid()
 
-    output = grdtrack(table=dataframe, grid=dataarray, newcolname="bathymetry")
-    assert output.columns.to_list() == ["longitude", "latitude", "bathymetry"]
-    assert output.iloc[0].to_list() == [-110.9536, -42.2489, -2950.49576833]
-
-    return output
+    with pytest.raises(GMTInvalidInput):
+        grdtrack(points=dataframe, grid=dataarray)