Improvement of two gallery examples regarding categorical colormaps (#1934)

Clarify that by default the labels for the colorbar must be given in alphabetical order.

* add remark regarding categorical number code
* use flexible arguments in makecpt
* shorten and replace remark regarding categorical number code
* fix typos and shorten text based on review

Author: yvonnefroehlich

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