Convenience classes and additional keywords

[mjziebarth]

Add more convenience classes or keyword parameters to facilitate ease of use

First off: Thanks for the work so far!

Coming from the scipy ecosystem and being an avid matplotlib user, I figured I'd leave some feedback from my experience starting with gmt-python. Since I'll likely be using it during the next couple of years, I'm willing to implement the ideas I have, but they may be quite big so I figured it would be best to discuss them beforehand.

I really like gmt as a tool and the achievable results, but the learning curve is quite steep. Especially since the documentation is not really concise or easy to read and there does not seem to be a big question-answering community around, at least in my limited experience. So I feel like one of the big advantages of gmt-python besides the native interaction with python would be to use the quite common python-intuitivity.

That being said, here's some ideas I had (some obviously inspired by my experiences with matplotlib):

• Create convenience classes that wrap the interaction with some parts of the gmt workflow. E.g. a Grid-class that can be created from numpy arrays and passed to the grdimage method, handling the xyz2grid calls internally (possibly with caching and whatnot). Or a Colormap class that handles the .cpt creation automatically (like the matplotlib colormaps). Or projection classes that have all the required configuration inside their __init__s

• Add further self-describing keywords (like List of GMT aliases #48) that are automatically converted to the gmt argument string inside e.g. Figure.plot.

In the end, this mostly boils down to creating more logic inside the methods and wrapping the gmt syntax into the structure supplied by the python language. I have some conceptional code which I use myself in this repository, just to give you a rough idea.

What do you think about the idea? In case the two points seem generally interesting, I'd be willing to discuss in detail what could be possible implementations and develop them.

Are you willing to help implement and maintain this feature?

Yes

[weiji14]

Hi @mjziebarth 👋, I know it's been almost 2 years since this was posted, and you'd probably moved on with other things in life, but just to give you (and others) a bit of an update on what we have/haven't achieved in terms of your ideas:

Create convenience classes that wrap the interaction with some parts of the gmt workflow. E.g. a Grid-class that can be created from numpy arrays and passed to the grdimage method, handling the xyz2grid calls internally (possibly with caching and whatnot).

We are able to pass in xarray.DataArray grids into grdimage now, which is somewhat different from your original numpy suggestion, but having labelled x and y coordinates is nice! The xyz2grd function is not yet implemented still (:octocat: PR welcome!), but we do have pygmt.surface to turn points into grids.

Or a Colormap class that handles the .cpt creation automatically (like the matplotlib colormaps).

I really like the work you've done at https://github.com/mjziebarth/gmt-python-extensions/blob/master/gmt_extensions/colormap.py. We do have makecpt, and a request for grd2cpt, but being able to use matplotlib colormaps in pygmt would be quite nice (:octocat: PR welcome!).

Or projection classes that have all the required configuration inside their __init__s

This has falling off as of late, but there's is a Work-in-Progress PR at #379. Happy for someone else to pick it up and continue the work.

Add further self-describing keywords (like #48) that are automatically converted to the gmt argument string inside e.g. Figure.plot.

We've done a lot of work turning all short aliases into long aliases at #474, and the intention is that only long-form keyword arguments are documented by default (though short-form aliases like -B still work silently for GMT veterans).

I really like gmt as a tool and the achievable results, but the learning curve is quite steep. Especially since the documentation is not really concise or easy to read and there does not seem to be a big question-answering community around, at least in my limited experience.

The GMT team has migrated the old forum from http://gmt.soest.hawaii.edu/projects/gmt/boards to a more modern-looking one at https://forum.generic-mapping-tools.org/, and the Q&A community is certainly quite active!

So in summary, there's a lot that's been done, but also a lot of room for improvement still! One thing we're trying to balance is the habits of users who are familiar with the classic GMT style, and those who don't know GMT much at all, or just come from the Python ecosystem. It's a tough thing to juggle, but I do think convenience is still a key factor in PyGMT's development and the more we know how users use PyGMT, the better we can make it.