Merge pull request #20562 from timhoffm/doc-faq

jklymak · web-flow · commit c61077a5e395 · 2021-07-04T09:24:43.000-07:00
More concise how to for subplot adjustment
diff --git a/doc/faq/howto_faq.rst b/doc/faq/howto_faq.rst
@@ -137,106 +137,25 @@ The same can be done using the pgf backend::
 
     from matplotlib.backends.backend_pgf import PdfPages
 
-.. _howto-subplots-adjust:
 
-Move the edge of an axes to make room for tick labels
------------------------------------------------------
-
-For subplots, you can control the default spacing on the left, right,
-bottom, and top as well as the horizontal and vertical spacing between
-multiple rows and columns using the
-:meth:`matplotlib.figure.Figure.subplots_adjust` method (in pyplot it
-is :func:`~matplotlib.pyplot.subplots_adjust`).  For example, to move
-the bottom of the subplots up to make room for some rotated x tick
-labels::
+.. _howto-auto-adjust:
 
-    fig = plt.figure()
-    fig.subplots_adjust(bottom=0.2)
-    ax = fig.add_subplot(111)
+Make room for tick labels
+-------------------------
 
-You can control the defaults for these parameters in your
-:file:`matplotlibrc` file; see :doc:`/tutorials/introductory/customizing`.  For
-example, to make the above setting permanent, you would set::
-
-    figure.subplot.bottom : 0.2   # the bottom of the subplots of the figure
-
-The other parameters you can configure are, with their defaults
-
-*left*  = 0.125
-    the left side of the subplots of the figure
-*right* = 0.9
-    the right side of the subplots of the figure
-*bottom* = 0.1
-    the bottom of the subplots of the figure
-*top* = 0.9
-    the top of the subplots of the figure
-*wspace* = 0.2
-    the amount of width reserved for space between subplots,
-    expressed as a fraction of the average axis width
-*hspace* = 0.2
-    the amount of height reserved for space between subplots,
-    expressed as a fraction of the average axis height
-
-If you want additional control, you can create an
-:class:`~matplotlib.axes.Axes` using the
-:func:`~matplotlib.pyplot.axes` command (or equivalently the figure
-:meth:`~matplotlib.figure.Figure.add_axes` method), which allows you to
-specify the location explicitly::
-
-    ax = fig.add_axes([left, bottom, width, height])
-
-where all values are in fractional (0 to 1) coordinates.  See
-:doc:`/gallery/subplots_axes_and_figures/axes_demo` for an example of
-placing axes manually.
+By default, Matplotlib uses fixed percentage margins around subplots. This can
+lead to labels overlapping or being cut off at the figure boundary. There are
+multiple ways to fix this:
 
-.. _howto-auto-adjust:
+- Manually adapt the subplot parameters using `.Figure.subplots_adjust` /
+  `.pyplot.subplots_adjust`.
+- Use one of the automatic layout mechanisms:
 
-Automatically make room for tick labels
----------------------------------------
+  - constrained layout (:doc:`/tutorials/intermediate/constrainedlayout_guide`)
+  - tight layout (:doc:`/tutorials/intermediate/tight_layout_guide`)
 
-.. note::
-   This is now easier to handle than ever before.
-   Calling :func:`~matplotlib.pyplot.tight_layout` or alternatively using
-   ``constrained_layout=True`` argument in :func:`~matplotlib.pyplot.subplots`
-   can fix many common layout issues.  See the
-   :doc:`/tutorials/intermediate/tight_layout_guide` and
-   :doc:`/tutorials/intermediate/constrainedlayout_guide` for more details.
-
-   The information below is kept here in case it is useful for other
-   purposes.
-
-In most use cases, it is enough to simply change the subplots adjust
-parameters as described in :ref:`howto-subplots-adjust`.  But in some
-cases, you don't know ahead of time what your tick labels will be, or
-how large they will be (data and labels outside your control may be
-being fed into your graphing application), and you may need to
-automatically adjust your subplot parameters based on the size of the
-tick labels.  Any :class:`~matplotlib.text.Text` instance can report
-its extent in window coordinates (a negative x coordinate is outside
-the window), but there is a rub.
-
-The :class:`~matplotlib.backend_bases.RendererBase` instance, which is
-used to calculate the text size, is not known until the figure is
-drawn (:meth:`~matplotlib.figure.Figure.draw`).  After the window is
-drawn and the text instance knows its renderer, you can call
-:meth:`~matplotlib.text.Text.get_window_extent`.  One way to solve
-this chicken and egg problem is to wait until the figure is draw by
-connecting
-(:meth:`~matplotlib.backend_bases.FigureCanvasBase.mpl_connect`) to the
-"on_draw" signal (:class:`~matplotlib.backend_bases.DrawEvent`) and
-get the window extent there, and then do something with it, e.g., move
-the left of the canvas over; see :ref:`event-handling-tutorial`.
-
-Here is an example that gets a bounding box in relative figure coordinates
-(0..1) of each of the labels and uses it to move the left of the subplots
-over so that the tick labels fit in the figure:
-
-.. figure:: ../gallery/pyplots/images/sphx_glr_auto_subplots_adjust_001.png
-    :target: ../gallery/pyplots/auto_subplots_adjust.html
-    :align: center
-    :scale: 50
-
-    Auto Subplots Adjust
+- Calculate good values from the size of the plot elements yourself
+  (:doc:`/gallery/pyplots/auto_subplots_adjust`)
 
 .. _howto-align-label:
 
diff --git a/examples/pyplots/auto_subplots_adjust.py b/examples/pyplots/auto_subplots_adjust.py
@@ -1,15 +1,41 @@
 """
-====================
-Auto Subplots Adjust
-====================
+===============================================
+Programmatically controlling subplot adjustment
+===============================================
 
-Automatically adjust subplot parameters. This example shows a way to determine
-a subplot parameter from the extent of the ticklabels using a callback on the
-:doc:`draw_event</users/event_handling>`.
+.. note::
 
-Note that a similar result would be achieved using `~.Figure.tight_layout`
-or `~.Figure.set_constrained_layout`; this example shows how one could
-customize the subplot parameter adjustment.
+    This example is primarily intended to show some advanced concepts in
+    Matplotlib.
+
+    If you are only looking for having enough space for your labels, it is
+    almost always simpler and good enough to either set the subplot parameters
+    manually using `.Figure.subplots_adjust`, or use one of the automatic
+    layout mechanisms
+    (:doc:`/tutorials/intermediate/constrainedlayout_guide` or
+    :doc:`/tutorials/intermediate/tight_layout_guide`).
+
+This example describes a user-defined way to read out Artist sizes and
+set the subplot parameters accordingly. Its main purpose is to illustrate
+some advanced concepts like reading out text positions, working with
+bounding boxes and transforms and using
+:ref:`events <event-handling-tutorial>`. But it can also serve as a starting
+point if you want to automate the layouting and need more flexibility than
+tight layout and constrained layout.
+
+Below, we collect the bounding boxes of all y-labels and move the left border
+of the subplot to the right so that it leaves enough room for the union of all
+the bounding boxes.
+
+There's one catch with calculating text bounding boxes:
+Querying the text bounding boxes (`.Text.get_window_extent`) needs a
+renderer (`.RendererBase` instance), to calculate the text size. This renderer
+is only available after the figure has been drawn (`.Figure.draw`).
+
+A solution to this is putting the adjustment logic in a draw callback.
+This function is executed after the figure has been drawn. It can now check
+if the subplot leaves enough room for the text. If not, the subplot parameters
+are updated and second draw is triggered.
 """
 
 import matplotlib.pyplot as plt
@@ -24,15 +50,16 @@
 def on_draw(event):
     bboxes = []
     for label in labels:
-        bbox = label.get_window_extent()
-        # the figure transform goes from relative coords->pixels and we
-        # want the inverse of that
-        bboxi = bbox.transformed(fig.transFigure.inverted())
-        bboxes.append(bboxi)
+        # Bounding box in pixels
+        bbox_px = label.get_window_extent()
+        # Transform to relative figure coordinates. This is the inverse of
+        # transFigure.
+        bbox_fig = bbox_px.transformed(fig.transFigure.inverted())
+        bboxes.append(bbox_fig)
     # the bbox that bounds all the bboxes, again in relative figure coords
     bbox = mtransforms.Bbox.union(bboxes)
     if fig.subplotpars.left < bbox.width:
-        # we need to move it over
+        # Move the subplot left edge more to the right
         fig.subplots_adjust(left=1.1*bbox.width)  # pad a little
         fig.canvas.draw()
 
diff --git a/tutorials/intermediate/constrainedlayout_guide.py b/tutorials/intermediate/constrainedlayout_guide.py
@@ -77,10 +77,10 @@ def example_plot(ax, fontsize=12, hide_labels=False):
 
 ###############################################################################
 # To prevent this, the location of axes needs to be adjusted. For
-# subplots, this can be done by adjusting the subplot params
-# (:ref:`howto-subplots-adjust`). However, specifying your figure with the
-# ``constrained_layout=True`` keyword argument will do the adjusting
-# automatically.
+# subplots, this can be done manually by adjusting the subplot parameters
+# using `.Figure.subplots_adjust`. However, specifying your figure with the
+# # ``constrained_layout=True`` keyword argument will do the adjusting
+# # automatically.
 
 fig, ax = plt.subplots(constrained_layout=True)
 example_plot(ax, fontsize=24)
diff --git a/tutorials/intermediate/tight_layout_guide.py b/tutorials/intermediate/tight_layout_guide.py
@@ -46,9 +46,9 @@ def example_plot(ax, fontsize=12):
 
 ###############################################################################
 # To prevent this, the location of axes needs to be adjusted. For
-# subplots, this can be done by adjusting the subplot params
-# (:ref:`howto-subplots-adjust`). Matplotlib v1.1 introduced
-# `.Figure.tight_layout` that does this automatically for you.
+# subplots, this can be done manually by adjusting the subplot parameters
+# using `.Figure.subplots_adjust`. `.Figure.tight_layout` does this
+# automatically.
 
 fig, ax = plt.subplots()
 example_plot(ax, fontsize=24)
