diff --git a/pygmt/modules.py b/pygmt/modules.py index 94512ec325d..1cacf67d6df 100644 --- a/pygmt/modules.py +++ b/pygmt/modules.py @@ -60,14 +60,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 +86,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 +120,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. + if result.startswith(("-R", "-T")): # e.g. -R0/1/2/3 or -T0/9/1 + result = result[2:].replace("/", " ") + result = np.loadtxt(result.splitlines()) + + return result @fmt_docstring diff --git a/pygmt/tests/test_info.py b/pygmt/tests/test_info.py index b7eadc53649..142b56dce8e 100644 --- a/pygmt/tests/test_info.py +++ b/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():