Tutorial 1 - Add JN for tutorial on first figure/subplot

[jhtong33]

This PR adds the Jupyter notebook tutorial for creating the first figure and subplots.
The purpose of this tutorial is to guide users through the basic plotting functionalities of PyGMT, with a focus on creating and configuring subplots.

The tutorial covers:

• creating new figure
• figure.coast
• pygmt.dataset
• figure.grdimage
• pygmt.makecpt
• figure.colorbar
• figure.subplot and figure.set_panel

Preview:

• https://github.com/GenericMappingTools/agu24workshop/blob/add-jn-first-figure/book/tut01_firstfigure.ipynb
• https://gitnotebooks.com/GenericMappingTools/agu24workshop/pull/10

[Esteban82]

It looks well. Is it ready to merge? Or WIP?

[yvonnefroehlich]

It looks well. Is it ready to merge? Or WIP?

Hm. I think the plan is to have a good draft until 20 November and then review the JNs or scripts of the others (#1 (comment)). With these suggestions and ideas, people should update and finalize their tutorial(s) until the final deadline of 30 November 2024 when the tutorial content should be up on the website. So, I would leave this PR unmerged for now.

I just created a new label "needs review", which can be added to a PR to indicate review is (now) welcome.

[jhtong33]

It looks well. Is it ready to merge? Or WIP?

The tutorial is ready. Any suggestion is welcome.

[Esteban82]

My only suggestion is to add a note saying something like:
"If you use -JM4i, then the width of your map will be 4 inches. The real width of the figure could be bigger if you add elements (like a frame, colorbar, etc.) outside the map."

[weiji14]

Thanks @jhtong33! Looks pretty good! Just a couple of suggestions for now (see below)

It looks well. Is it ready to merge? Or WIP?

Hm. I think the plan is to have a good draft until 20 November and then review the JNs or scripts of the others (#1 (comment)). With these suggestions and ideas, people should update and finalize their tutorial(s) until the final deadline of 30 November 2024 when the tutorial content should be up on the website. So, I would leave this PR unmerged for now.

@yvonnefroehlich, the 20 and 30 Nov are more like hard deadlines for the draft and final final tutorial respectively. We can merge the PR if there is 2 or more approvals, and after merging, it is still possible to edit changes (e.g. if there is a typo).

[weiji14]

My only suggestion is to add a note saying something like: "If you use -JM4i, then the width of your map will be 4 inches. The real width of the figure could be bigger if you add elements (like a frame, colorbar, etc.) outside the map."

If I may add to @Esteban82's comment, it would be good to use SI units (centimeters) by default (PyGMT has this convention since GenericMappingTools/pygmt#795). Still ok to mention inches, and point, but the -J flag should use something like -JM2c.

[jhtong33]

Since I also receive these mails, I'll give my opinion on this topic. You should not give examples in inches. SI (though cm is exactly SI) should be used. We had (and it's not complete) a lot of work in replacing i by c in the manuals examples. Don't keep spreading the use of inches.

OK! Understanding this issue. I replace i to c and only mention c

[jhtong33]

updated review

[joa-quim]

Since I also receive these mails, I'll give my opinion on this topic. You should not give examples in inches. SI (though cm is exactly SI) should be used. We had (and it's not complete) a lot of work in replacing i by c in the manuals examples. Don't keep spreading the use of inches.

[joa-quim]

:) I don't think that literally replacing i by c is a good idea in a real example. 4c is small and since the annotation fonts get scaled with image size, for small images the annotations are often a bit disproportional large (something that should be improved in GMT).

[jhtong33]

:) I don't think that literally replacing i by c is a good idea in a real example. 4c is small and since the annotation fonts get scaled with image size, for small images the annotations are often a bit disproportional large (something that should be improved in GMT).

Thanks @joa-quim's reminder. I made a note of this to help others avoid encountering the same situation.

[yvonnefroehlich]

It looks well. Is it ready to merge? Or WIP?

Hm. I think the plan is to have a good draft until 20 November and then review the JNs or scripts of the others (#1 (comment)). With these suggestions and ideas, people should update and finalize their tutorial(s) until the final deadline of 30 November 2024 when the tutorial content should be up on the website. So, I would leave this PR unmerged for now.

@yvonnefroehlich, the 20 and 30 Nov are more like hard deadlines for the draft and final final tutorial respectively. We can merge the PR if there is 2 or more approvals, and after merging, it is still possible to edit changes (e.g. if there is a typo).

Yes, of course, if people are finished before the deadline 😅, the other can directly start with reviewing 🙂. Sure, I feel the easiest way is to have a finale PR for minor things like fixing typos, correcting links, and make things consistent.

[yvonnefroehlich]

So far, I did not figure out how to make a useful code suggestion in case an image is included in this cell of the Jupyter notebook. Thus I just list these two aspects:

(1) Please fix the typo "canva" to "canvas" and change "latest" to "v0.13.0" in

Creating multi-panel figures in a canva -- figure.subplot(https://www.pygmt.org/latest/api/generated/pygmt.Figure.subplot.html#pygmt.Figure.subplot) and figure.set_panel(https://www.pygmt.org/latest/api/generated/pygmt.Figure.set_panel.html#pygmt.Figure.set_panel)

(2) Please fix the typo "figre" to "figure" and change "colorbar" to "colormap" in

Now, re-plot the figre with new colorbar and ...

[jhtong33]

So far, I did not figure out how to make a useful code suggestion in case an image is included in this cell of the Jupyter notebook.

The better way is to use HTML such as <img src="images/image.png" alt="image.png" width="500" align="right" /> This way also can control figure size and position. However, when I push to github, the images do not show on notebook. I'm not certain if this is feasible for our.

[Esteban82]

For me it is ready to be merged. I just added the CPT acronym in the text.

[weiji14]

@jhtong33, just one comment on the CPT below to fix, and I'd be keen to merge if you're ok with that. There's still some formatting/stylistic things we could tidy up on, but that can be done in a follow-up pull request.

[weiji14]

The EarthByte Earth Seafloor Crustal Age (earth_age) grid has a dedicated @earth_age.cpt colormap. We can use that instead of 'jet' 🙂

Also, pygmt.makecpt won't output anything, so nothing will be stored in the cpt variable. You could do something like this:

pygmt.makecpt(cmap="@earth_age.cpt", series=[0, 160, 10], reverse=True)

fig.grdimage(grid=grid_crust_age,
                     ...
                     cmap=True) 

[jhtong33]

Thanks for your remind. I change the cmap.

[weiji14]

Sorry, I forgot to remove reverse=True in the suggestion 😅 Could you remove that, and then I'll merge this in later today.

[jhtong33]

@weiji14 I also remove the inc because @earth_age.cpt is discrete colormap.

[weiji14]

Awesome, thanks again @jhtong33! Your tutorial is now up at https://www.generic-mapping-tools.org/agu24workshop/tut01_firstfigure.html 🎉 If you'd like to make any edits, feel free to do so anytime before the workshop.