Figures to include in examples section

[willschlitzer]

List of potential figures/modules to include examples for:

Maps

• coast Create a map using coast module #1
• grdimage
• grdcontour
• grdview
• solar
• inset

Data Plots

• histogram
• meca
• plot3d
• ternary
• velo

Datasets

• list/load_sample_data
• load_earth_age
• load_earth_relief
• load_earth_geoid

Data operations

• binstats
• blockmean/median/mode
• nearneighbor
• sph2grd
• sphdistance
• xyz2grd
• grd2xyz
• grdfilter
• grdgradient
• grdcut
• grdcut

[willschlitzer]

@GenericMappingTools/pygmt-maintainers The above list of examples is just my opinion of what modules best demonstrate the types of figures and operations that PyGMT can handle, as well as how it may integrate with the PyData ecosystem. My guess is that this is way too many examples for a paper, and the list should be shortened.

Couple of questions to nail down:
1). Roughly how many figures should the example section include?
2). What modules should we have examples for from the ones listed in the top post? Are there any that should be included that I didn't include in the list?
3). How should an example section handle the outputs of the data processing modules?

[seisman]

1). Roughly how many figures should the example section include?

See https://www.agu.org/Publish-with-AGU/Publish/Author-Resources/New-Manuscript-Checklist. The paper usually should be less than 25 publication units. One publication unit is 500 words or a figure/table. So I guess we should have no more than 10 figures. As a reference, the GMT6 paper has 6 figures and the GMT/Matlab paper has 5 figures.

[willschlitzer]

1). Roughly how many figures should the example section include?

See https://www.agu.org/Publish-with-AGU/Publish/Author-Resources/New-Manuscript-Checklist. The paper usually should be less than 25 publication units. One publication unit is 500 words or a figure/table. So I guess we should have no more than 10 figures. As a reference, the GMT6 paper has 6 figures and the GMT/Matlab paper has 5 figures.

Seems to me like we should just submit 20-25 figures and then save ourselves the trouble of having to write anything! 😜

5-6 seems like a good number of figures; I'm guessing we should prioritize examples that can include numpy, pandas, and datetime integration to demonstrate Python/PyGMT advantages?

[yvonnefroehlich]

2). What modules should we have examples for from the ones listed in the top post? Are there any that should be included that I didn't include in the list?

3). How should an example section handle the outputs of the data processing modules?

In my opinion, we should focus on the more "general" plotting methods. Figure.solar, Figure.tenary, Figure.velo, and Figure.meca are a bit more specific. (However, maybe Figure.meca can be useful to show the usage of a dictionary as input?)

Beside Figure.inset, Figure.subplot is a useful plotting methods.

Beside the available global datasets (e.g. datasets.load_earth_relief), Figure.tilemap is important, especially in comparison with "normal" GMT. Maybe we can plot some geospatial data (data points as numpy.array or a geometry via a geopandas.DataFrame) on top of such a background map?

From the data processing part, I feel pygmt.xyz2grd and pygmt.grdcut are relevant. Maybe we can demonstrate them together with Figure.grdimage and/or Figure.grdcontour to plot the outputs?

To not only have maps 😆, considering a histogram (cartesian via Figure.histogram or polar via Figure.polar) and/or a date time chart seems to be fair. For the histogram we could use a pandas.DataFrame and for the time chart a datetime or a xarray.DataArray as input.

Edit: While looking at this EGU 2022 Short Course example I am wondering, whether a Choropleth map could also be an option.

[yvonnefroehlich]

Dear all, I am a bit unsure how to continue here.

I have started collecting some of my own thoughts and ideas via working on a feature branch of my own fork. Currently, this is all at a very early stage, and there is only one Jupyter notebook containing all the examples. After some polishing and structuring, I will post some ideas in this issue, as this facilitate discussion. For submitting separate PRs to this repository, the examples have to be (simplified,) documented and split into single JNs. I still have to check and make sure that the manuscript text and the examples fit together. This will lead to changes on both.
However, before I put more / too much effort into this, it would be good to know, what has been done by others so far locally but not submitted as PR? I want to avoid double work, and I feel it would be fair that everybody who likes to contribute a figure can do so 🙂.

[seisman]

I have no progresses yet.

[seisman]

@yvonnefroehlich If you still have these example, I feel it would be better if you can submit them as PRs. Don't spend too much time on polishing or improving them, since we may need to discuss first which examples should be included.

[yvonnefroehlich]

@yvonnefroehlich If you still have these example, I feel it would be better if you can submit them as PRs. Don't spend too much time on polishing or improving them, since we may need to discuss first which examples should be included.

I submitted five PRs with drafts for different aspects.
There are obviously some similarities to the EGU2022 and AGU2024 workshops and the AGU talk. I used the EGU2022 workshop as orientation for Xarray and some of my ideas for the paper images for the AGU2024 workshop and talk.
So far there is no explicit example for NumPy and datetime formats. Edit 2025/01/04: Added the PyGMT talk NumPy-datetime example as separate PR.