Add an introductory PyGMT tutorial

[willschlitzer]

I think there should be a PyGMT tutorial, much like the GMT tutorial. I don't think it requires as much explanation as what's happening under the hood, but would ideally recreate the Laboratory Exercises. The PyGMT User Guides cover a variety of topics, but I think following the GMT tutorial gives us a good roadmap on what features to explain for someone trying to learn.

Proposed structure:

• Tutorial introduction (Update the starter tutorial introduction #1607)
• Create a basic map figure using coast (Update the starter tutorial introduction #1607)
• Plot data on a map (Add intro tutorial section for creating contour map #2126)
• Create a contour map (Add intro tutorial section for creating contour map #2126)
• Add a color pallet to a map (Add intro tutorial section for creating contour map #2126)
• Create a 3D map

[weiji14]

This reminds me of the FOSS4GOceania 2019 workshop material I made at #317, and the ROSES 2020 stuff which @liamtoney made at #613. As a start, we could probably expose those to be more visible somewhere (and update the content since the API has changed).

If you're thinking about a full comprehensive GMT tutorial like the one linked, I'd suggest doing it session by session (and good luck with that)! On a side note, there might still be time (?) to put in an abstract for vEGU21 to gain more exposure via an online workshop. All depends on what we want to focus on ;)

[willschlitzer]

I was planning on recreating exercises in the tutorial. I'm not sure how to split them up regarding sessions/pages, but I figure the hard part would be putting together the content, which can be done one exercise at a time.

Regarding the vEGU21 abstract, I was unaware that was something we were hoping to do. According to the website, there are still 16 days for abstract submission. I'm happy to help out on this, but my last conference abstract was for AGU Fall 2011, so I'm not too familiar with whats involved in this process.

[liamtoney]

I will likely be providing a PyGMT lesson again for ROSES 2021.

[willschlitzer]

@liamtoney Awesome! Your tutorial video was what brought me to PyGMT.

[seisman]

Sorry, it's still unclear to me what's the difference between the proposed "PyGMT Tutorial" and the existing "PyGMT User Guides". I thought they're the same.

[willschlitzer]

@seisman I'm thinking something more structured like the laboratory exercises that are in the GMT docs, instead of stand-alone user guides. I'm not saying the PyGMT User Guides should be eliminated, but I think having a series of exercises covering different PyGMT functions would be good for someone trying to familiarize themself with the package.

[seisman]

Sounds good to me.

[weiji14]

Another thing we could do is to take the existing user guide and divide it into sections, going from the basics to intermediate stuff. For advanced stuff, I was thinking of adding a page of 'Community contributed' examples (with code) that are just pretty (and good for inspiration).

Regarding the vEGU21 abstract, I was unaware that was something we were hoping to do. According to the website, there are still 16 days for abstract submission. I'm happy to help out on this, but my last conference abstract was for AGU Fall 2011, so I'm not too familiar with whats involved in this process.

If you (or anyone) are interested in vEGU21, open up an issue and we can discuss 😉 There should be funding for covering any registration costs and we've got plenty of old abstracts and material you can adapt for a presentation/short-course.

[willschlitzer]

I like that idea. We can use the existing guides and augment them with the lab exercises from the GMT docs.

[weiji14]

Just mentioning that we've submitted a tutorial proposal for Scipy 2021 (see https://github.com/GenericMappingTools/scipy2021) 😉

In terms of this issue, how should we proceed and/or what exactly is it that we intend to do for the PyGMT tutorials at https://www.pygmt.org/v0.3.0/tutorials/? Do we want to add more tutorials, reorganize them, or do something else? Just wanted to make this issue less vague and decide what we actually want to do here 🙂

[willschlitzer]

@weiji14 I've thought about this from time to time (mostly whenever I click on my issues and see this is still here and think about how I haven't gotten around to it), and it is one of my priorities for v0.4.0. My vision is something along the lines of the first half of the SciPy tutorial. I think the current issue with our tutorials is that they cover the how-tos for different things someone might want to do, but someone just trying to learn PyGMT wouldn't really know where to start. Most people following along with the tutorial will probably come across exercises that aren't applicable to what they are hoping to do, but they can get to the end (or skip exercises) and feel like they have learned the basics. My quick (pre-coffee) outline, which follows along with the GMT tutorial and @liamtoney's ROSES video, is something like this:

1. Basic map making (plot frame, plot coast elements)
2. Plotting extra things on a map (data points, text)
3. More advanced map making tools (grdimage, grdcontour)

I think these plotting elements would cover the basics and make people feel comfortable with looking at the more advanced tutorials (subplots, insets, 3D images, etc.) and gallery examples. I think we should still leave in the original user guides, even if they cover the same topics as discussed in the tutorial, to make anyone looking for a quick reference not have to search through a long tutorial.

[maxrjones]

I can't remember if this has come up in PyGMT spaces before, but the documentation system by Daniele Procinda has been mentioned during GMT documentation discussions. For the GMT documentation, we proposed to make some revisions according to that structure in the recently submitted NASA proposal. Here are the three objectives that we specifically proposed for the documentation side of GMT:

1. Rewrite the “tutorial” section of the user guide to provide repeatable, concrete learning exercises for beginners
2. Write a set of how-to guides that address common problems related to Earth and planetary science
3. Add reproducible, visual examples to the reference documentation

I think that PyGMT's user guides have some similarities to what the next iteration of the GMT tutorial might look like, especially in that they provide concrete, tangible steps without too much reference information mixed in. So, my two main points here are that the current GMT tutorial will be revised to be more accessible to beginners, so recreating it might not be the best bet (which it seems like isn't the exact plan based on the last couple comments), and that the Divio documentation system offers some nice advice on how to make tutorials successful, regardless of whether the broader documentation structure is tutorials, how-to guides, explanation, and reference (based on Divio) or gallery, user-guide, tutorials (new), and API reference (based on PyGMT).

[maxrjones]

Also, I agree with this will be a helpful addition that will give new users a place to start, especially people who prefer to learn by reading rather than listening/watching (where #613 is helpful).

[liamtoney]

Well said, @meghanrjones — I agree with the thoughts you put forth here.

[whyjz]

Hi folks, Firstly thanks @weiji14 for bringing me to this discussion thread! I have been writing some GMT tutorial posts on my gmt-tutorials.org site, and in February I started to include PyGMT in some posts. This is an example of what I am doing and plan to do: for each map, I provide both a GMT script and a PyGMT script. There is a binder link to let users run PyGMT code snippets, but except for that, the explanation on the page is mostly based on GMT. Another note is that these tutorial posts are originally written in Chinese (Taiwan), and the English translation is always an ongoing process. With that being said, I have set up a weblate page to hopefully initiate translation contributions from the community.

As an external effort to make PyGMT more accessible to people, I would like to see if there are any ways in your mind that can best improve these onboarding resources. It looks that my tutorial posts can provide additional gallery examples for PyGMT users, but I am not sure if it would be good to add step-by-step PyGMT explanations as I did for GMT in each post.

Also, please let me know if I could be of any help in contributing to the official PyGMT user guide/tutorial. Happy to discuss this more at any time.

[weiji14]

Welcome @whyjz! Thanks for providing the links, I think that your website is really well thought out, and it fills in an important gap we have on the 'understanding-orientated' side of PyGMT's documentation as mentioned by @meghanrjones at #770 (comment). The translation system is a very nice feature too, and I hope that we can get more languages going all over the world. Really excited to see where we can go with this by combining efforts!

To start, how about you take a shot at opening a PR to resolve #1059 which is specifically about adding a page on the PyGMT sidebar linking to community contributions like yours. I think you should be familiar enough with the sphinx website theme to figure it out, but let us know if you need help (we can talk more in that #1059 thread).