Figure.colorbar: Add note regarding automatic fontsize scaling

[yvonnefroehlich]

Description of proposed changes

There are several reports and posts on GitHub and the GMT forum regarding the automatic scaling of the fontsize of the colorbar label up on GMT 6.5. Maybe adding a note to the documentation for Figure.colorbar makes this change more visible to users.

GMT docs dev: https://docs.generic-mapping-tools.org/dev/colorbar.html#description

Preview: https://pygmt-dev--4126.org.readthedocs.build/en/4126/api/generated/pygmt.Figure.colorbar.html

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 wrapping a new module, open a 'Wrap new GMT module' issue and submit reasonably-sized PRs.
• 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 command is:

• /format: automatically format and lint the code

Address #3041

[weiji14]

Saw your post at https://forum.generic-mapping-tools.org/t/longitude-axis-starts-at-0-instead-of-my-region-bounds-when-using-mercator-projection-in-pygmt/6214/4, and the link to https://docs.generic-mapping-tools.org/dev/colorbar.html#description which suggests using --FONT_ANNOT_PRIMARY=....

Based on your example at #3041 (comment), is the recommendation to use:

fig.basemap(...)
with pygmt.config(FONT=...):
    fig.colorbar(cmap="...", ...)

Or can we maybe suggest using FONT_ANNOT_PRIMARY? I think the key is to:

1. Only wrap the with pygmt.config(FONT_ANNOT_PRIMARY=...) statement around fig.colorbar, but keep the basemap and other fig.* calls outside.
2. Apply the scaling factor using your scale_cb_font function in Colorbar annotation size does not change #3041 (comment)

[yvonnefroehlich]

Hm. I think it's FONT_LABEL for the x-axis label. because as far as I understood it:

• FONT_ANNOT_PRIMARY: fontsize of the x-axis annotations (numbers)
• FONT_ANNOT_SECONDARY: fontsize of the y-axis label (-> unit)
• FONT_LABEL: fontsize of the x-axis label (-> quantity)
• FONT: fontsize of all

For me, FONT_ANNOT_PRIMARY has no effect on the x-axis label:

import pygmt

size = 5
args_bmap = {"region": [-1, 1, -size, size], "projection": f"X4c/{size}c", "frame": 1}
args_cb = {"cmap": "batlow", "position": "jMC", "frame": ["x+lquantity", "y+lunit"]}

fig = pygmt.Figure()

# -----------------------------------------------------------------------------
fig.basemap(**args_bmap)

fig.colorbar(**args_cb)

# -----------------------------------------------------------------------------
fig.shift_origin(xshift="+w+1c")
fig.basemap(**args_bmap)

with pygmt.config(
    FONT_ANNOT_PRIMARY="10p,blue",  # x-axis annotations (numbers)
    FONT_ANNOT_SECONDARY="20p,darkgreen",  # y-axis label (-> unit)
    FONT_LABEL="20p,orange",  # x-axis label (-> quantity)
):
    fig.colorbar(**args_cb)

# -----------------------------------------------------------------------------
fig.shift_origin(xshift="+w+1c")
fig.basemap(**args_bmap)

with pygmt.config(
    FONT_ANNOT_PRIMARY="25p,blue", 
    FONT_ANNOT_SECONDARY="20p,darkgreen",
    FONT_LABEL="20p,orange",
):
    fig.colorbar(**args_cb)

# -----------------------------------------------------------------------------
fig.shift_origin(xshift="+w+1c")
fig.basemap(**args_bmap)

with pygmt.config(
    FONT_ANNOT_PRIMARY="25p,blue", 
    FONT_ANNOT_SECONDARY="20p,darkgreen",
    # FONT_LABEL="20p,orange",
):
    fig.colorbar(**args_cb)

fig.show()

---

I am fine with including an explicit workaround. Yes, the user has to adjust the desired font size based on the scale factor (previously calculated using the colorbar width) and pass this value to FONT_LABEL (or FONT). The automatic font size scaling reverts this adjustment, and the desired font size is applied. This has to be done locally (with config(...): ) to avoid affecting the font sizes related to the figure frame (basemap) because here no automatic font size scaling is applied.

[weiji14]

From Leo's code at #3041 (comment), it seems like it is not just the colorbar label (set by FONT_LABEL) which is affected by the scaling factor, but also the x- and y- axis annotations (set by FONT_ANNOT_PRIMARY and FONT_ANNOT_SECONDARY respectively). So probably should mention all of these. Could you update the text to reflect that both the label and annotations are affected?