diff --git a/‎galleries/examples/lines_bars_and_markers/scatter_hist.py‎
Lines changed: 22 additions & 19 deletions b/‎galleries/examples/lines_bars_and_markers/scatter_hist.py‎
Lines changed: 22 additions & 19 deletions
@@ -6,6 +6,9 @@
 Show the marginal distributions of a scatter plot as histograms at the sides of
 the plot.
 
+This layout has a central scatter plot, with marginal histograms above and to the
+right of the central plot.
+
 For a nice alignment of the main Axes with the marginals, two options are shown
 below:
 
@@ -55,27 +58,27 @@ def scatter_hist(x, y, ax, ax_histx, ax_histy):
 
 
 # %%
+# Defining the Axes positions using subplot_mosaic
+# ------------------------------------------------
 #
-# Defining the Axes positions using a gridspec
-# --------------------------------------------
+# We use the `~.pyplot.subplot_mosaic` function to define the positions and
+# names of the three axes; the empty axes is specified by `'.'`.  We manually
+# specify the size of the figure, and can make the different axes have
+# different sizes by specifying the *width_ratios* and *height_ratios*
+# arguments. The *layout* argument is set to `'constrained'` to optimize the
+# spacing between the axes.
 #
-# We define a gridspec with unequal width- and height-ratios to achieve desired
-# layout.  Also see the :ref:`arranging_axes` tutorial.
-
-# Start with a square Figure.
-fig = plt.figure(figsize=(6, 6))
-# Add a gridspec with two rows and two columns and a ratio of 1 to 4 between
-# the size of the marginal Axes and the main Axes in both directions.
-# Also adjust the subplot parameters for a square plot.
-gs = fig.add_gridspec(2, 2,  width_ratios=(4, 1), height_ratios=(1, 4),
-                      left=0.1, right=0.9, bottom=0.1, top=0.9,
-                      wspace=0.05, hspace=0.05)
-# Create the Axes.
-ax = fig.add_subplot(gs[1, 0])
-ax_histx = fig.add_subplot(gs[0, 0], sharex=ax)
-ax_histy = fig.add_subplot(gs[1, 1], sharey=ax)
-# Draw the scatter plot and marginals.
-scatter_hist(x, y, ax, ax_histx, ax_histy)
+# Note that there are other ways to accomplish the same layout using a gridspec
+# and only adding the three desired axes, or by using `~.pyplot.subplots` and
+# removing the unused axes in the upper right.  The arguments are similar to the ones
+# used here.
+
+fig, axs = plt.subplot_mosaic([['histx', '.'],
+                               ['scatter', 'histy']],
+                              figsize=(6, 6),
+                              width_ratios=(4, 1), height_ratios=(1, 4),
+                              layout='constrained')
+scatter_hist(x, y, axs['scatter'], axs['histx'], axs['histy'])
 
 
 # %%