matplotlib
diff --git a/‎doc/users/next_whats_new/fig_gridspec.rst‎
Lines changed: 18 additions & 0 deletions b/‎doc/users/next_whats_new/fig_gridspec.rst‎
Lines changed: 18 additions & 0 deletions
diff --git a/‎tutorials/intermediate/constrainedlayout_guide.py‎
Lines changed: 24 additions & 22 deletions b/‎tutorials/intermediate/constrainedlayout_guide.py‎
Lines changed: 24 additions & 22 deletions
diff --git a/‎tutorials/intermediate/gridspec.py‎
Lines changed: 27 additions & 18 deletions b/‎tutorials/intermediate/gridspec.py‎
Lines changed: 27 additions & 18 deletions
@@ -0,0 +1,18 @@
+New convenience methods for GridSpec
+------------------------------------
+
+There are new convenience methods for `.gridspec.GridSpec` and
+`.gridspec.GridSpecFromSubplotSpec`.  Instead of the former we can
+now call `.Figure.add_gridspec` and for the latter `.SubplotSpec.subgridspec`.
+
+.. code-block:: python
+
+    import matplotlib.pyplot as plt
+
+    fig = plt.figure()
+    gs0 = fig.add_gridspec(3, 1)
+    ax1 = fig.add_subplot(gs0[0])
+    ax2 = fig.add_subplot(gs0[1])
+    gssub = gs0[2].subgridspec(1, 3)
+    for i in range(3):
+        fig.add_subplot(gssub[0, i])
@@ -48,7 +48,6 @@
 plt.rcParams['savefig.facecolor'] = "0.8"
 plt.rcParams['figure.figsize'] = 4.5, 4.
 
-
 def example_plot(ax, fontsize=12, nodec=False):
     ax.plot([1, 2])
 
@@ -62,7 +61,7 @@ def example_plot(ax, fontsize=12, nodec=False):
         ax.set_yticklabels('')
 
 
-fig, ax = plt.subplots()
+fig, ax = plt.subplots(constrained_layout=False)
 example_plot(ax, fontsize=24)
 
 ###############################################################################
@@ -285,8 +284,10 @@ def example_plot(ax, fontsize=12, nodec=False):
 # with :func:`~matplotlib.figure.Figure.subplots` or
 # :func:`~matplotlib.gridspec.GridSpec` and
 # :func:`~matplotlib.figure.Figure.add_subplot`.
+#
+# Note that in what follows ``constrained_layout=True``
 
-fig = plt.figure(constrained_layout=True)
+fig = plt.figure()
 
 gs1 = gridspec.GridSpec(2, 1, figure=fig)
 ax1 = fig.add_subplot(gs1[0])
@@ -296,20 +297,21 @@ def example_plot(ax, fontsize=12, nodec=False):
 example_plot(ax2)
 
 ###############################################################################
-# More complicated gridspec layouts are possible...
+# More complicated gridspec layouts are possible.  Note here we use the
+# convenenience functions ``add_gridspec`` and ``subgridspec``
 
-fig = plt.figure(constrained_layout=True)
+fig = plt.figure()
 
-gs0 = gridspec.GridSpec(1, 2, figure=fig)
+gs0 = fig.add_gridspec(1, 2)
 
-gs1 = gridspec.GridSpecFromSubplotSpec(2, 1, gs0[0])
+gs1 = gs0[0].subgridspec(2, 1)
 ax1 = fig.add_subplot(gs1[0])
 ax2 = fig.add_subplot(gs1[1])
 
 example_plot(ax1)
 example_plot(ax2)
 
-gs2 = gridspec.GridSpecFromSubplotSpec(3, 1, gs0[1])
+gs2 = gs0[1].subgridspec(3, 1)
 
 for ss in gs2:
     ax = fig.add_subplot(ss)
@@ -324,9 +326,9 @@ def example_plot(ax, fontsize=12, nodec=False):
 # extent.  If we want the top and bottom of the two grids to line up then
 # they need to be in the same gridspec:
 
-fig = plt.figure(constrained_layout=True)
+fig = plt.figure()
 
-gs0 = gridspec.GridSpec(6, 2, figure=fig)
+gs0 = fig.add_gridspec(6, 2)
 
 ax1 = fig.add_subplot(gs0[:3, 0])
 ax2 = fig.add_subplot(gs0[3:, 0])
@@ -349,10 +351,10 @@ def example_plot(ax, fontsize=12, nodec=False):
 
 
 def docomplicated(suptitle=None):
-    fig = plt.figure(constrained_layout=True)
-    gs0 = gridspec.GridSpec(1, 2, figure=fig, width_ratios=[1., 2.])
-    gsl = gridspec.GridSpecFromSubplotSpec(2, 1, gs0[0])
-    gsr = gridspec.GridSpecFromSubplotSpec(2, 2, gs0[1])
+    fig = plt.figure()
+    gs0 = fig.add_gridspec(1, 2, figure=fig, width_ratios=[1., 2.])
+    gsl = gs0[0].subgridspec(2, 1)
+    gsr = gs0[1].subgridspec(2, 2)
 
     for gs in gsl:
         ax = fig.add_subplot(gs)
@@ -381,7 +383,7 @@ def docomplicated(suptitle=None):
 # effect on it anymore.  (Note that constrained_layout still leaves the space
 # for the axes that is moved).
 
-fig, axs = plt.subplots(1, 2, constrained_layout=True)
+fig, axs = plt.subplots(1, 2)
 example_plot(axs[0], fontsize=12)
 axs[1].set_position([0.2, 0.2, 0.4, 0.4])
 
@@ -395,7 +397,7 @@ def docomplicated(suptitle=None):
 
 from matplotlib.transforms import Bbox
 
-fig, axs = plt.subplots(1, 2, constrained_layout=True)
+fig, axs = plt.subplots(1, 2)
 example_plot(axs[0], fontsize=12)
 fig.execute_constrained_layout()
 # put into data-space:
@@ -419,7 +421,7 @@ def docomplicated(suptitle=None):
 # to yield a nice layout:
 
 
-fig = plt.figure(constrained_layout=True)
+fig = plt.figure()
 
 ax1 = plt.subplot(221)
 ax2 = plt.subplot(223)
@@ -432,8 +434,8 @@ def docomplicated(suptitle=None):
 ###############################################################################
 # Of course that layout is possible using a gridspec:
 
-fig = plt.figure(constrained_layout=True)
-gs = gridspec.GridSpec(2, 2, figure=fig)
+fig = plt.figure()
+gs = fig.add_gridspec(2, 2)
 
 ax1 = fig.add_subplot(gs[0, 0])
 ax2 = fig.add_subplot(gs[1, 0])
@@ -448,7 +450,7 @@ def docomplicated(suptitle=None):
 # :func:`~matplotlib.pyplot.subplot2grid` doesn't work for the same reason:
 # each call creates a different parent gridspec.
 
-fig = plt.figure(constrained_layout=True)
+fig = plt.figure()
 
 ax1 = plt.subplot2grid((3, 3), (0, 0))
 ax2 = plt.subplot2grid((3, 3), (0, 1), colspan=2)
@@ -464,8 +466,8 @@ def docomplicated(suptitle=None):
 # The way to make this plot compatible with ``constrained_layout`` is again
 # to use ``gridspec`` directly
 
-fig = plt.figure(constrained_layout=True)
-gs = gridspec.GridSpec(3, 3, figure=fig)
+fig = plt.figure()
+gs = fig.add_gridspec(3, 3)
 
 ax1 = fig.add_subplot(gs[0, 0])
 ax2 = fig.add_subplot(gs[0, 1:])
 
@@ -35,7 +35,7 @@
 # Basic Quickstart Guide
 # ======================
 #
-# These first two examples show how to create a basic 4-by-4 grid using
+# These first two examples show how to create a basic 2-by-2 grid using
 # both :func:`~matplotlib.pyplot.subplots` and :mod:`~matplotlib.gridspec`.
 #
 # Using :func:`~matplotlib.pyplot.subplots` is quite simple.
@@ -55,7 +55,7 @@
 # numpy arrays.
 
 fig2 = plt.figure()
-spec2 = fig2.add_gridspec(ncols=2, nrows=2)
+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])
@@ -68,21 +68,25 @@
 # The method shown here initializes a uniform grid specification,
 # and then uses typical numpy indexing and slices to allocate multiple
 # "cells" for a given subplot.
+#
+# Note that we have also used the convenience method `.Figure.add_grisdpec`
+# instead of `.gridspec.GridSpec`, potentially saving the user an import,
+# and keeping the namespace cleaner.
 
 fig3 = plt.figure()
 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)
+ax1 = fig3.add_subplot(spec3[0, 0])
+ax1.annotate('GridSpec[0, 0]', **anno_opts)
+ax1.set_ylabel('Ylab')
 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.canvas.draw()  # Sometime constrained_layout needs an extra draw...
-fig3.show()
 
 ############################################################################
-# Other option is to use the ``width_ratios`` and ``height_ratios``
+# Another option is to use the ``width_ratios`` and ``height_ratios``
 # parameters. These keyword arguments are lists of numbers.
 # Note that absolute values are meaningless, only their relative ratios
 # matter. That means that ``width_ratios=[2, 4, 8]`` is equivalent to
@@ -123,33 +127,35 @@
 # =====================================
 #
 # When a GridSpec is explicitly used, you can adjust the layout
-# parameters of subplots that are created from the GridSpec.
+# parameters of subplots that are created from the GridSpec.  Note this
+# option is not compatible with ``constrained_layout`` or
+# `.Figure.tight_layout` which both adjust subplot sizes to fill the
+# figure.
 
-fig6 = plt.figure()
+fig6 = plt.figure(constrained_layout=False)
 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(constrained_layout=False)
-gs1 = fig.add_gridspec(nrows=3, ncols=3, left=0.05, right=0.48,
+fig7 = plt.figure(constrained_layout=False)
+gs1 = fig7.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])
+ax1 = fig7.add_subplot(gs1[:-1, :])
+ax2 = fig7.add_subplot(gs1[-1, :-1])
+ax3 = fig7.add_subplot(gs1[-1, -1])
 
-gs2 = fig.add_gridspec(nrows=3, ncols=3, left=0.55, right=0.98,
+gs2 = fig7.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])
+ax4 = fig7.add_subplot(gs2[:, :-1])
+ax5 = fig7.add_subplot(gs2[:-1, -1])
+ax6 = fig7.add_subplot(gs2[-1, -1])
 
 
 ###############################################################################
@@ -159,6 +165,9 @@
 # You can create GridSpec from the :class:`~matplotlib.gridspec.SubplotSpec`,
 # in which case its layout parameters are set to that of the location of
 # the given SubplotSpec.
+#
+# Note this is also available from the more verbose
+# `.gridspec.GridSpecFromSubplotSpec`.
 
 fig = plt.figure()
 gs0 = fig.add_gridspec(1, 2)