Demonstrate inset_axes in scatter_hist example.

anntzer · anntzer · commit af7d306091f6 · 2021-10-05T17:03:23.000+02:00
Currently, the scatter_hist example needs to force the main axes to be
square by carefully adjusting the figure size -- shared axes and fixed
aspects don't work well together (and manually resizing the figure shows
that the aspect is indeed not fixed).  In fact, the
scatter_hist_locatable_axes example explicitly states that the advantage
of using axes_grid1 is to allow the aspect to be fixed.

I realized that one can also use inset_axes to position the marginals
axes relative to the main axes *and* support a fixed aspect ratio for
the main axes.  Perhaps this can be considered as a slight API abuse,
but I think this is a solution for a real limitation; the question is
whether we want to promote this use?
diff --git a/examples/axes_grid1/scatter_hist_locatable_axes.py b/examples/axes_grid1/scatter_hist_locatable_axes.py
@@ -10,9 +10,10 @@
 are defined by a ``Divider``, produced via `.make_axes_locatable`.
 
 An alternative method to produce a similar figure is shown in the
-:doc:`/gallery/lines_bars_and_markers/scatter_hist` example. The advantage of
-the locatable axes method shown below is that the marginal axes follow the
-fixed aspect ratio of the main axes.
+:doc:`/gallery/lines_bars_and_markers/scatter_hist` example.  The main
+difference is that the size of the marginals and the paddings are in inches
+(rather than relative to the main axes).  Moreover, similarly to the
+`~.Axes.inset_axes` approach, the main axes can have a fixed aspect ratio.
 """
 
 import numpy as np
diff --git a/examples/lines_bars_and_markers/scatter_hist.py b/examples/lines_bars_and_markers/scatter_hist.py
@@ -11,6 +11,7 @@
 
 * the axes positions are defined in terms of rectangles in figure coordinates
 * the axes positions are defined via a gridspec
+* the axes positions are defined via a inset_axes
 
 An alternative method to produce a similar figure using the ``axes_grid1``
 toolkit is shown in the
@@ -70,7 +71,7 @@ def scatter_hist(x, y, ax, ax_histx, ax_histy):
 rect_histy = [left + width + spacing, bottom, 0.2, height]
 
 # start with a square Figure
-fig = plt.figure(figsize=(8, 8))
+fig = plt.figure(figsize=(6, 6))
 
 ax = fig.add_axes(rect_scatter)
 ax_histx = fig.add_axes(rect_histx, sharex=ax)
@@ -79,8 +80,6 @@ def scatter_hist(x, y, ax, ax_histx, ax_histy):
 # use the previously defined function
 scatter_hist(x, y, ax, ax_histx, ax_histy)
 
-plt.show()
-
 
 #############################################################################
 #
@@ -92,7 +91,7 @@ def scatter_hist(x, y, ax, ax_histx, ax_histy):
 # tutorial.
 
 # start with a square Figure
-fig = plt.figure(figsize=(8, 8))
+fig = plt.figure(figsize=(6, 6))
 
 # Add a gridspec with two rows and two columns and a ratio of 2 to 7 between
 # the size of the marginal axes and the main axes in both directions.
@@ -108,6 +107,30 @@ def scatter_hist(x, y, ax, ax_histx, ax_histy):
 # use the previously defined function
 scatter_hist(x, y, ax, ax_histx, ax_histy)
 
+
+#############################################################################
+#
+# Using inset_axes
+# ----------------
+#
+# Despite its name, `~.Axes.inset_axes` can also be used to position marginals
+# *outside* the main axes.  The advantage of doing so is that the aspect ratio
+# of the main axes can be fixed, regardless of the figure size.
+
+fig = plt.figure(constrained_layout=True)  # doesn't need to be square
+
+# Create the main axes, leaving 25% of the figure space at the top and on the
+# right to position marginals.
+ax = fig.add_gridspec(top=0.75, right=0.75).subplots()
+# The axes' aspect can be fixed.
+ax.set(aspect=1)
+# Create marginals, which have 25% of the size of the main axes.
+ax_histx = ax.inset_axes([0, 1.05, 1, 0.25], sharex=ax)
+ax_histy = ax.inset_axes([1.05, 0, 0.25, 1], sharey=ax)
+
+# use the previously defined function
+scatter_hist(x, y, ax, ax_histx, ax_histy)
+
 plt.show()
 
 
@@ -121,5 +144,6 @@ def scatter_hist(x, y, ax, ax_histx, ax_histy):
 #    - `matplotlib.figure.Figure.add_axes`
 #    - `matplotlib.figure.Figure.add_subplot`
 #    - `matplotlib.figure.Figure.add_gridspec`
+#    - `matplotlib.axes.Axes.inset_axes`
 #    - `matplotlib.axes.Axes.scatter`
 #    - `matplotlib.axes.Axes.hist`
