Wrap subplot

[weiji14]

Description of proposed changes

Wrapping the subplot function! Preview the tutorial at https://pygmt-git-subplot.gmt.now.sh/tutorials/subplots.html, translated and adapted from https://docs.gmt-china.org/latest/tutorial/subplot/ (in Chinese).

Original GMT subplot function can be found at https://docs.generic-mapping-tools.org/latest/subplot.html. Current implementation has a 'directive' statement to tell subplot whether to 'begin', 'set' or 'end' a subplot, and the position/number of row(s) and column(s) can be set too.

Example code:

import pygmt

fig = pygmt.Figure()
fig.subplot(directive="begin", row=1, col=2, dimensions="f6c/3c")
fig.subplot(directive="set", row=0, col=0)
fig.basemap(region=[0, 3, 0, 3], frame=True)
fig.subplot(directive="set", row=0, col=1)
fig.basemap(region=[0, 3, 0, 3], frame=True)
fig.subplot(directive="end")
fig.show()

Produces:

Also cross-referencing Julia wrapper/implementation at https://www.generic-mapping-tools.org/GMT.jl/latest/#GMT.subplot.

Parameters/Aliases to wrap:

• F = dims/dimensions/size/sizes
• A = autolabel/fixedlabel
• B = frame
• C = clearance
• J = projection
• M = margins
• R = region
• SC/SR = row_axes | col_axes
• T= title

Note: this initial implementation is based on a thin wrapper I've been using for a while now (see here), but I think it's time to get it properly into PyGMT! Happy to consider other suggestions though, e.g. Would it be better to create it using a with subplot(...): style functionality?

Fixes #20

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 adding new functionality, add an example to docstrings or tutorials.

[seisman]

import pygmt

fig = pygmt.Figure()
fig.subplot(directive="begin", row=1, col=2, dimensions="f6c/3c")
fig.subplot(directive="set", row=0, col=0)
fig.basemap(region=[0, 3, 0, 3], frame=True)
fig.subplot(directive="set", row=0, col=1)
fig.basemap(region=[0, 3, 0, 3], frame=True)
fig.subplot(directive="end")
fig.show()

@weiji14 I'm not sure if this is a good implementation for subplot. The directive argument looks a little weird for matplotlib users. Your implementation may become difficult to read for nested subplots (currently GMT doesn't support nested subplot, but I think it will, see GenericMappingTools/gmt#1280). My first thought is using context manager, but maybe it's more complicated.

[weiji14]

The directive argument looks a little weird for matplotlib users.

Yeah I totally agree with you. I was trying to come up with a way to have a syntax like fig.subplot.begin, fig.subplot.set and fig.subplot.end, but it's tricky implementing it directly in the BasePlotting class. Also looked at matplotlib.subplot, but their codebase is huge...

Your implementation may become difficult to read for nested subplots (currently GMT doesn't support nested subplot, but I think it will, see GenericMappingTools/gmt#1280). My first thought is using context manager, but maybe it's more complicated.

I did think of going the context manager route, similar to what you did in #293. Will need to experiment a bit. Open to any suggestions.