pygmt.grdclip: Clip the range of grid values

[seisman]

This is the central issue to track the implementation of the pygmt.grdclip method.

• GMT doc: https://docs.generic-mapping-tools.org/6.5/grdclip.html
• PyGMT doc: https://www.pygmt.org/dev/api/generated/pygmt.grdclip.html
• GMT.jl doc: https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/grdclip/

GMT options

Checked: Implemented; Unchecked: To be implemented/discussed; Strikethrough: Won't implement.

• <ingrid> Wrap grdclip #1261
• -G<outgrid> Wrap grdclip #1261
• -R: region Wrap grdclip #1261
• -Sa<high>/<above>[+e]: above Wrap grdclip #1261
• -Sb<low>/<below>[+e]: below Wrap grdclip #1261
• -Si<low>/<high>/<between>: between Wrap grdclip #1261
• -Sr<old>/<new>: new Wrap grdclip #1261
• -V: verbose Wrap grdclip #1261
• --PAR=<value>: Use pygmt.config()

[seisman]

grdclip is one of the simple modules that have very few options. In PR #3883, I've tried to improve the pygmt.grdclip function, but before that, I'd like to ask your opinion about renaming the parameter new to replace.

-Srold/new
Set all data[i] == old to new. This is mostly useful when your data are known to be integer values. Repeat the option for as many replacements as are needed.

• PyGMT uses new
• GMT.jl supports old or new (GMT.jl allows multiple aliases for the same option)
• GMT recommends replace or new (https://github.com/GenericMappingTools/gmt/blob/23be98456397b75c44f5701d1c47936739f021f7/src/longopt/grdclip_inc.h#L30)

I feel replace is a better name than new.

[yvonnefroehlich]

I feel replace is a better name than new.

For me a renaming to replace makes sense, as this alias is more descriptive.

[seisman]

-Sahigh/above[+e]
Sets all values where data[i] > high to above. The +e modifier includes equality, meaning data[i] ≥ high.

This option is aliased as above, with the Pythonic syntax accepting a two-value sequence (e.g., above=(100, 200)). However, there is no direct Pythonic equivalent for the +e modifier. If users need to include equality, a simple workaround is to slightly decrease high (e.g., above=(99.999, 200)). In other words, there is no need to implement a dedicated Pythonic solution for +e.

The same goes for -Sb.

For -Si and -Sr, both of them can be repeated for as many intervals as are needed. Currently, between and replace only accept 1-D sequence. PR #3883 will adds 2-D sequence support to these two parameters.