Merge branch 'main' into refactor-meca

Author: seisman

.github/workflows/ci_docs.yml

@@ -80,7 +80,7 @@ jobs:
 
       # Download cached remote files (artifacts) from GitHub
       - name: Download remote data from GitHub
-        uses: dawidd6/action-download-artifact@v2.20.0
+        uses: dawidd6/action-download-artifact@v2.21.0
         with:
           workflow: cache_data.yaml
           workflow_conclusion: success

.github/workflows/ci_tests.yaml

@@ -105,7 +105,7 @@ jobs:
 
       # Download cached remote files (artifacts) from GitHub
       - name: Download remote data from GitHub
-        uses: dawidd6/action-download-artifact@v2.20.0
+        uses: dawidd6/action-download-artifact@v2.21.0
         with:
           workflow: cache_data.yaml
           workflow_conclusion: success

.github/workflows/ci_tests_dev.yaml

@@ -137,7 +137,7 @@ jobs:
 
       # Download cached remote files (artifacts) from GitHub
       - name: Download remote data from GitHub
-        uses: dawidd6/action-download-artifact@v2.20.0
+        uses: dawidd6/action-download-artifact@v2.21.0
         with:
           workflow: cache_data.yaml
           workflow_conclusion: success

doc/external_resources.md

@@ -10,14 +10,91 @@ to submit a pull request with your recommended addition to the
 
 ## Tutorials
 
-- [2022 EGU SC5.2: Crafting beautiful maps with PyGMT](https://github.com/GenericMappingTools/egu22pygmt) by Wei Ji Leong, Leonardo Uieda, Max Jones, Andre Belem
-- [2021 PyGMT course at the UAF Geophysical Institute](https://github.com/liamtoney/gi-pygmt-2021) by Liam Toney
-- [2021 Remote Online Sessions for Emerging Seismologists (ROSES): Unit 5 - Mapping](https://www.youtube.com/watch?v=Zvcy7VDuhiw) by Liam Toney
-- [2020 Remote Online Sessions for Emerging Seismologists (ROSES): Unit 8 - PyGMT](https://www.iris.edu/hq/inclass/lesson/728) by Liam Toney
-- [PyGMT Tutorial in 2021](https://github.com/MIGG-NTU/PyGMT2021) by MIGG-NTU
-- [PyGMT Workshop at FOSS4G Oceania 2019](https://github.com/GenericMappingTools/foss4g2019oceania) by Wei Ji Leong
+:::::{grid} 1 2 2 3
+
+::::{grid-item-card} 2022 EGU SC5.2: Crafting beautiful maps with PyGMT
+:link: https://www.generic-mapping-tools.org/egu22pygmt/
+:text-align: center
+:margin: 0 3 0 0
+
+![](https://user-images.githubusercontent.com/3974108/171653272-efaceeb1-a253-44a1-bddc-36bc9498c19b.png)
++++
+Wei Ji Leong, Leonardo Uieda, Max Jones, Andre Belem
+::::
+
+::::{grid-item-card} 2021 PyGMT course at the UAF Geophysical Institute
+:link: https://github.com/liamtoney/gi-pygmt-2021
+:text-align: center
+:margin: 0 3 0 0
+
+![](https://user-images.githubusercontent.com/3974108/172042115-3f700c16-0f78-49d3-9e8d-87c77e4c0444.png)
++++
+Liam Toney
+::::
+
+::::{grid-item-card} 2021 Remote Online Sessions for Emerging Seismologists (ROSES): Unit 5 - Mapping
+:link: https://www.youtube.com/watch?v=Zvcy7VDuhiw
+:text-align: center
+:margin: 0 3 0 0
+
+![](https://user-images.githubusercontent.com/3974108/172055872-b81057b6-aef3-473f-8f42-1cc82a68d188.jpg)
++++
+Liam Toney
+::::
+
+::::{grid-item-card} 2020 Remote Online Sessions for Emerging Seismologists (ROSES): Unit 8 - PyGMT
+:link: https://www.iris.edu/hq/inclass/lesson/728
+:text-align: center
+:margin: 0 3 0 0
+
+![](https://user-images.githubusercontent.com/3974108/172055922-8df68c00-4115-42f4-83ae-13a971fef846.png)
++++
+Liam Toney
+::::
+
+::::{grid-item-card} PyGMT Tutorial in 2021
+:link: https://github.com/MIGG-NTU/PyGMT2021
+:text-align: center
+:margin: 0 3 0 0
+
+![](https://user-images.githubusercontent.com/23487320/172058757-9b68f7ae-7a3f-4f48-9df6-9a065d6cd448.png)
++++
+MIGG-NTU
+::::
+
+::::{grid-item-card} PyGMT Workshop at FOSS4G Oceania 2019
+:link: https://github.com/GenericMappingTools/foss4g2019oceania
+:text-align: center
+:margin: 0 3 0 0
+
+![](https://github.com/GenericMappingTools/foss4g2019oceania/releases/download/v1/picton_3d_dsm_view.png)
++++
+Wei Ji Leong
+::::
+:::::
 
 ## Examples from Publications and Posters
 
-- [GMT and PyGMT plotting examples](https://github.com/michaelgrund/GMT-plotting) by Michael Grund
-- [NZ Antarctic Science Conference 2021 poster](https://github.com/weiji14/nzasc2021) by Wei Ji Leong
+:::::{grid} 1 2 2 3
+
+::::{grid-item-card} GMT and PyGMT plotting examples
+:link: https://github.com/michaelgrund/GMT-plotting
+:text-align: center
+:margin: 0 3 0 0
+
+![](https://user-images.githubusercontent.com/3974108/172055991-c0646f6c-d130-474f-b46a-5587483998cb.jpg)
++++
+Michael Grund
+::::
+
+::::{grid-item-card} NZ Antarctic Science Conference 2021 poster
+:link: https://github.com/weiji14/nzasc2021
+:text-align: center
+:margin: 0 3 0 0
+
+![](https://user-images.githubusercontent.com/23487320/107176140-6aa4e580-6a33-11eb-8f30-1a7913788d6c.png)
++++
+Wei Ji Leong
+::::
+
+:::::

doc/install.rst

@@ -137,7 +137,7 @@ This installs the latest stable release from
 Alternatively, you can install the latest development version from
 `TestPyPI <https://test.pypi.org/project/pygmt>`__::
 
-    pip install --pre --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple pygmt
+    pip install --pre --extra-index-url https://test.pypi.org/simple/ pygmt
 
 To upgrade the installed stable release or development version to be the latest
 one, just add ``--upgrade`` to the corresponding command above.

examples/gallery/3d_plots/scatter3d.py

@@ -17,9 +17,20 @@
 import pandas as pd
 import pygmt
 
-# Load sample iris data and convert 'species' column to categorical dtype
+# Load sample iris data
 df = pd.read_csv("https://github.com/mwaskom/seaborn-data/raw/master/iris.csv")
+# Convert 'species' column to categorical dtype
+# By default, pandas sorts the individual categories in an alphabetical order.
+# For a non-alphabetical order, you have to manually adjust the list of
+# categories. For handling and manipulating categorical data in pandas,
+# have a look at:
+# https://pandas.pydata.org/docs/user_guide/categorical.html
 df.species = df.species.astype(dtype="category")
+# Make a list of the individual categories of the 'species' column
+# ['setosa', 'versicolor', 'virginica']
+# They are (corresponding to the categorical number code) by default in
+# alphabetical order and later used for the colorbar labels
+labels = list(df.species.cat.categories)
 
 # Use pygmt.info to get region bounds (xmin, xmax, ymin, ymax, zmin, zmax)
 # The below example will return a numpy array [0.0, 3.0, 4.0, 8.0, 1.0, 7.0]
@@ -35,12 +46,18 @@
 fig = pygmt.Figure()
 
 # Define a colormap to be used for three categories, define the range of the
-# new discrete CPT using series=(lowest_value, highest_value, interval), use
-# color_model="+cSetosa,Versicolor,Virginica" to write the discrete color
+# new discrete CPT using series=(lowest_value, highest_value, interval),
+# use color_model="+csetosa,versicolor,virginica" to write the discrete color
 # palette "cubhelix" in categorical format and add the species names as
 # annotations for the colorbar
 pygmt.makecpt(
-    cmap="cubhelix", color_model="+cSetosa,Versicolor,Virginica", series=(0, 2, 1)
+    cmap="cubhelix",
+    # Use the minimum and maximum of the categorical number code
+    # to set the lowest_value and the highest_value of the CPT
+    series=(df.species.cat.codes.min(), df.species.cat.codes.max(), 1),
+    # convert ['setosa', 'versicolor', 'virginica'] to
+    # 'setosa,versicolor,virginica'
+    color_model="+c" + ",".join(labels),
 )
 
 fig.plot3d(

examples/gallery/symbols/points_categorical.py

@@ -14,9 +14,20 @@
 import pandas as pd
 import pygmt
 
-# Load sample penguins data and convert 'species' column to categorical dtype
+# Load sample penguins data
 df = pd.read_csv("https://github.com/mwaskom/seaborn-data/raw/master/penguins.csv")
+# Convert 'species' column to categorical dtype
+# By default, pandas sorts the individual categories in an alphabetical order.
+# For a non-alphabetical order, you have to manually adjust the list of
+# categories. For handling and manipulating categorical data in pandas,
+# have a look at:
+# https://pandas.pydata.org/docs/user_guide/categorical.html
 df.species = df.species.astype(dtype="category")
+# Make a list of the individual categories of the 'species' column
+# ['Adelie', 'Chinstrap', 'Gentoo']
+# They are (corresponding to the categorical number code) by default in
+# alphabetical order and later used for the colorbar labels
+labels = list(df.species.cat.categories)
 
 # Use pygmt.info to get region bounds (xmin, xmax, ymin, ymax)
 # The below example will return a numpy array like [30.0, 60.0, 12.0, 22.0]
@@ -48,7 +59,14 @@
 # use color_model="+cAdelie,Chinstrap,Gentoo" to write the discrete color
 # palette "inferno" in categorical format and add the species names as
 # annotations for the colorbar
-pygmt.makecpt(cmap="inferno", series=(0, 2, 1), color_model="+cAdelie,Chinstrap,Gentoo")
+pygmt.makecpt(
+    cmap="inferno",
+    # Use the minimum and maximum of the categorical number code
+    # to set the lowest_value and the highest_value of the CPT
+    series=(df.species.cat.codes.min(), df.species.cat.codes.max(), 1),
+    # convert ['Adelie', 'Chinstrap', 'Gentoo'] to 'Adelie,Chinstrap,Gentoo'
+    color_model="+c" + ",".join(labels),
+)
 
 fig.plot(
     # Use bill length and bill depth as x and y data input, respectively

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [tool.setuptools_scm]
 local_scheme = "node-and-date"
-fallback_version = "unknown"
+fallback_version = "999.999.999+unknown"
 
 [tool.coverage.run]
 omit = ["*/tests/*", "*pygmt/__init__.py"]