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).