Merge branch 'master' into wrap-grdclip

examples/gallery/3d_plots/scatter3d.py

@@ -17,7 +17,7 @@
 import pandas as pd
 import pygmt
 
-# Load sample iris data, and convert 'species' column to categorical dtype
+# Load sample iris data and convert 'species' column to categorical dtype
 df = pd.read_csv("https://github.com/mwaskom/seaborn-data/raw/master/iris.csv")
 df.species = df.species.astype(dtype="category")
 
@@ -36,9 +36,12 @@
 
 # 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="+c" to write the discrete color palette "cubhelix" in
-# categorical format
-pygmt.makecpt(cmap="cubhelix", color_model="+c", series=(0, 3, 1))
+# 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)
+)
 
 fig.plot3d(
     # Use petal width, sepal length and petal length as x, y and z data input,
@@ -58,14 +61,18 @@
     region=region,
     # Set frame parameters
     frame=[
-        "WsNeZ3",  # z axis label positioned on 3rd corner
-        'xafg+l"Petal Width"',
-        'yafg+l"Sepal Length"',
-        'zafg+l"Petal Length"',
+        'WsNeZ3+t"Iris flower data set"',  # z axis label positioned on 3rd corner, add title
+        'xafg+l"Petal Width (cm)"',
+        'yafg+l"Sepal Length (cm)"',
+        'zafg+l"Petal Length (cm)"',
     ],
     # Set perspective to azimuth NorthWest (315°), at elevation 25°
     perspective=[315, 25],
     # Vertical exaggeration factor
     zscale=1.5,
 )
+
+# Add colorbar legend
+fig.colorbar(xshift=3.1)
+
 fig.show()

examples/gallery/lines/line_custom_cpt.py

@@ -21,13 +21,16 @@
 fig = pygmt.Figure()
 fig.basemap(frame=["WSne", "af"], region=[20, 30, -10, 10])
 
-# Create a custom CPT with the batlow CPT and 10 discrete z-values (colors)
-pygmt.makecpt(cmap="batlow", series=[0, 10, 1])
+# Create a custom CPT with the batlow CPT and 10 discrete z-values (colors),
+# use color_model="+c0-9" to write the color palette in categorical format and
+# add labels (0) to (9) for the colorbar legend
+pygmt.makecpt(cmap="batlow", series=[0, 9, 1], color_model="+c0-9")
 
 # Plot 10 lines and set a different z-value for each line
 for zvalue in range(0, 10):
     y = zvalue * np.sin(x)
     fig.plot(x=x, y=y, cmap=True, zvalue=zvalue, pen="thick,+z,-")
+
 # Color bar to show the custom CPT and the associated z-values
 fig.colorbar()
 fig.show()

examples/gallery/symbols/points_categorical.py

@@ -44,9 +44,10 @@
 
 # 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="+c" to write the discrete color palette "inferno" in
-# categorical format
-pygmt.makecpt(cmap="inferno", series=(0, 3, 1), color_model="+c")
+# 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")
 
 fig.plot(
     # Use bill length and bill depth as x and y data input, respectively
@@ -66,7 +67,7 @@
     transparency=40,
 )
 
-# A colorbar displaying the different penguin species types will be added
-# once GMT 6.2.0 is released.
+# Add colorbar legend
+fig.colorbar()
 
 fig.show()

pygmt/src/histogram.py

@@ -10,16 +10,29 @@
     A="horizontal",
     B="frame",
     C="cmap",
+    D="annotate",
+    E="barwidth",
+    F="center",
     G="fill",
     J="projection",
+    L="extreme",
+    N="distribution",
+    Q="cumulative",
     R="region",
+    S="stairs",
     T="series",
+    U="timestamp",
+    V="verbose",
     W="pen",
+    X="xshift",
+    Y="yshift",
+    Z="type",
     c="panel",
     l="label",
     p="perspective",
+    t="transparency",
 )
-@kwargs_to_strings(R="sequence", T="sequence")
+@kwargs_to_strings(R="sequence", T="sequence", c="sequence_comma", p="sequence")
 def histogram(self, table, **kwargs):
     r"""
     Plots a histogram, and can read data from a file or
@@ -40,16 +53,75 @@ def histogram(self, table, **kwargs):
     {G}
     {W}
     {c}
-    label : str
-        Add a legend entry for the symbol or line being plotted.
-    {p}
+    annotate : bool or str
+        [**+b**][**+f**\ *font*][**+o**\ *off*][**+r**].
+        Annotate each bar with the count it represents.  Append any of the
+        following modifiers: Use **+b** to place the labels beneath the bars
+        instead of above; use **+f** to change to another font than the default
+        annotation font; use **+o** to change the offset between bar and
+        label [6p]; use **+r** to rotate the labels from horizontal to
+        vertical.
+    barwidth : int or float or str
+        *width*\ [**+o**\ *offset*].
+        Use an alternative histogram bar width than the default set via
+        ``series``, and optionally shift all bars by an *offset*.  Here
+        *width* is either an alternative width in data units, or the user may
+        append a valid plot dimension unit (**c**\|\ **i**\|\ **p**) for a
+        fixed dimension instead. Optionally, all bins may be shifted along the
+        axis by *offset*. As for *width*, it may be given in data units of
+        plot dimension units by appending the relevant unit.
+    center : bool
+        Center bin on each value. [Default is left edge].
+    distribution : bool or int or float or str
+        [*mode*][**+p**\ *pen*].
+        Draw the equivalent normal distribution; append desired
+        *pen* [Default is 0.25p,black].
+        The *mode* selects which central location and scale to use:
+
+        * 0 = mean and standard deviation [Default];
+        * 1 = median and L1 scale (1.4826 \* median absolute deviation; MAD);
+        * 2 = LMS (least median of squares) mode and scale.
+    cumulative : bool or str
+        [**r**].
+        Draw a cumulative histogram by passing ``True``. Use **r** to display
+        a reverse cumulative histogram.
+    extreme : str
+        **l**\|\ **h**\|\ **b**.
+        The modifiers specify the handling of extreme values that fall outside
+        the range set by ``series``.  By default these values are ignored.
+        Append **b** to let these values be included in the first or last
+        bins. To only include extreme values below first bin into the first
+        bin, use **l**, and to only include extreme values above the last bin
+        into that last bin, use **h**.
+    stairs : bool
+        Draws a stairs-step diagram which does not include the internal bars
+        of the default histogram.
     horizontal : bool
         Plot the histogram using horizonal bars instead of the
         default vertical bars.
     series : int or str or list
-        [*min*\ /*max*\ /]\ *inc*\ [**+n**\ ]
+        [*min*\ /*max*\ /]\ *inc*\ [**+n**\ ].
         Set the interval for the width of each bar in the histogram.
+    type : int or str
+        [*type*][**+w**].
+        Choose between 6 types of histograms:
 
+        * 0 = counts [Default]
+        * 1 = frequency_percent
+        * 2 = log (1.0 + count)
+        * 3 = log (1.0 + frequency_percent)
+        * 4 = log10 (1.0 + count)
+        * 5 = log10 (1.0 + frequency_percent).
+
+        To use weights provided as a second data column instead of pure counts,
+        append **+w**.
+    {XY}
+    {U}
+    {V}
+    label : str
+        Add a legend entry for the symbol or line being plotted.
+    {p}
+    {t}
     """
     kwargs = self._preprocess(**kwargs)  # pylint: disable=protected-access
     with Session() as lib: