Return values of gmt.info

[seisman]

This issue is opened to further discuss the #106 (comment) about gmt.info.

Do you think we should print the output instead of returning it? There could be a flag to trigger a return instead of printing.

IMHO, returning the output makes more sense than printing it. It's easy for users to print it via print(gmt.info()) if they need.

Either way, if the returned string is just a list of numbers, it would be better to return an array/list of the number instead.

As far as I know, the outputs of gmt info can be divided into following types when different options are used:

Type 1

$ gmt info points.txt 
points.txt: N = 20	<11.5309/61.7074>	<-2.9289/7.8648>	<0.1412/0.9338>

I think this type is useless in most cases. We can leave it as it is.

Type 2

$ gmt info points.txt -C
11.5309	61.7074	-2.9289	7.8648	0.1412	0.9338

We can convert this type to a list/array.

Type 3

$ gmt info points.txt -I0.1                                                            
-R11.5/61.8/-3/7.9

-Rw/e/s/n is useless for Python. Should be convert to a list/array.

Type 4

$ gmt info points.txt -T0.1
-T11.5/61.8/0.1

Useless. Should be convert to a list/array.

Types 5

$ gmt info points.txt -Ib   
11.5309	-2.9289
61.7074	-2.9289
61.7074	7.8648
11.5309	7.8648
11.5309	-2.9289

gmt info -Ib reports the bounding box polygon for the data files, which is usually used in further fig.plot(). So it may make more sense to return it as two arrays x and y. A much general way is to return it as a ndarray, so users can access the first column via output[:,0] and the ith column via output[:,i-1].

If -Af|s option is used, the output becomes more complicated, e.g.:

$ gmt info points.txt points-copy.txt -C -Af
11.5309	61.7074	-2.9289	7.8648	0.1412	0.9338
11.5309	61.7074	-2.9289	7.8648	0.1412	0.9338

In such cases, we can return the output as a ndarray.

Conclusion

What we can do with the gmt.info outputs:

1. convert it to an array (type 2-4)
2. convert it to a multi-dimensional ndarray (type 2-5 and some more complicated cases).
3. leave the output as it is (type 1 and other cases not discussed in the issue).

[leouieda]

Hi @seisman, sorry I missed this issue. I think we can leave it the way it is for now. gmt.info probably won't be as useful in Python as it is on the command-line because we can get a lot of the same information from the Python containers.

I'll leave this open so we know to come back to it if the need arises.

[seisman]

I also agree with that gmt.info is mostly useless in Python. The above discussions may also apply to other modules like grdinfo, gmtselect et al. So we may further explore this later.

[leouieda]

Yep. Those should be very low in our list of things to wrap.

[liamtoney]

tl;dr

After reading the above discussion, I would like to work on more fully wrapping grdinfo. It seems like a potentially good "first issue," and I can see a benefit in wrapping it even with Python containers also available. See below, for example.

Motivation

In my use case, I want to easily see the min/max z-values of a DEM so that I can choose my colorbar limits.

1. No specified region

With GRIDFILE being the full path to my grid file, I could use

import gmt
print(gmt.grdinfo(GRIDFILE).strip())

...
../srtm15_plus_w180n90.nc: z_min: -7840.125 z_max: 6057.64355469 name: z
...

or (with xarray, for example)

import xarray
print(xarray.open_dataset(GRIDFILE).z.actual_range)

[-7840.125       6057.64355469]

These are about equal effort (and xarray returns things in a more usable output).

2. Specified region of interest

For viewing the min/maz z-values within a specified REGION = (lonmin, lonmax, latmin, latmax), I think that grdinfo makes this easier:

import gmt
print(gmt.grdinfo(GRIDFILE, R='{}/{}/{}/{}'.format(*REGION)).strip())

...
../srtm15_plus_w180n90.nc: z_min: -4996.11816406 z_max: 6057.64355469 name: z
...

vs.

import xarray
z = xarray.open_dataset(GRIDFILE).sel(lon=slice(*REGION[0:2]), lat=slice(*REGION[2:4])).z.values
print(z.min(), z.max())

-4996.118 6057.6436

Plus grdinfo is more format agnostic. By minimally including the @use_alias and @kwargs_to_strings decorators, the grdinfo command above could be just

print(gmt.grdinfo(GRIDFILE, region=REGION).strip())

and (with more work) could perhaps output a dictionary? Please let me know if this is a worthwhile effort and I'll make a PR for modules.py.