Figure.subplot: Add parameters tag/tag_box/tag_position/tag_orientation/tag_number_style/tag_font for controlling subplot tagging

[seisman]

This PR provides a more Pythonic implementation for the -A option of subplot by splitting it into multiple parameters.

The full syntax is:

-A[autotag][+cdx[/dy]][+gfill][+j|Jrefpoint][+odx[/dy]][+ppen][+r|R][+s[[dx/dy][/shade]]][+v]

In PyGMT, the Pythonic parameters are:

• autotag: autotag [Previously it's called autolabel, but I feel it should be called autotag or tag]
• [+cdx[/dy]][+gfill][+ppen][+s[[dx/dy][/shade]]]: tag_box. Controls the box outline. It's a subset of the existing Box class, so we can directly pass a Box object!
• [+j|Jrefpoint][+odx[/dy]]: tag_position, use the Position class
• +r|R: tag_number_style
• +v: tag_orientation
• FONT_TAG: tag_font

It's a POC PR, and is not complete or final yet. Here is an example usage:

import pygmt
from pygmt.params import Box

fig = pygmt.Figure()
with fig.subplot(
    nrows=2, ncols=2, subsize=(5, 5), 
    autotag="(1)", 
    tag_box=Box(pen="1p,red", fill="lightblue"), 
    tag_position="TL", 
    tag_orientation="vertical",
    tag_number_style="roman",
    tag_font="12p,blue"
):
    for i in range(4):
        fig.basemap(region=[0, 10, 0, 10], projection="X?", panel=True)
fig.show()

Preview: https://pygmt-dev--4313.org.readthedocs.build/en/4313/api/generated/pygmt.Figure.subplot.html#pygmt.Figure.subplot

[seisman]

@GenericMappingTools/pygmt-maintainers I think this PR is ready for final reviews. Please read the top post for the implementation details.

I'm still debating about the parameter name autotag. Previously, the -A option was aliased to autolabel. This PR splits it into multiple parameters autotag/tag_box/tag_position/tag_number_style/tag_orientation/tag_font. Following our naming conventions, autotag should be auto_tag, but I'm debating if we should just call it tag, and also rename Figure.set_panel's fixedlabel parameter to tag, too. I feel tag makes the parameters more consistent:

The new syntax would be like:

with fig.subplot(nrows=2, ncols=2, tag="(a)"):
    with fig.set_panel(tag="AnyTag"):
        ...

So, tag="(a)" in Figure.subplot sets the tag for the first subplot, and other subplots are automatically tagged, while tag="AnyTag" sets the tag for a specified panel.

[github-actions]

Summary of changed images

This is an auto-generated report of images that have changed on the DVC remote

Status	Path
renamed	pygmt/tests/baseline/test_subplot_autolabel_margins_title.png -> pygmt/tests/baseline/test_subplot_autotag_margins_title.png

Image diff(s)

Details

Added images

Modified images

Path	Old	New

Report last updated at commit 0c7de28

[github-actions]

Summary of changed images

This is an auto-generated report of images that have changed on the DVC remote

Status	Path
renamed	pygmt/tests/baseline/test_subplot_autolabel_margins_title.png -> pygmt/tests/baseline/test_subplot_tag_margins_title.png

Image diff(s)

Details

Added images

Modified images

Path	Old	New

Report last updated at commit 0c85280

[yvonnefroehlich]

I'm still debating about the parameter name autotag. Previously, the -A option was aliased to autolabel. This PR splits it into multiple parameters autotag/tag_box/tag_position/tag_number_style/tag_orientation/tag_font. Following our naming conventions, autotag should be auto_tag, but I'm debating if we should just call it tag, and also rename Figure.set_panel's fixedlabel parameter to tag, too. I feel tag makes the parameters more consistent:

The new syntax would be like:

with fig.subplot(nrows=2, ncols=2, tag="(a)"):
    with fig.set_panel(tag="AnyTag"):
        ...

So, tag="(a)" in Figure.subplot sets the tag for the first subplot, and other subplots are automatically tagged, while tag="AnyTag" sets the tag for a specified panel.

I like the consistency, and tag is shorter compared to the current names.

[seisman]

I'm still debating about the parameter name autotag. Previously, the -A option was aliased to autolabel. This PR splits it into multiple parameters autotag/tag_box/tag_position/tag_number_style/tag_orientation/tag_font. Following our naming conventions, autotag should be auto_tag, but I'm debating if we should just call it tag, and also rename Figure.set_panel's fixedlabel parameter to tag, too. I feel tag makes the parameters more consistent:
The new syntax would be like:

with fig.subplot(nrows=2, ncols=2, tag="(a)"):
    with fig.set_panel(tag="AnyTag"):
        ...

So, tag="(a)" in Figure.subplot sets the tag for the first subplot, and other subplots are automatically tagged, while tag="AnyTag" sets the tag for a specified panel.

I like the consistency, and tag is shorter compared to the current names.

I've renamed autotag to tag, and will rename fixedlabel to tag in a separate PR (so that we can have an entry in the changelog.