DOC: add a couple more placement examples, crosslink axes_grid [ci doc]

jklymak · rcomer · jklymak · commit c23438433045 · 2023-09-26T09:49:52.000-07:00
Co-authored-by: Ruth Comer &lt;10599679+rcomer@users.noreply.github.com&gt;
diff --git a/galleries/examples/axes_grid1/demo_colorbar_with_axes_divider.py b/galleries/examples/axes_grid1/demo_colorbar_with_axes_divider.py
@@ -1,4 +1,6 @@
 """
+.. _demo-colorbar-with-axes-divider:
+
 =========================
 Colorbar with AxesDivider
 =========================
@@ -8,6 +10,10 @@
 method of the `.AxesDivider` can then be used to create a new axes on a given
 side ("top", "right", "bottom", or "left") of the original axes. This example
 uses `.append_axes` to add colorbars next to axes.
+
+Users should consider simply passing the main axes to the *ax* keyword argument of
+`~.Figure.colorbar` instead of creating a locatable axes manually like this.
+See :ref:`colorbar_placement`.
 """
 
 import matplotlib.pyplot as plt
diff --git a/galleries/examples/axes_grid1/demo_colorbar_with_inset_locator.py b/galleries/examples/axes_grid1/demo_colorbar_with_inset_locator.py
@@ -1,15 +1,21 @@
 """
+.. _demo-colorbar-with-inset-locator:
+
 ==============================================================
 Controlling the position and size of colorbars with Inset Axes
 ==============================================================
 
-This example shows how to control the position, height, and width of
-colorbars using `~mpl_toolkits.axes_grid1.inset_locator.inset_axes`.
+This example shows how to control the position, height, and width of colorbars
+using `~mpl_toolkits.axes_grid1.inset_locator.inset_axes`.
 
 Inset axes placement is controlled as for legends: either by providing a *loc*
 option ("upper right", "best", ...), or by providing a locator with respect to
 the parent bbox.  Parameters such as *bbox_to_anchor* and *borderpad* likewise
 work in the same way, and are also demonstrated here.
+
+Users should consider using `.Axes.inset_axes` instead (see
+:ref:`colorbar_placement`).
+
 """
 
 import matplotlib.pyplot as plt
diff --git a/galleries/users_explain/axes/colorbar_placement.py b/galleries/users_explain/axes/colorbar_placement.py
@@ -28,9 +28,9 @@
         fig.colorbar(pcm, ax=ax)
 
 # %%
-# The first column has the same type of data in both rows, so it may
-# be desirable to combine the colorbar which we do by calling
-# `.Figure.colorbar` with a list of axes instead of a single axes.
+# The first column has the same type of data in both rows, so it may be
+# desirable to have just one colorbar. We do this by passing `.Figure.colorbar`
+# a list of axes with the *ax* kwarg.
 
 fig, axs = plt.subplots(2, 2)
 cmaps = ['RdBu_r', 'viridis']
@@ -56,8 +56,74 @@
 fig.colorbar(pcm, ax=[axs[2, 1]], location='left')
 
 # %%
-# Colorbars with fixed-aspect-ratio axes
-# ======================================
+# Adjusting the spacing between colorbars and parent axes
+# =======================================================
+#
+# The distance a colorbar is from the parent axes can be adjusted with the
+# *pad* keyword argument.  This is in units of fraction of the parent axes
+# width, and the default for a vertical axes is 0.05 (or 0.15 for a horizontal
+# axes).
+
+fig, axs = plt.subplots(3, 1, layout='constrained', figsize=(5, 5))
+for ax, pad in zip(axs, [0.025, 0.05, 0.1]):
+    pcm = ax.pcolormesh(np.random.randn(20, 20), cmap='viridis')
+    fig.colorbar(pcm, ax=ax, pad=pad, label=f'pad: {pad}')
+fig.suptitle("layout='constrained'")
+
+# %%
+# Note that if you do not use constrained layout, the pad command makes the
+# parent axes shrink:
+
+fig, axs = plt.subplots(3, 1, figsize=(5, 5))
+for ax, pad in zip(axs, [0.025, 0.05, 0.1]):
+    pcm = ax.pcolormesh(np.random.randn(20, 20), cmap='viridis')
+    fig.colorbar(pcm, ax=ax, pad=pad, label=f'pad: {pad}')
+fig.suptitle("No layout manager")
+
+# %%
+# Manual placement of colorbars
+# =============================
+#
+# Sometimes the automatic placement provided by ``colorbar`` does not
+# give the desired effect.  We can manually create an axes and tell
+# ``colorbar`` to use that axes by passing the axes to the *cax* keyword
+# argument.
+#
+# Using ``inset_axes``
+# --------------------
+#
+# We can manually create any type of axes for the colorbar to use, but an
+# `.Axes.inset_axes` is useful because it is a child of the parent axes and can
+# be positioned relative to the parent.  Here we add a colorbar centered near
+# the bottom of the parent axes.
+
+fig, ax = plt.subplots(layout='constrained', figsize=(4, 4))
+pcm = ax.pcolormesh(np.random.randn(20, 20), cmap='viridis')
+ax.set_ylim([-4, 20])
+cax = ax.inset_axes([0.3, 0.07, 0.4, 0.04])
+fig.colorbar(pcm, cax=cax, orientation='horizontal')
+
+# %%
+# `.Axes.inset_axes` can also specify its position in data coordinates
+# using the *transform* keyword argument if you want your axes at a
+# certain data position on the graph:
+
+fig, ax = plt.subplots(layout='constrained', figsize=(4, 4))
+pcm = ax.pcolormesh(np.random.randn(20, 20), cmap='viridis')
+ax.set_ylim([-4, 20])
+cax = ax.inset_axes([7.5, -1.7, 5, 1.2], transform=ax.transData)
+fig.colorbar(pcm, cax=cax, orientation='horizontal')
+
+# %%
+# .. seealso::
+#
+#  :ref:`axes_grid` has methods for creating colorbar axes as well:
+#
+#  - :ref:`demo-colorbar-with-inset-locator`
+#  - :ref:`demo-colorbar-with-axes-divider`
+#
+# Colorbars attached to fixed-aspect-ratio axes
+# ---------------------------------------------
 #
 # Placing colorbars for axes with a fixed aspect ratio pose a particular
 # challenge as the parent axes changes size depending on the data view.
@@ -77,8 +143,8 @@
             fig.colorbar(pcm, ax=ax, shrink=0.6)
 
 # %%
-# One way around this issue is to use an `.Axes.inset_axes` to locate the
-# axes in axes coordinates.  Note that if you zoom in on the axes, and
+# We solve this problem using `.Axes.inset_axes` to locate the axes in axes
+# coordinates.  Note that if you zoom in on the axes, and thus
 # change the shape of the axes, the colorbar will also change position.
 
 fig, axs = plt.subplots(2, 2, layout='constrained')
@@ -94,6 +160,4 @@
             ax.set_aspect(1/2)
         if row == 1:
             cax = ax.inset_axes([1.04, 0.2, 0.05, 0.6])
-            fig.colorbar(pcm, ax=ax, cax=cax)
-
-plt.show()
+            fig.colorbar(pcm, cax=cax)
