Better categories for gallery examples

[seisman]

The Gallery is generated from Python scripts in the examples/gallery directory.

Currently, we have 19 gallery examples in 4 directories (categories).

• Lines: 2 examples
• Coastlines and boundaries: 3 examples
• Plotting map items: 12 examples
• Grids: 2 examples

IMHO, the current categories are not good, especially that the "Plotting map items" category is too general.

We need to think about how to categorize these existing and future examples. We can check the matplotlib gallery for some inspirations.

[willschlitzer]

Looking at the gallery, this is my thought:

*Plot maps (coastlines and boundaries section, along with inset)
*Plot numeric data (scatter plots, 3d plots, datetime input, line)
*Plot additional figure elements (symbols, legend, logo, colorbar, set line color)

[seisman]

I'm thinking in a different way:

• Lines and vectors
• Symbols and markers
• Images and contours
• Subplots
• 3D plots
• more?

[seisman]

Here are some new thoughts about categories.

As documented in the contributing guides, a good gallery plot should "highlight a single feature/command". Usually, we only use one or a few plotting commands in one example. So, I think it's easier to decide the categories based on the plotting modules and features that GMT provides.

Please see this page for the full list of all GMT modules, especially the plotting modules.

Here are categories in my mind:

---

1. Lines and vetcors:

• lines plotted using plot (no -S option)
• vectors (plot -Sm, -SM, -Sv, -SV, -S=)
• quoted lines (plot -Sq)
• front lines (plot -Sf)
• decorated lines (plot -S~)

---

2. Symbols and Markers

If I understand it correctly, GMT calls them "symbols" but matplotlib calls them "markers". So we could use "symbols and markers".

• symbols (mostly plot -S except those listed in "Lines and vectors")

---

3. Images, contours and fields

This category mainly focuses on the illustration of matrix data (e.g., images and grids)

• grdimage: plot a grid by color-coded pixels
• grdvector: plot a grid by vectors or fields
• grdcontour: plot a grid by contours
• image: raster image is just a special matrix data
• contour: never used it, but I think it's similar to grdcontour

---

4. Histograms

• histogram: Cartesian histogram
• rose: polar histogram (rose, sector, windrose diagrams)

---

5. 3D plots

Most plotting modules can use the perspective parameter (-p option) for 3D view, but this category focuses on two modules:

• grdview
• plot3d

---

6. Seismology and Geodesy

• meca: beachballs on maps
• coupe: beachballs on cross-sections
• polar: polarity observations on beachballs
• velo: vectors, crosses, and wedges

---

7. Subplots

Similar to the "Subplots, axes and figures" category in matplotlib, I think it's useful to show different subplot layouts (especially for subplots that share X and/or Y axis).

---

8. Maps

Plotting geographic maps is the key feature of GMT and PyGMT. I think we will have more maps in this category. As mentioned below, we can add more examples showing maps with map scale, directional rose, and insets.

---

9. Base maps

I expect to see more examples for different kinds of base maps, for example:

• Different time axes (https://docs.generic-mapping-tools.org/dev/cookbook/options.html#cartesian-time-axes)
• Double Y-axis graph (Add an example for double Y-axis graph #1009)
• Base maps using different MAP_FRAME_TYPE, especially inside and graph

but I'm not sure if we should put them in "projections" or a separated category.

---

10. Text, labels and annotations

Similar to https://matplotlib.org/stable/gallery/index.html#subplots-axes-and-figures.

This category focuses on:

• text
• the frame parameter
• LaTeX expression support?

---

11. Embellishments

The GMT cookbook has a section for plotting different "embellishments" (https://docs.generic-mapping-tools.org/dev/cookbook/features.html#plot-embellishments). The GMT embellishments include:

• map scale, directional map scale, and magnetic map roses
• color scale bars
• legend
• logo
• inset
• vertical scale

Most of these embellishments won't be used alone. For example, map scales are used in maps, it makes sense to put them in the "Maps" category. However, if we want to add examples that highlight the different appearance of map scales or colorbars, we can put them in the "Embellishments" category.

---

There are still some plotting modules that are not covered above:

• clip: not a real plotting module
• mask: again, not a real plotting module
• events: mostly used in animations
• solar: Plot day-light terminators
• ternary: Plot data on ternary diagrams. Perhaps put it in "Base Maps"
• wiggle: Put it in "Lines"?

The above categories mainly focus on plotting modules. Sometimes, we may also want to show usage of non-plotting modules (for examplehttps://www.pygmt.org/dev/gallery/grid/track_sampling.html). I'm not sure where to put these examples.

[maxrjones]

Here are some new thoughts about categories.

As documented in the contributing guides, a good gallery plot should "highlight a single feature/command". Usually, we only use one or a few plotting commands in one example. So, I think it's easier to decide the categories based on the plotting modules and features that GMT provides.

Please see this page for the full list of all GMT modules, especially the plotting modules.

Here are categories in my mind:

1. Lines and vetcors:

* lines plotted using **plot** (no **-S** option)

* vectors (**plot** **-Sm**, **-SM**, **-Sv**, **-SV**, **-S=**)

* quoted lines (**plot -Sq**)

* front lines (**plot -Sf**)

* decorated lines (**plot -S~**)

2. Symbols and Markers

If I understand it correctly, GMT calls them "symbols" but matplotlib calls them "markers". So we could use "symbols and markers".

* symbols (mostly **plot -S** except those listed in "Lines and vectors")

3. Images, contours and fields

This category mainly focuses on the illustration of matrix data (e.g., images and grids)

* `grdimage`: plot a grid by color-coded pixels

* `grdvector`: plot a grid by vectors or fields

* `grdcontour`: plot a grid by contours

* `image`: raster image is just a special matrix data

* `contour`: never used it, but I think it's similar to `grdcontour`

4. Histograms

* `histogram`: Cartesian histogram

* `rose`: polar histogram (rose, sector, windrose diagrams)

5. 3D plots

Most plotting modules can use the perspective parameter (-p option) for 3D view, but this category focuses on two modules:

* `grdview`

* `plot3d`

6. Seismology and Geodesy

* `meca`: beachballs on maps

* `coupe`: beachballs on cross-sections

* `polar`: polarity observations on beachballs

* `velo`: vectors, crosses, and wedges

7. Subplots

Similar to the "Subplots, axes and figures" category in matplotlib, I think it's useful to show different subplot layouts (especially for subplots that share X and/or Y axis).

8. Maps

Plotting geographic maps is the key feature of GMT and PyGMT. I think we will have more maps in this category. As mentioned below, we can add more examples showing maps with map scale, directional rose, and insets.

9. Base maps

I expect to see more examples for different kinds of base maps, for example:

* Different time axes (https://docs.generic-mapping-tools.org/dev/cookbook/options.html#cartesian-time-axes)

* Double Y-axis graph (#1009)

* Base maps using different [`MAP_FRAME_TYPE`](https://docs.generic-mapping-tools.org/dev/gmt.conf.html), especially **inside** and **graph**

but I'm not sure if we should put them in "projections" or a separated category.

10. Text, labels and annotations

Similar to https://matplotlib.org/stable/gallery/index.html#subplots-axes-and-figures.

This category focuses on:

* `text`

* the `frame` parameter

* LaTeX expression support?

11. Embellishments

The GMT cookbook has a section for plotting different "embellishments" (https://docs.generic-mapping-tools.org/dev/cookbook/features.html#plot-embellishments). The GMT embellishments include:

* map scale, directional map scale, and magnetic map roses

* color scale bars

* legend

* logo

* inset

* vertical scale

Most of these embellishments won't be used alone. For example, map scales are used in maps, it makes sense to put them in the "Maps" category. However, if we want to add examples that highlight the different appearance of map scales or colorbars, we can put them in the "Embellishments" category.

There are still some plotting modules that are not covered above:

* `clip`: not a real plotting module

* `mask`: again, not a real plotting module

* `events`: mostly used in animations

* `solar`: Plot day-light terminators

* `ternary`: Plot data on ternary diagrams. Perhaps put it in "Base Maps"

* `wiggle`: Put it in "Lines"?

The above categories mainly focus on plotting modules. Sometimes, we may also want to show usage of non-plotting modules (for examplehttps://www.pygmt.org/dev/gallery/grid/track_sampling.html). I'm not sure where to put these examples.

I like this organization, in particular because the features that are currently in 'maps and map elements' in #995 that are not exclusive to maps will be more aptly categorized as 'embellishments'. It's also nice to have the consistency with GMT terminology.

I think that the grdtrack example would be best placed in a Data processing section (which could also hold several of the other modules that don't fit in the other categories such as clip, mask). I prefer this in order to highlight the focus of the example on grid sampling rather than plotting. The processing modules could also be split into two categories - one for GMT modules that process grids and one for GMT modules that process tables.

solar could be considered an 'embellishment'.

[seisman]

I'll keep the PR open for more discussions.

[seisman]

I'm closing the issue, since most of the categories (except "subplots" and "Text, labels and annotations") mentioned in #876 (comment) have been created.