DOC/advanced Tutorial "Cartesian histograms": General improvements (#3626)

Author: yvonnefroehlich

examples/tutorials/advanced/cartesian_histograms.py

@@ -2,8 +2,8 @@
 Cartesian histograms
 ====================
 
-Cartesian histograms can be generated using the :meth:`pygmt.Figure.histogram`
-method. In this tutorial, different histogram related aspects are addressed:
+Cartesian histograms can be generated using the :meth:`pygmt.Figure.histogram` method.
+In this tutorial, different histogram related aspects are addressed:
 
 - Using vertical and horizontal bars
 - Using stair-steps
@@ -38,39 +38,36 @@
 # Vertical and horizontal bars
 # ----------------------------
 #
-# To define the width of the bins, the ``series`` parameter has to be
-# specified. The bars can be filled via the ``fill`` parameter with either a
-# color or a pattern (see later in this tutorial). Use the ``pen`` parameter
-# to adjust width, color, and style of the outlines. By default, a histogram
-# with vertical bars is created. Horizontal bars can be achieved via
-# ``horizontal=True``.
-
-# Create new figure instance
+# To define the width of the bins, the ``series`` parameter has to be specified. The
+# bars can be filled via the ``fill`` parameter with either a color or a pattern (see
+# later in this tutorial). Use the ``pen`` parameter to adjust width, color, and style
+# of the outlines. By default, a histogram with vertical bars is created. Horizontal
+# bars can be achieved via ``horizontal=True``.
+
 fig = pygmt.Figure()
 
 # Create histogram for data01 with vertical bars
 fig.histogram(
     # Define the plot range as a list of xmin, xmax, ymin, ymax
-    # Let ymin and ymax determined automatically by setting both to the same
-    # value
+    # Let ymin and ymax determined automatically by setting both to the same value
     region=[0, 200, 0, 0],
     projection="X10c",  # Cartesian projection with a width of 10 centimeters
-    # Add frame, annotations (a), ticks (f), and y-axis label (+l) "Counts"
-    # The numbers give the steps of annotations and ticks
+    # Add frame, annotations ("a"), ticks ("f"), and y-axis label ("+l") "Counts"; the
+    # numbers give the steps of annotations and ticks
     frame=["WStr", "xaf10", "ya1f1+lCounts"],
     data=data01,
     # Set the bin width via the "series" parameter
     series=10,
     # Fill the bars with color "red3"
     fill="red3",
-    # Draw a 1-point thick solid outline in "darkgray" around the bars
+    # Draw a 1-point thick, solid outline in "darkgray" around the bars
     pen="1p,darkgray,solid",
     # Choose counts via the "histtype" parameter
     histtype=0,
 )
 
-# Shift plot origin 12 centimeters to the right
-fig.shift_origin(xshift="12c")
+# Shift plot origin by the figure width ("w") plus 2 centimeters to the right
+fig.shift_origin(xshift="w+2c")
 
 # Create histogram for data01 with horizontal bars
 fig.histogram(
@@ -83,8 +80,8 @@
     pen="1p,darkgray,solid",
     histtype=0,
     # Use horizontal bars
-    # Please note the flip of the x and y axes regarding annotations, ticks,
-    # gridlines, and axis labels
+    # Please note the flip of the x and y axes regarding annotations, ticks, gridlines,
+    # and labels
     horizontal=True,
 )
 
@@ -95,10 +92,9 @@
 # Stair-steps
 # -----------
 #
-# A stair-step diagram can be created by setting ``stairs=True``. Then only
-# the outer outlines of the bars are drawn, and no internal bars are visible.
+# A stair-step diagram can be created by setting ``stairs=True``. Then only the
+# outer outlines of the bars are drawn, and no internal bars are visible.
 
-# Create new figure instance
 fig = pygmt.Figure()
 
 # Create histogram for data01
@@ -108,15 +104,14 @@
     frame=["WSne", "xaf10", "ya1f1+lCounts"],
     data=data01,
     series=10,
-    # Draw a 1-point thick dotted outline in "red3"
+    # Draw a 1-point thick, dotted outline in "red3"
     pen="1p,red3,dotted",
     histtype=0,
     # Draw stair-steps in stead of bars
     stairs=True,
 )
 
-# Shift plot origin 12 centimeters to the right
-fig.shift_origin(xshift="12c")
+fig.shift_origin(xshift="w+2c")
 
 # Create histogram for data02
 fig.histogram(
@@ -125,7 +120,7 @@
     frame=["WSne", "xaf10", "ya1f1+lCounts"],
     data=data02,
     series=10,
-    # Draw a 1.5-point thick dashed outline in "orange"
+    # Draw a 1.5-points thick, dashed outline in "orange"
     pen="1.5p,orange,dashed",
     histtype=0,
     stairs=True,
@@ -138,12 +133,10 @@
 # Counts and frequency percent
 # ----------------------------
 #
-# By default, a histogram showing the counts in each bin is created
-# (``histtype=0``). To show the frequency percent set the ``histtpye``
-# parameter to ``1``. For further options please have a look at the
-# documentation of :meth:`pygmt.Figure.histogram`.
+# By default, a histogram showing the counts in each bin is created (``histtype=0``).
+# To show the frequency percent set the ``histtpye`` parameter to ``1``. For further
+# options please have a look at the documentation of :meth:`pygmt.Figure.histogram`.
 
-# Create new figure instance
 fig = pygmt.Figure()
 
 # Create histogram for data02 showing counts
@@ -159,8 +152,7 @@
     histtype=0,
 )
 
-# Shift plot origin 11 centimeters to the right
-fig.shift_origin(xshift="11c")
+fig.shift_origin(xshift="w+1c")
 
 # Create histogram for data02 showing frequency percent
 fig.histogram(
@@ -183,12 +175,11 @@
 # Cumulative values
 # -----------------
 #
-# To create a histogram showing the cumulative values set ``cumulative=True``.
-# Here, the bars of the cumulative histogram are filled with a pattern via
-# the ``fill`` parameter. Annotate each bar with the counts it represents
-# using the ``annotate`` parameter.
+# To create a histogram showing the cumulative values set ``cumulative=True``. Here,
+# the bars of the cumulative histogram are filled with a pattern via the ``fill``
+# parameter. Annotate each bar with the counts it represents using the ``annotate``
+# parameter.
 
-# Create new figure instance
 fig = pygmt.Figure()
 
 # Create histogram for data01 showing the counts per bin
@@ -205,8 +196,7 @@
     annotate=True,
 )
 
-# Shift plot origin 11 centimeters to the right
-fig.shift_origin(xshift="11c")
+fig.shift_origin(xshift="w+1c")
 
 # Create histogram for data01 showing the cumulative counts
 fig.histogram(
@@ -215,15 +205,15 @@
     frame=["wSnE", "xaf10", "ya5f1+lCumulative counts"],
     data=data01,
     series=10,
-    # Use pattern (p) number 8 as fill for the bars
-    # Set the background (+b) to white [Default]
-    # Set the foreground (+f) to black [Default]
+    # Use pattern ("p") number 8 as fill for the bars
+    # Set the background ("+b") to white [Default]
+    # Set the foreground ("+f") to black [Default]
     fill="p8+bwhite+fblack",
     pen="1p,darkgray,solid",
     histtype=0,
     # Show cumulative counts
     cumulative=True,
-    # Offset (+o) the label by 10 points in negative y-direction
+    # Offset ("+o") the label by 10 points in negative y-direction
     annotate="+o-10p",
 )
 
@@ -234,17 +224,16 @@
 # Overlaid bars
 # -------------
 #
-# Overlaid or overlapping bars can be achieved by plotting two or several
-# histograms, each for one data set, on top of each other. The legend entry
-# can be specified via the ``label`` parameter.
+# Overlaid or overlapping bars can be achieved by plotting two or several histograms,
+# each for one data set, on top of each other. The legend entry can be specified via
+# the ``label`` parameter.
 #
 # Limitations of histograms with overlaid bars are:
 #
 # - Mixing of colors or/and patterns
 # - Visually more colors or/and patterns than data sets
 # - Visually a "third histogram" (or more in case of more than two data sets)
 
-# Create new figure instance
 fig = pygmt.Figure()
 
 # Create histogram for data01
@@ -283,10 +272,10 @@
 # Stacked bars
 # ------------
 #
-# Histograms with stacked bars are not directly supported by PyGMT. Thus,
-# before plotting, combined data sets have to be created from the single data
-# sets. Then, stacked bars can be achieved similar to overlaid bars via
-# plotting two or several histograms on top of each other.
+# Histograms with stacked bars are not directly supported by PyGMT. Thus, before
+# plotting, combined data sets have to be created from the single data sets. Then,
+# stacked bars can be achieved similar to overlaid bars via plotting two or several
+# histograms on top of each other.
 #
 # Limitations of histograms with stacked bars are:
 #
@@ -296,7 +285,6 @@
 # Combine the two data sets to one data set
 data_merge = np.concatenate((data01, data02), axis=None)
 
-# Create new figure instance
 fig = pygmt.Figure()
 
 # Create histogram for data02 by using the combined data set
@@ -309,8 +297,7 @@
     fill="orange",
     pen="1p,darkgray,solid",
     histtype=0,
-    # The combined data set appears in the final histogram visually
-    # as data set data02
+    # The combined data set appears in the final histogram visually as data set data02
     label="data02",
 )
 
@@ -346,7 +333,6 @@
 # Width used for binning the data
 binwidth = 10
 
-# Create new figure instance
 fig = pygmt.Figure()
 
 # Create histogram for data01
@@ -359,10 +345,10 @@
     fill="red3",
     pen="1p,darkgray,solid",
     histtype=0,
-    # Calculate the bar width in respect to the bin width, here for two
-    # data sets half of the bin width
-    # Offset (+o) the bars to align each bar with the left limit of the
-    # corresponding bin
+    # Calculate the bar width in respect to the bin width, here for two data sets half
+    # of the bin width
+    # Offset ("+o") the bars to align each bar with the left limit of the corresponding
+    # bin
     barwidth=f"{binwidth/2}+o-{binwidth/4}",
     label="data01",
 )