Add a gallery example of inset map showing a rectangle region

[core-man]

Description of proposed changes

Plot an inset map with a rectangle to show the area of the main figure referring to https://docs.gmt-china.org/latest/tutorial/inset/.

• Tokyo is the study area in the primary figure
• Japan mainland is plotted in the inset, along with Tokyo area indicated by a rectangle

Fixes #1018

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.

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

[core-man]

One question: it seems that we don't need to set projection for the coast (see https://www.pygmt.org/latest/api/generated/pygmt.Figure.inset.html#pygmt.Figure.inset and https://www.pygmt.org/latest/gallery/plot/inset.html). I guess GMT will set a default projection.

fig = pygmt.Figure()
fig.coast(region="MG+r2", water="lightblue", shorelines="thin")
fig.show()

[seisman]

One question: it seems that we don't need to set projection for the coast (see pygmt.org/latest/api/generated/pygmt.Figure.inset.html#pygmt.Figure.inset and pygmt.org/latest/gallery/plot/inset.html). I guess GMT will set a default projection.

fig = pygmt.Figure()
fig.coast(region="MG+r2", water="lightblue", shorelines="thin")
fig.show()

Yes, the default value of projection is -JQ15c+.

[core-man]

One question: it seems that we don't need to set projection for the coast (see pygmt.org/latest/api/generated/pygmt.Figure.inset.html#pygmt.Figure.inset and pygmt.org/latest/gallery/plot/inset.html). I guess GMT will set a default projection.

fig = pygmt.Figure()
fig.coast(region="MG+r2", water="lightblue", shorelines="thin")
fig.show()

Yes, the default value of projection is -JQ15c+.

@seisman @willschlitzer Shall we add a projection for those inset examples? It may not a good habit to ignore the projection parameter.

[seisman]

1. Rename it to "inset_rectangle_region.py"?
2. Move it to the embellishments directory.

[core-man]

1. Rename it to "inset_rectangle_region.py"?
2. Move it to the embellishments directory.

Done in e7aa9da.

[seisman]

Looks good to me.

Ping @GenericMappingTools/python @GenericMappingTools/python-contributors @GenericMappingTools/python-maintainers for comments and approvals.

[weiji14]

If it's not too much work, would it be possible to change to a different projection system besides Mercator? E.g. Universal Transverse Mercator (U)? I worry about all the people who are going to use Mercator for their publications because it was a default copied from some gallery example!

[core-man]

If it's not too much work, would it be possible to change to a different projection system besides Mercator? E.g. Universal Transverse Mercator (U)? I worry about all the people who are going to use Mercator for their publications because it was a default copied from some gallery example!

I think it's really a good suggestion. Maybe we should add a tutorial to discuss how to choose projection. But I am not very familiar with the difference between different projections.

I test U, the figure looks a little oblique. Ping @GenericMappingTools/python @GenericMappingTools/python-contributors for any suggestion?

fig.basemap(region=region, projection="U54S/12c", frame=["WSne", "af"])
...
# Inset
    fig.coast(
        region=[129, 146, 30, 46],
        projection="U54S/?",
        ...
    )

[core-man]

Now there are six additional examples with different map projections:

• Political Boundaries: I
• Color land and water: W
• Shorelines: W
• Sampling along tracks: Cyl_stere
• Focal mechanisms: M
• Inset: Q15c+ (GMT default projection)

[weiji14]

I think it's really a good suggestion. Maybe we should add a tutorial to discuss how to choose projection. But I am not very familiar with the difference between different projections.

I test U, the figure looks a little oblique. Ping @GenericMappingTools/python @GenericMappingTools/python-contributors for any suggestion?

Not an expert with GMT projection codes either, but I think it's ok to have it a little oblique. Maybe take a look at https://docs.generic-mapping-tools.org/6.1/gallery/ex28.html which managed a square-ish output somehow.

P.S. Please try to keep pinging of teams to a minimal (e.g. just one team if possible instead of 2 or 3). Not everyone checks their notification area all the time, and it's best not to spam people's notification area with dozens of mentions if they decide to go away for the weekend.

[core-man]

P.S. Please try to keep pinging of teams to a minimal (e.g. just one team if possible instead of 2 or 3). Not everyone checks their notification area all the time, and it's best not to spam people's notification area with dozens of mentions if they decide to go away for the weekend.

Okay~ Thanks for the suggestion. Actually, I don't know which is the best one for help. I guess usually I can use python-contributors?

[weiji14]

Personally I would 1) just try and solve it myself first, 2) ask a question without pinging anyone (it's ok to leave a PR like that for a few days, those who are interested will usually answer) and then 3) ping someone from the team if you get no reply. I realize it's getting close to the release date and we all want our PRs to be merged ASAP, but please try and be considerate of people's inboxes too!

That said, I think the slightly oblique Japan map on a UTM projection is fine, it actually looks a bit cool to be honest! After trying for a bit, I think (though not 100%) that the only way to get a rectangular/non-oblique map is to plot a grid first in linear projection system (e.g. -Jx1:250000) which would require knowing the region bounds in UTM unit metres rather than lon/lat. This will be a bit too complicated for a gallery example, so let's just keep it easy and use U54S/12c.

[core-man]

Personally I would 1) just try and solve it myself first, 2) ask a question without pinging anyone (it's ok to leave a PR like that for a few days, those who are interested will usually answer) and then 3) ping someone from the team if you get no reply. I realize it's getting close to the release date and we all want our PRs to be merged ASAP, but please try and be considerate of people's inboxes too!

Great~

That said, I think the slightly oblique Japan map on a UTM projection is fine, it actually looks a bit cool to be honest! After trying for a bit, I think (though not 100%) that the only way to get a rectangular/non-oblique map is to plot a grid first in linear projection system (e.g. -Jx1:250000) which would require knowing the region bounds in UTM unit metres rather than lon/lat. This will be a bit too complicated for a gallery example, so let's just keep it easy and use U54S/12c.

I would like to keep M for the following reasons: 1) If we assume that PyGMT users will copy the code to use for their own figures, I think they usually will plot symbols/data/lines/... in the figure, too. If we use U instead of M, they will also have to face the issue of how to plot those things in a UTM map. 2) We may have a tutorial about how to use projection in the future and GMT users should know how to choose a better projection themselves.

[weiji14]

I would like to keep M for the following reasons: 1) If we assume that PyGMT users will copy the code to use for their own figures, I think they usually will plot symbols/data/lines/... in the figure, too. If we use U instead of M, they will also have to face the issue of how to plot those things in a UTM map.

I'm pretty sure users can plot symbols/data/lines on a UTM map just as usual compared to a Mercator map right? I.e. use the same georeferenced data in longitude/latitude. The projection only distorts the shape of the Earth, not the data points or how they can be plotted.

2. We may have a tutorial about how to use projection in the future and GMT users should know how to choose a better projection themselves.

Yes I agree that a tutorial for projections is good (though this is a big geography lesson in itself).

[core-man]

I would like to keep M for the following reasons: 1) If we assume that PyGMT users will copy the code to use for their own figures, I think they usually will plot symbols/data/lines/... in the figure, too. If we use U instead of M, they will also have to face the issue of how to plot those things in a UTM map.

I'm pretty sure users can plot symbols/data/lines on a UTM map just as usual compared to a Mercator map right? I.e. use the same georeferenced data in longitude/latitude. The projection only distorts the shape of the Earth, not the data points or how they can be plotted.

Good to know. It seems that my understanding is a little wrong. Done in 0ea30e2.

[weiji14]

Thanks @core-man, sorry if some of my review points came across as a bit harsh, please don't take it personally. I actually appreciate having this example a lot, you will not believe how many hours I've wasted searching for and writing up the code to plot a rectangular box like this before PyGMT v0.3.0! I'm sure this will be an example used by many people so thanks again 😄

[core-man]

Thanks @core-man, sorry if some of my review points came across as a bit harsh, please don't take it personally. I actually appreciate having this example a lot, you will not believe how many hours I've wasted searching for and writing up the code to plot a rectangular box like this before PyGMT v0.3.0! I'm sure this will be an example used by many people so thanks again

@weiji14 I think your review is very good and helpful 👍, and it not harsh from my point of view. Actually, I am very open to any comment/review no matter if it will be accepted or rejected, because a reviewer really spends a lot of their time helping the author to polish the code or documentation. I can learn a lot of things I don't know from the review process.

This is the first GitHub open project that I join with the number of members more than 2 😁. I am really grateful for your comments on this PR and other PRs/issues to help me better work with other members. I enjoy helping and learning from PyGMTers.