Expand table-like input options for sphdistance (#1491)

*Add parameter and tests for x/y inputs
*Rename "table" parameter to "data"
*Improve docstring for new parameters

Co-authored-by: Wei Ji <[email protected]>
Co-authored-by: Dongdong Tian <[email protected]>

doc/api/index.rst

@@ -84,6 +84,7 @@ Operations on tabular data:
     blockmode
     nearneighbor
     sph2grd
+    sphdistance
     sphinterpolate
     surface
 
@@ -102,7 +103,6 @@ Operations on grids:
     grdproject
     grdsample
     grdtrack
-    sphdistance
     xyz2grd
 
 Crossover analysis with x2sys:

pygmt/src/sphdistance.py

@@ -22,19 +22,28 @@
     V="verbose",
 )
 @kwargs_to_strings(I="sequence", R="sequence")
-def sphdistance(table, **kwargs):
+def sphdistance(data=None, x=None, y=None, **kwargs):
     r"""
-    Create Voroni polygons from lat/lon coordinates.
+    Create Voronoi distance, node, or natural nearest-neighbor grid on a
+    sphere.
 
-    Reads one or more ASCII [or binary] files (or standard
-    input) containing lon, lat and performs the construction of Voronoi
-    polygons. These polygons are then processed to calculate the nearest
-    distance to each node of the lattice and written to the specified grid.
+    Reads a table containing *lon, lat* columns and performs
+    the construction of Voronoi polygons. These polygons are
+    then processed to calculate the nearest distance to each
+    node of the lattice and written to the specified grid.
+
+    Full option list at :gmt-docs:`sphdistance.html
 
     {aliases}
 
     Parameters
     ----------
+    data : str or {table-like}
+        Pass in (x, y) or (longitude, latitude) values by
+        providing a file name to an ASCII data table, a 2D
+        {table-classes}.
+    x/y : 1d arrays
+        Arrays of x and y coordinates.
     outgrid : str or None
         The name of the output netCDF file with extension .nc to store the grid
         in.
@@ -46,6 +55,7 @@ def sphdistance(table, **kwargs):
     -------
     ret: xarray.DataArray or None
         Return type depends on whether the ``outgrid`` parameter is set:
+
         - :class:`xarray.DataArray` if ``outgrid`` is not set
         - None if ``outgrid`` is set (grid output will be stored in file set by
           ``outgrid``)
@@ -54,7 +64,9 @@ def sphdistance(table, **kwargs):
         raise GMTInvalidInput("Both 'region' and 'spacing' must be specified.")
     with GMTTempFile(suffix=".nc") as tmpfile:
         with Session() as lib:
-            file_context = lib.virtualfile_from_data(check_kind="vector", data=table)
+            file_context = lib.virtualfile_from_data(
+                check_kind="vector", data=data, x=x, y=y
+            )
             with file_context as infile:
                 if "G" not in kwargs.keys():  # if outgrid is unset, output to tempfile
                     kwargs.update({"G": tmpfile.name})

pygmt/tests/test_sphdistance.py

@@ -20,13 +20,29 @@ def fixture_table():
     return np.array(coords_list)
 
 
+def test_sphdistance_xy_inputs():
+    """
+    Test inputs using separate xy arguments.
+    """
+    y = [22.3, 22.6, 22.4, 23.3]
+    x = [85.5, 82.3, 85.8, 86.5]
+    temp_grid = sphdistance(x=x, y=y, spacing=[1, 2], region=[82, 87, 22, 24])
+    assert temp_grid.dims == ("lat", "lon")
+    assert temp_grid.gmt.gtype == 1  # Geographic grid
+    assert temp_grid.gmt.registration == 0  # Gridline registration
+    npt.assert_allclose(temp_grid.max(), 232977.546875)
+    npt.assert_allclose(temp_grid.min(), 0)
+    npt.assert_allclose(temp_grid.median(), 0)
+    npt.assert_allclose(temp_grid.mean(), 62469.17)
+
+
 def test_sphdistance_outgrid(array):
     """
     Test sphdistance with a set outgrid.
     """
     with GMTTempFile(suffix=".nc") as tmpfile:
         result = sphdistance(
-            table=array, outgrid=tmpfile.name, spacing=1, region=[82, 87, 22, 24]
+            data=array, outgrid=tmpfile.name, spacing=1, region=[82, 87, 22, 24]
         )
         assert result is None  # return value is None
         assert os.path.exists(path=tmpfile.name)  # check that outgrid exists
@@ -36,7 +52,7 @@ def test_sphdistance_no_outgrid(array):
     """
     Test sphdistance with no set outgrid.
     """
-    temp_grid = sphdistance(table=array, spacing=[1, 2], region=[82, 87, 22, 24])
+    temp_grid = sphdistance(data=array, spacing=[1, 2], region=[82, 87, 22, 24])
     assert temp_grid.dims == ("lat", "lon")
     assert temp_grid.gmt.gtype == 1  # Geographic grid
     assert temp_grid.gmt.registration == 0  # Gridline registration
@@ -52,4 +68,4 @@ def test_sphdistance_fails(array):
     given.
     """
     with pytest.raises(GMTInvalidInput):
-        sphdistance(table=array)
+        sphdistance(data=array)