Wrap grdhisteq

[maxrjones]

Description of proposed changes

This PR will wrap the gmt module grdhisteq.

Preview docs at https://pygmt-git-grdhisteq-gmt.vercel.app/api/generated/pygmt.grdhisteq.html

Fixes #1399

Reminders

• Run make format and make check to make sure the code follows the style guide.
• Add tests for new features or tests that would have caught the bug that you're fixing.
• Add new public functions/methods/classes to doc/api/index.rst.
• Write detailed docstrings for all functions/methods.
• If adding new functionality, add an example to docstrings or tutorials.

Slash Commands

You can write slash commands (/command) in the first line of a comment to perform
specific operations. Supported slash commands are:

• /format: automatically format and lint the code
• /test-gmt-dev: run full tests on the latest GMT development version

[weiji14]

Gentle push on this. I'm starting a project using Sentinel 2 data so I imagine this function would come in handy at some point for doing histogram equalized plots 😄

Looking at https://docs.generic-mapping-tools.org/6.2/grdhisteq.html closely, it seems that both grid outputs (-G) and table outputs (-D) are possible. Happy to only do grid outputs for now, but if you want to do table outputs too, the triangulate implementation at #731 can be a good resource to follow.

P.S. Recommend to update branch and resolve merge conflict before applying suggested changes below.

[maxrjones]

Gentle push on this. I'm starting a project using Sentinel 2 data so I imagine this function would come in handy at some point for doing histogram equalized plots 😄

I'll try to wrap up the remaining tasks (i.e., polishing docstring, adding table output test) tomorrow.

Edit: I will need a bit longer to finish this, since the implementation will depend on the results from GenericMappingTools/gmt#5785.

[maxrjones]

I changed the implementation a bit relative to #731 to support ASCII or pandas.DataFrame output for writing out the equalized histogram.

Still, the code is a bit clunky in order to support four different output types (pandas.DataFrame, xarray.DataArray, netCDF, or ASCII). What would you think about having two PyGMT functions for GMT's grdhisteq module rather than just one? One function could write out the data ranges of histogram equalization to a pd.DataFrame or ASCII table and the other could write out the cumulative distribution statistics to a netCDF file or xarray.DataArray. I guess coming up with the names for these would be harder than the current implementation, but I think it would be more user friendly long-term.

[maxrjones]

Nice one. Looking forward to using this in my project soon! I'm getting sick of arbitrarily stretching optical satellite images...

Thanks for all your helpful feedback!

[seisman]

Perhaps we should raise an exception here rather than give a warning? Sometimes people just ignore warnings.

[maxrjones]

There was a bit of a discussion about this following this comment #1284 (review). See #1284 (comment) for a specific discussion about raising a warning versus exception. I think we should follow that lead, although we could move this to a helper function to make it more clear that the logic is used for multiple modules.