DOC/Gallery example "Scatter plot with histograms": General improvements (#3628)

Co-authored-by: Dongdong Tian <[email protected]>
Co-authored-by: Michael Grund <[email protected]>

Author: 3 people

examples/gallery/histograms/scatter_and_histograms.py

@@ -2,70 +2,75 @@
 Scatter plot with histograms
 ============================
 
-To create a scatter plot with histograms at the sides of the plot one
-can use :meth:`pygmt.Figure.plot` in combination with
-:meth:`pygmt.Figure.histogram`. The positions of the histograms are plotted
-by offsetting them from the main scatter plot figure using
-:meth:`pygmt.Figure.shift_origin`.
+To create a scatter plot with histograms at the sides of the plot one can use
+:meth:`pygmt.Figure.plot` in combination with :meth:`pygmt.Figure.histogram`. The
+positions of the histograms are plotted by offsetting them from the main scatter plot
+using :meth:`pygmt.Figure.shift_origin`.
 """
 
 # %%
 import numpy as np
 import pygmt
 
-# Generate random data from a standard normal distribution centered on 0
-# with a standard deviation of 1
-rng = np.random.default_rng(seed=19680801)
+# Generate random x, y coordinates from a standard normal distribution.
+# x values are centered on 0 with a standard deviation of 1, and y values are centered
+# on 30 with a standard deviation of 2.
+rng = np.random.default_rng()
 x = rng.normal(loc=0, scale=1, size=1000)
-y = rng.normal(loc=0, scale=1, size=1000)
+y = rng.normal(loc=30, scale=2, size=1000)
 
-# Get axis limits
-xymax = max(np.max(np.abs(x)), np.max(np.abs(y)))
+# Get axis limits from the data limits. Extend the limits by 0.5 to add some margin.
+xmin = np.floor(x.min()) - 0.5
+xmax = np.ceil(x.max()) + 0.5
+ymin = np.floor(y.min()) - 0.5
+ymax = np.ceil(y.max()) + 0.5
 
+# Set fill color for symbols and bars.
+fill = "seagreen"
+
+# Set the dimensions of the scatter plot.
+width, height = 10, 8
 
 fig = pygmt.Figure()
 fig.basemap(
-    region=[-xymax - 0.5, xymax + 0.5, -xymax - 0.5, xymax + 0.5],
-    projection="X10c/10c",
-    frame=["WSrt", "a1"],
+    region=[xmin, xmax, ymin, ymax],
+    projection=f"X{width}/{height}",
+    frame=["WSrt", "af"],
 )
 
-fillcol = "seagreen"
-
-# Plot data points as circles with a diameter of 0.15 centimeters
-fig.plot(x=x, y=y, style="c0.15c", fill=fillcol, transparency=50)
+# Plot data points as circles with a diameter of 0.15 centimeters and set transparency
+# level for all circles to deal with overplotting.
+fig.plot(x=x, y=y, style="c0.15c", fill=fill, transparency=50)
 
-# Shift the plot origin and add top margin histogram
-fig.shift_origin(yshift="10.25c")
+# Shift the plot origin and add top margin histogram.
+fig.shift_origin(yshift=height + 0.25)
 
 fig.histogram(
-    projection="X10c/2c",
-    frame=["Wsrt", "xf1", "y+lCounts"],
-    # Give the same value for ymin and ymax to have ymin and ymax
-    # calculated automatically
-    region=[-xymax - 0.5, xymax + 0.5, 0, 0],
+    projection=f"X{width}/3",
+    frame=["Wsrt", "xf", "yaf+lCounts"],
+    # Give the same value for ymin and ymax to have them calculated automatically.
+    region=[xmin, xmax, 0, 0],
     data=x,
-    fill=fillcol,
+    fill=fill,
     pen="0.1p,white",
     histtype=0,
-    series=0.1,
+    series=0.2,
 )
 
-# Shift the plot origin and add right margin histogram
-fig.shift_origin(yshift="-10.25c", xshift="10.25c")
+# Shift the plot origin and add right margin histogram.
+fig.shift_origin(yshift=-height - 0.25, xshift=width + 0.25)
 
+# Plot the horizontal histogram.
 fig.histogram(
     horizontal=True,
-    projection="X2c/10c",
-    # Note that the y-axis annotation "Counts" is shown in x-axis direction
-    # due to the rotation caused by horizontal=True
-    frame=["wSrt", "xf1", "y+lCounts"],
-    region=[-xymax - 0.5, xymax + 0.5, 0, 0],
+    projection=f"X3/{height}",
+    # Note that the x- and y-axis are flipped, with the y-axis plotted horizontally.
+    frame=["wSrt", "xf", "yaf+lCounts"],
+    region=[ymin, ymax, 0, 0],
     data=y,
-    fill=fillcol,
+    fill=fill,
     pen="0.1p,white",
     histtype=0,
-    series=0.1,
+    series=0.2,
 )
-
 fig.show()

examples/tutorials/advanced/cartesian_histograms.py

@@ -79,9 +79,8 @@
     fill="red3",
     pen="1p,darkgray,solid",
     histtype=0,
-    # Use horizontal bars
-    # Please note the flip of the x and y axes regarding annotations, ticks, gridlines,
-    # and labels
+    # Use horizontal bars. Note that the x- and y-axis are flipped, with the x-axis
+    # plotted vertically and the y-axis plotted horizontally.
     horizontal=True,
 )
 

pygmt/src/histogram.py

@@ -104,8 +104,9 @@ def histogram(self, data, **kwargs):
         Draw a stairs-step diagram which does not include the internal bars
         of the default histogram.
     horizontal : bool
-        Plot the histogram using horizontal bars instead of the
-        default vertical bars.
+        Plot the histogram horizontally from x = 0 [Default is vertically from y = 0].
+        The plot dimensions remain the same, but the two axes are flipped, i.e., the
+        x-axis is plotted vertically and the y-axis is plotted horizontally.
     series : int, str, or list
         [*min*\ /*max*\ /]\ *inc*\ [**+n**\ ].
         Set the interval for the width of each bar in the histogram.