Add zoom_adjust parameter to pygmt.datasets.load_tile_map and Figure.tilemap

[weiji14]

Description of proposed changes

The zoom_adjust parameter is used to adjust the automatic zoom level by integer increments.

Preview at https://pygmt-dev--2934.org.readthedocs.build/en/2934/api/generated/pygmt.datasets.load_tile_map.html

Note: This requires contextily>=1.5.0, see geopandas/contextily#228.

Example usage:

import contextily
import pygmt

region = [-157.84, -157.8, 21.255, 21.285]  # West, East, South, North
fig = pygmt.Figure()
with fig.subplot(ncols=2, figsize=("15c", "6c"), sharey=True):
    # Regular zoom level
    fig.tilemap(
        zoom="auto",
        region=region,
        source=contextily.providers.CartoDB.Positron,
        panel=0,
        frame="+tAuto Zoom",
    )
    # Zoom level -1 (more zoomed out)
    fig.tilemap(
        zoom="auto",
        region=region,
        source=contextily.providers.CartoDB.Positron,
        zoom_adjust=-1,
        panel=1,
        frame="+tAuto Zoom -1",
    )
fig.savefig("zoom_adjust.png")
fig.show(width=1000)

produces

Fixes #

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.
• Use underscores (not hyphens) in names of Python files and directories.

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]

Might need to make this backwards compatible with contextily<1.5.0.

[seisman]

Yes, need to check the contextily version and also better to mention that the zoom_adjust parameter requires contextily>=1.5.0.

[weiji14]

Ok, documented at e48c08d, and added another commit at b428d12 to raise an error if zoom_adjust is used but contextily<1.5.0 is installed.

[seisman]

Add type hints to this newly added parameter?

Suggested change

	zoom_adjust=None,
	zoom_adjust: int | None,

[weiji14]

Done at f0c95d8 for just the zoom_adjust parameter. Since all the lines are changing, should I just add type hints for all the other parameters too?

[seisman]

Perfer to focus on the zoom_adjust parameter only in this PR.

[seisman]

Maybe we should not add this until PyGMT reaches v1.0.0?

.. versionadded:: 0.11.0

[weiji14]

Ok, changed to using the note directive instead at 0b01664. I've also used the note and important directive/admonition in other parts of the docstring at 32c04f8:

If it looks a bit messy, I can also revert the changes back to the plain text version.

[seisman]

Do you want to also include zoom, source, ll, wait and max_retries in contextily_kwargs?

[weiji14]

Mm, not really necessary. I only made the contextily_kwargs dict to make things backwards compatible with contextily<1.5.0.

[weiji14]

Gonna leave this open for another day or so in case someone wants to comment on anything.