Sensible array outputs for pygmt info

pygmt/modules.py

@@ -1,6 +1,8 @@
 """
 Non-plot GMT modules.
 """
+import re
+
 import numpy as np
 import xarray as xr
 
@@ -60,14 +62,17 @@ def info(table, **kwargs):
     """
     Get information about data tables.
 
-    Reads from files and finds the extreme values in each of the columns.
-    It recognizes NaNs and will print warnings if the number of columns vary
-    from record to record. As an option, it will find the extent of the first
-    n columns rounded up and down to the nearest multiple of the supplied
-    increments. By default, this output will be in the form *-Rw/e/s/n*,
-    or the output will be in column form for as many columns as there are
-    increments provided. The *nearest_multiple* option will provide a
-    *-Tzmin/zmax/dz* string for makecpt.
+    Reads from files and finds the extreme values in each of the columns
+    reported as min/max pairs. It recognizes NaNs and will print warnings if
+    the number of columns vary from record to record. As an option, it will
+    find the extent of the first two columns rounded up and down to the nearest
+    multiple of the supplied increments given by *spacing*. Such output will be
+    in a numpy.ndarray form ``[w, e, s, n]``, which can be used directly as the
+    *region* argument for other modules (hence only dx and dy are needed). If
+    the *per_column* option is combined with *spacing*, then the numpy.ndarray
+    output will be rounded up/down for as many columns as there are increments
+    provided in *spacing*. A similar option *nearest_multiple* option will
+    provide a numpy.ndarray in the form of ``[zmin, zmax, dz]`` for makecpt.
 
     Full option list at :gmt-docs:`gmtinfo.html`
 
@@ -83,12 +88,21 @@ def info(table, **kwargs):
     spacing : str
         ``'[b|p|f|s]dx[/dy[/dz...]]'``.
         Report the min/max of the first n columns to the nearest multiple of
-        the provided increments and output results in the form *-Rw/e/s/n*
-        (unless *per_column* is set).
+        the provided increments and output results in the form
+        ``[w, e, s, n]``.
     nearest_multiple : str
         ``'dz[+ccol]'``
         Report the min/max of the first (0'th) column to the nearest multiple
-        of dz and output this as the string *-Tzmin/zmax/dz*.
+        of dz and output this in the form ``[zmin, zmax, dz]``.
+
+    Returns
+    -------
+    output : np.ndarray or str
+        Return type depends on whether any of the 'per_column', 'spacing', or
+        'nearest_multiple' parameters are set.
+
+        - np.ndarray if either of the above parameters are used.
+        - str if none of the above parameters are used.
     """
     kind = data_kind(table)
     with Session() as lib:
@@ -108,7 +122,16 @@ def info(table, **kwargs):
                     [fname, build_arg_string(kwargs), "->" + tmpfile.name]
                 )
                 lib.call_module("info", arg_str)
-            return tmpfile.read()
+            result = tmpfile.read()
+
+        if any(arg in kwargs for arg in ["C", "I", "T"]):
+            # Converts certain output types into a numpy array
+            # instead of a raw string that is less useful.
+            result = np.loadtxt(
+                re.sub(pattern="-R|-T|/", repl=" ", string=result).splitlines()
+            )
+
+        return result
 
 
 @fmt_docstring

pygmt/tests/test_info.py

@@ -4,6 +4,7 @@
 import os
 
 import numpy as np
+import numpy.testing as npt
 import pandas as pd
 import pytest
 import xarray as xr
@@ -57,25 +58,42 @@ def test_info_1d_array():
 def test_info_per_column():
     "Make sure the per_column option works"
     output = info(table=POINTS_DATA, per_column=True)
-    assert output == "11.5309 61.7074 -2.9289 7.8648 0.1412 0.9338\n"
+    npt.assert_allclose(
+        actual=output, desired=[11.5309, 61.7074, -2.9289, 7.8648, 0.1412, 0.9338]
+    )
 
 
 def test_info_spacing():
     "Make sure the spacing option works"
     output = info(table=POINTS_DATA, spacing=0.1)
-    assert output == "-R11.5/61.8/-3/7.9\n"
+    npt.assert_allclose(actual=output, desired=[11.5, 61.8, -3, 7.9])
+
+
+def test_info_spacing_bounding_box():
+    "Make sure the spacing option for writing a bounding box works"
+    output = info(table=POINTS_DATA, spacing="b")
+    npt.assert_allclose(
+        actual=output,
+        desired=[
+            [11.5309, -2.9289],
+            [61.7074, -2.9289],
+            [61.7074, 7.8648],
+            [11.5309, 7.8648],
+            [11.5309, -2.9289],
+        ],
+    )
 
 
 def test_info_per_column_spacing():
     "Make sure the per_column and spacing options work together"
     output = info(table=POINTS_DATA, per_column=True, spacing=0.1)
-    assert output == "11.5 61.8 -3 7.9 0.1412 0.9338\n"
+    npt.assert_allclose(actual=output, desired=[11.5, 61.8, -3, 7.9, 0.1412, 0.9338])
 
 
 def test_info_nearest_multiple():
     "Make sure the nearest_multiple option works"
     output = info(table=POINTS_DATA, nearest_multiple=0.1)
-    assert output == "-T11.5/61.8/0.1\n"
+    npt.assert_allclose(actual=output, desired=[11.5, 61.8, 0.1])
 
 
 def test_info_fails():