Add region docstring to COMMON_OPTIONS for non-plotting modules

[willschlitzer]

The use of {R} in docstrings begins with "Required if this is the first plot command.", which doesn't make sense for not plotting modules. I think there should be an {R-noplot}-type option that just states that the region can be set.

Are you willing to help implement and maintain this feature? Yes

[maxrjones]

Good point. Another factor is that region and projection are not always required for the first plot command (not well documented in GMT, I'll look into fixing this but cannot easily find the conversation about when these are and are not required). Here is an example that works fine without region or projection.

import pygmt

data = pygmt.datasets.load_sample_bathymetry()

fig = pygmt.Figure()
fig.plot(data=data, style="p1p")
fig.show()

[seisman]

Another factor is that region and projection are not always required for the first plot command (not well documented in GMT, I'll look into fixing this but cannot easily find the conversation about when these are and are not required).

The THIS_MODULE_NEEDS macro in the C code determine if -J or -R option is required. For example, JR means both -J and -R are required, d or g means the module can determine the region from the input dataset or grid, thus -R option is not required.

For about half of the plotting modules, -R option is not required, but for some non-plotting modules (e.g., grdmask, grdlandmask), -R is required.

I think we can simply define {R} as:

    "R": r"""
        region : str or list
            *xmin/xmax/ymin/ymax*\ [**+r**][**+u**\ *unit*].
            Specify the :doc:`region </tutorials/regions>` of interest.""",

and add some trailing text if -R is required. For example, in pscoast docstring, we can use

{R}
    *Required if this is the first plot command.*

in grdlandmask docstring, we can use:

{R}
    *Required.*

[maxrjones]

I agree with @seisman's suggestion and think we should update the docs for projection similarly. Here's the distribution for modules that are already wrapped and require region and/or projection.

Requires only region

• blockmean, blockmedian, blockmode
• surface
• grdlandmask
• sphdistance
• xyz2grd

Requires only projection

• grdproject
• contour
• grdcontour
• grdimage
• grdview
• velo
• meca
• plot
• plot3d
• wiggle

Requires region and projection
Changed in #1510

• basemap
• coast
• histogram
• rose
• solar
• text

#define THIS_MODULE_NEEDS "jr" (may be required, depending on other arguments)

• colorbar
• image
• legend
• logo

[willschlitzer]

I"ll submit a PR that removes the text for region and projection and changes a few of these modules.

[willschlitzer]

rose uses a different description for region and uses diameter for J. I haven't used rose before; should these docstrings stay or should they use the standard options from COMMON_OPTIONS?

[maxrjones]

rose uses a different description for region and uses diameter for J. I haven't used rose before; should these docstrings stay or should they use the standard options from COMMON_OPTIONS?

The current docstring for rose is fine, since the usage is different from all the other cases.

[seisman]

Actually, I'm a little confused about the THIS_MODULE_NEEDS macro. For psxy, THIS_MODULE_NEEDS is Jd. It means J is required, but R can be automatically determined from the input dataset. However, command gmt plot input.txt -pdf map works without -J and -R options. Is it because the THIS_MODULE_NEEDS is not updated correctly, or am I misunderstanding the macro?

[maxrjones]

Actually, I'm a little confused about the THIS_MODULE_NEEDS macro. For psxy, THIS_MODULE_NEEDS is Jd. It means J is required, but R can be automatically determined from the input dataset. However, command gmt plot input.txt -pdf map works without -J and -R options. Is it because the THIS_MODULE_NEEDS is not updated correctly, or am I misunderstanding the macro?

I just asked Paul about this. THIS_MODULE_NEEDS describes what the GMT module requires to work, but not what the user needs to provide. The machinery around this is in gmt_init_module in gmt_init.c. I am going to work on cleaning up the GMT docs about when -R and -J and required.

For -R, your initial interpretation of THIS_MODULE_NEEDS is correct.

-J is actually currently not needed for any PyGMT functions. If modern mode is used and -J is in THIS_MODULE_NEEDS, GMT will first check the command, then the history, then set to -JQ15c+ if the data are geographic or -JX15c/15c for Cartesian data unless there are panels or time-axes. Interestingly, this is set for both plotting and non-plotting commands. For example, the following code produces a grid with a 15c cylindrical equidistant projection (which probably should be disallowed similar to -R for non-plotting commands).

gmt begin
    gmt grdproject @earth_relief_05m -Gtest.nc
gmt end