Merge branch 'master' into contrib-guide

pygmt/src/blockm.py

@@ -12,7 +12,7 @@
 )
 
 
-def _blockm(block_method, table, outfile, **kwargs):
+def _blockm(block_method, table, outfile, x, y, z, **kwargs):
     r"""
     Block average (x,y,z) data tables by mean or median estimation.
 
@@ -41,7 +41,9 @@ def _blockm(block_method, table, outfile, **kwargs):
     with GMTTempFile(suffix=".csv") as tmpfile:
         with Session() as lib:
             # Choose how data will be passed into the module
-            table_context = lib.virtualfile_from_data(check_kind="vector", data=table)
+            table_context = lib.virtualfile_from_data(
+                check_kind="vector", data=table, x=x, y=y, z=z
+            )
             # Run blockm* on data table
             with table_context as infile:
                 if outfile is None:
@@ -73,14 +75,18 @@ def _blockm(block_method, table, outfile, **kwargs):
     r="registration",
 )
 @kwargs_to_strings(R="sequence")
-def blockmean(table, outfile=None, **kwargs):
+def blockmean(table=None, outfile=None, *, x=None, y=None, z=None, **kwargs):
     r"""
     Block average (x,y,z) data tables by mean estimation.
 
     Reads arbitrarily located (x,y,z) triples [or optionally weighted
-    quadruples (x,y,z,w)] from a table and writes to the output a mean
-    position and value for every non-empty block in a grid region defined by
-    the ``region`` and ``spacing`` parameters.
+    quadruples (x,y,z,w)] and writes to the output a mean position and value
+    for every non-empty block in a grid region defined by the ``region`` and
+    ``spacing`` parameters.
+
+    Takes a matrix, xyz triplets, or a file name as input.
+
+    Must provide either ``table`` or ``x``, ``y``, and ``z``.
 
     Full option list at :gmt-docs:`blockmean.html`
 
@@ -92,12 +98,12 @@ def blockmean(table, outfile=None, **kwargs):
         Pass in (x, y, z) or (longitude, latitude, elevation) values by
         providing a file name to an ASCII data table, a 2D
         {table-classes}.
+    x/y/z : 1d arrays
+        Arrays of x and y coordinates and values z of the data points.
 
     {I}
 
-    region : str or list
-        *xmin/xmax/ymin/ymax*\[\ **+r**\][**+u**\ *unit*].
-        Specify the region of interest.
+    {R}
 
     outfile : str
         The file name for the output ASCII file.
@@ -114,11 +120,13 @@ def blockmean(table, outfile=None, **kwargs):
         Return type depends on whether the ``outfile`` parameter is set:
 
         - :class:`pandas.DataFrame` table with (x, y, z) columns if ``outfile``
-          is not set
+          is not set.
         - None if ``outfile`` is set (filtered output will be stored in file
-          set by ``outfile``)
+          set by ``outfile``).
     """
-    return _blockm(block_method="blockmean", table=table, outfile=outfile, **kwargs)
+    return _blockm(
+        block_method="blockmean", table=table, outfile=outfile, x=x, y=y, z=z, **kwargs
+    )
 
 
 @fmt_docstring
@@ -132,14 +140,18 @@ def blockmean(table, outfile=None, **kwargs):
     r="registration",
 )
 @kwargs_to_strings(R="sequence")
-def blockmedian(table, outfile=None, **kwargs):
+def blockmedian(table=None, outfile=None, *, x=None, y=None, z=None, **kwargs):
     r"""
     Block average (x,y,z) data tables by median estimation.
 
     Reads arbitrarily located (x,y,z) triples [or optionally weighted
-    quadruples (x,y,z,w)] from a table and writes to the output a median
-    position and value for every non-empty block in a grid region defined by
-    the ``region`` and ``spacing`` parameters.
+    quadruples (x,y,z,w)] and writes to the output a median position and value
+    for every non-empty block in a grid region defined by the ``region`` and
+    ``spacing`` parameters.
+
+    Takes a matrix, xyz triplets, or a file name as input.
+
+    Must provide either ``table`` or ``x``, ``y``, and ``z``.
 
     Full option list at :gmt-docs:`blockmedian.html`
 
@@ -151,12 +163,12 @@ def blockmedian(table, outfile=None, **kwargs):
         Pass in (x, y, z) or (longitude, latitude, elevation) values by
         providing a file name to an ASCII data table, a 2D
         {table-classes}.
+    x/y/z : 1d arrays
+        Arrays of x and y coordinates and values z of the data points.
 
     {I}
 
-    region : str or list
-        *xmin/xmax/ymin/ymax*\[\ **+r**\][**+u**\ *unit*].
-        Specify the region of interest.
+    {R}
 
     outfile : str
         The file name for the output ASCII file.
@@ -173,8 +185,16 @@ def blockmedian(table, outfile=None, **kwargs):
         Return type depends on whether the ``outfile`` parameter is set:
 
         - :class:`pandas.DataFrame` table with (x, y, z) columns if ``outfile``
-          is not set
+          is not set.
         - None if ``outfile`` is set (filtered output will be stored in file
-          set by ``outfile``)
+          set by ``outfile``).
     """
-    return _blockm(block_method="blockmedian", table=table, outfile=outfile, **kwargs)
+    return _blockm(
+        block_method="blockmedian",
+        table=table,
+        outfile=outfile,
+        x=x,
+        y=y,
+        z=z,
+        **kwargs
+    )

pygmt/tests/test_blockmean.py

@@ -43,6 +43,22 @@ def test_blockmean_input_table_matrix(dataframe):
     npt.assert_allclose(output.iloc[0], [245.888877, 29.978707, -384.0])
 
 
+def test_blockmean_input_xyz(dataframe):
+    """
+    Run blockmean by passing in x/y/z as input.
+    """
+    output = blockmean(
+        x=dataframe.longitude,
+        y=dataframe.latitude,
+        z=dataframe.bathymetry,
+        spacing="5m",
+        region=[245, 255, 20, 30],
+    )
+    assert isinstance(output, pd.DataFrame)
+    assert output.shape == (5849, 3)
+    npt.assert_allclose(output.iloc[0], [245.888877, 29.978707, -384.0])
+
+
 def test_blockmean_wrong_kind_of_input_table_grid(dataframe):
     """
     Run blockmean using table input that is not a pandas.DataFrame or file but

pygmt/tests/test_blockmedian.py

@@ -31,7 +31,7 @@ def test_blockmedian_input_dataframe(dataframe):
     npt.assert_allclose(output.iloc[0], [245.88819, 29.97895, -385.0])
 
 
-def test_blockmedian_wrong_kind_of_input_table_matrix(dataframe):
+def test_blockmedian_input_table_matrix(dataframe):
     """
     Run blockmedian using table input that is not a pandas.DataFrame but still
     a matrix.
@@ -43,6 +43,22 @@ def test_blockmedian_wrong_kind_of_input_table_matrix(dataframe):
     npt.assert_allclose(output.iloc[0], [245.88819, 29.97895, -385.0])
 
 
+def test_blockmedian_input_xyz(dataframe):
+    """
+    Run blockmedian by passing in x/y/z as input.
+    """
+    output = blockmedian(
+        x=dataframe.longitude,
+        y=dataframe.latitude,
+        z=dataframe.bathymetry,
+        spacing="5m",
+        region=[245, 255, 20, 30],
+    )
+    assert isinstance(output, pd.DataFrame)
+    assert output.shape == (5849, 3)
+    npt.assert_allclose(output.iloc[0], [245.88819, 29.97895, -385.0])
+
+
 def test_blockmedian_wrong_kind_of_input_table_grid(dataframe):
     """
     Run blockmedian using table input that is not a pandas.DataFrame or file