DOC: change gridspec tutorial

jklymak · jklymak · commit 7f7192c54904 · 2018-04-10T09:53:27.000-07:00
diff --git a/lib/matplotlib/_constrained_layout.py b/lib/matplotlib/_constrained_layout.py
@@ -158,6 +158,7 @@ def do_constrained_layout(fig, renderer, h_pad, w_pad,
 
     '''
 
+    _log.debug('Starting do_constrained_layout')
     invTransFig = fig.transFigure.inverted().transform_bbox
 
     # list of unique gridspecs that contain child axes:
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -2252,9 +2252,9 @@ def align_labels(self, axs=None):
 
         See Also
         --------
-        `matplotlib.figure.Figure.align_xlabels`
+        matplotlib.figure.Figure.align_xlabels
 
-        `matplotlib.figure.Figure.align_ylabels`
+        matplotlib.figure.Figure.align_ylabels
         """
         self.align_xlabels(axs=axs)
         self.align_ylabels(axs=axs)
diff --git a/tutorials/intermediate/gridspec.py b/tutorials/intermediate/gridspec.py
@@ -7,8 +7,9 @@
 
     :func:`~matplotlib.pyplot.subplots`
         Perhaps the primary function used to create figures and axes.
-        It's also similar to :func:`~matplotlib.pyplot.subplot`,
-        but creates and places all axes on the figure at once.
+        It's also similar to :func:`.matplotlib.pyplot.subplot`,
+        but creates and places all axes on the figure at once.  See also
+        `.matplotlib.Figure.subplots`.
 
     :class:`~matplotlib.gridspec.GridSpec`
         Specifies the geometry of the grid that a subplot will be
@@ -40,8 +41,7 @@
 # It returns a :class:`~matplotlib.figure.Figure` instance and an array of
 # :class:`~matplotlib.axes.Axes` objects.
 
-fig1, f1_axes = plt.subplots(ncols=2, nrows=2)
-fig1.tight_layout()
+fig1, f1_axes = plt.subplots(ncols=2, nrows=2, contstrained_layout=True)
 
 ############################################################################
 # For a simple use case such as this, :mod:`~matplotlib.gridspec` is
@@ -53,13 +53,12 @@
 # The elements of the gridspec are accessed in generally the same manner as
 # numpy arrays.
 
-fig2 = plt.figure()
+fig2 = plt.figure(contstrained_layout=True)
 spec2 = gridspec.GridSpec(ncols=2, nrows=2)
 f2_ax1 = fig2.add_subplot(spec2[0, 0])
 f2_ax2 = fig2.add_subplot(spec2[0, 1])
 f2_ax3 = fig2.add_subplot(spec2[1, 0])
 f2_ax4 = fig2.add_subplot(spec2[1, 1])
-fig2.tight_layout()
 
 #############################################################################
 # When you want to have subplots of different sizes, however,
@@ -69,17 +68,17 @@
 # and then uses typical numpy indexing and slices to allocate multiple
 # "cells" for a given subplot.
 
-fig3 = plt.figure()
-spec3 = gridspec.GridSpec(ncols=3, nrows=3)
+fig3 = plt.figure(contstrained_layout=True)
+spec3 = fig3.add_gridspec(ncols=3, nrows=3)
 anno_opts = dict(xy=(0.5, 0.5), xycoords='axes fraction',
                  va='center', ha='center')
 
 fig3.add_subplot(spec3[0, 0]).annotate('GridSpec[0, 0]', **anno_opts)
 fig3.add_subplot(spec3[0, 1:]).annotate('GridSpec[0, 1:]', **anno_opts)
 fig3.add_subplot(spec3[1:, 0]).annotate('GridSpec[1:, 0]', **anno_opts)
 fig3.add_subplot(spec3[1:, 1:]).annotate('GridSpec[1:, 1:]', **anno_opts)
-
-fig3.tight_layout()
+fig3.canvas.draw()  # Sometime constrained_layout needs an extra draw...
+fig3.show()
 
 ############################################################################
 # Other option is to use the ``width_ratios`` and ``height_ratios``
@@ -90,19 +89,17 @@
 # For the sake of demonstration, we'll blindly create the axes within
 # ``for`` loops since we won't need them later.
 
-fig4 = plt.figure()
+fig4 = plt.figure(contstrained_layout=True)
 widths = [2, 3, 1.5]
 heights = [1, 3, 2]
-spec4 = gridspec.GridSpec(ncols=3, nrows=3, width_ratios=widths,
+spec4 = fig4.add_gridspec(ncols=3, nrows=3, width_ratios=widths,
                           height_ratios=heights)
 for row in range(3):
     for col in range(3):
         ax = fig4.add_subplot(spec4[row, col])
         label = 'Width: {}\nHeight: {}'.format(widths[col], heights[row])
         ax.annotate(label, (0.1, 0.5), xycoords='axes fraction', va='center')
 
-fig4.tight_layout()
-
 ############################################################################
 # Learning to use ``width_ratios`` and ``height_ratios`` is particularly
 # useful since the top-level function :func:`~matplotlib.pyplot.subplots`
@@ -114,49 +111,47 @@
 # gridspec instance.
 
 gs_kw = dict(width_ratios=widths, height_ratios=heights)
-fig5, f5_axes = plt.subplots(ncols=3, nrows=3, gridspec_kw=gs_kw)
+fig5, f5_axes = plt.subplots(ncols=3, nrows=3, contstrained_layout=True,
+        gridspec_kw=gs_kw)
 for r, row in enumerate(f5_axes):
     for c, ax in enumerate(row):
         label = 'Width: {}\nHeight: {}'.format(widths[c], heights[r])
         ax.annotate(label, (0.1, 0.5), xycoords='axes fraction', va='center')
 
-fig5.tight_layout()
-
-
 ###############################################################################
 # Fine Adjustments to a Gridspec Layout
 # =====================================
 #
 # When a GridSpec is explicitly used, you can adjust the layout
 # parameters of subplots that are created from the GridSpec.
 
-fig = plt.figure()
-gs1 = gridspec.GridSpec(nrows=3, ncols=3, left=0.05, right=0.48, wspace=0.05)
-ax1 = fig.add_subplot(gs1[:-1, :])
-ax2 = fig.add_subplot(gs1[-1, :-1])
-ax3 = fig.add_subplot(gs1[-1, -1])
-
+fig6 = plt.figure()
+gs1 = fig6.add_gridspec(nrows=3, ncols=3, left=0.05, right=0.48, wspace=0.05)
+ax1 = fig6.add_subplot(gs1[:-1, :])
+ax2 = fig6.add_subplot(gs1[-1, :-1])
+ax3 = fig6.add_subplot(gs1[-1, -1])
+fig6.canvas.draw()
 
 ###############################################################################
 # This is similar to :func:`~matplotlib.pyplot.subplots_adjust`, but it only
 # affects the subplots that are created from the given GridSpec.
 #
 # For example, compare the left and right sides of this figure:
 
-fig = plt.figure()
-gs1 = gridspec.GridSpec(nrows=3, ncols=3, left=0.05, right=0.48,
+fig = plt.figure(constrained_layout=False)
+gs1 = fig.add_gridspec(nrows=3, ncols=3, left=0.05, right=0.48,
                         wspace=0.05)
 ax1 = fig.add_subplot(gs1[:-1, :])
 ax2 = fig.add_subplot(gs1[-1, :-1])
 ax3 = fig.add_subplot(gs1[-1, -1])
 
-
-gs2 = gridspec.GridSpec(nrows=3, ncols=3, left=0.55, right=0.98,
+gs2 = fig.add_gridspec(nrows=3, ncols=3, left=0.55, right=0.98,
                         hspace=0.05)
 ax4 = fig.add_subplot(gs2[:, :-1])
 ax5 = fig.add_subplot(gs2[:-1, -1])
 ax6 = fig.add_subplot(gs2[-1, -1])
 
+
 ###############################################################################
 # GridSpec using SubplotSpec
 # ==========================
@@ -165,19 +160,17 @@
 # in which case its layout parameters are set to that of the location of
 # the given SubplotSpec.
 
-fig = plt.figure()
-gs0 = gridspec.GridSpec(1, 2)
+fig = plt.figure(contstrained_layout=True)
+gs0 = fig.add_gridspec(1, 2)
 
-gs00 = gridspec.GridSpecFromSubplotSpec(2, 3, subplot_spec=gs0[0])
-gs01 = gridspec.GridSpecFromSubplotSpec(3, 2, subplot_spec=gs0[1])
+gs00 = gs0[0].subgridspec(2, 3)
+gs01 = gs0[1].subgridspec(3, 2)
 
 for a in range(2):
     for b in range(3):
         fig.add_subplot(gs00[a, b])
         fig.add_subplot(gs01[b, a])
 
-fig.tight_layout()
-
 ###############################################################################
 # A Complex Nested GridSpec using SubplotSpec
 # ===========================================
@@ -189,18 +182,16 @@
 import numpy as np
 from itertools import product
 
-
 def squiggle_xy(a, b, c, d, i=np.arange(0.0, 2*np.pi, 0.05)):
     return np.sin(i*a)*np.cos(i*b), np.sin(i*c)*np.cos(i*d)
 
-fig = plt.figure(figsize=(8, 8))
+fig = plt.figure(figsize=(8, 8), constrained_layout=False)
 
 # gridspec inside gridspec
-outer_grid = gridspec.GridSpec(4, 4, wspace=0.0, hspace=0.0)
+outer_grid = fig.add_gridspec(4, 4, wspace=0.0, hspace=0.0)
 
 for i in range(16):
-    inner_grid = gridspec.GridSpecFromSubplotSpec(
-      3, 3, subplot_spec=outer_grid[i], wspace=0.0, hspace=0.0)
+    inner_grid = outer_grid[i].subgridspec(3, 3, wspace=0.0, hspace=0.0)
     a, b = int(i/4)+1, i % 4+1
     for j, (c, d) in enumerate(product(range(1, 4), repeat=2)):
         ax = plt.Subplot(fig, inner_grid[j])
@@ -225,3 +216,19 @@ def squiggle_xy(a, b, c, d, i=np.arange(0.0, 2*np.pi, 0.05)):
         ax.spines['right'].set_visible(True)
 
 plt.show()
+
+#############################################################################
+#
+# ------------
+#
+# References
+# """"""""""
+#
+# The usage of the following functions and methods is shown in this example:
+
+matplotlib.pyplot.subplots
+matplotlib.figure.Figure.add_gridspec
+matplotlib.figure.Figure.add_subplot
+matplotlib.gridspec.GridSpec
+matplotlib.gridspec.SubplotSpec.subgridspec
+matplotlib.gridspec.GridSpecFromSubplotSpec
