Add GridSpec.subplots()

anntzer · anntzer · commit 484527e7f675 · 2019-06-03T09:52:15.000+02:00
so that one can separately pass `gridspec_kw` directly to the gridspec
constructor.
diff --git a/doc/users/next_whats_new/2019-06-01-AL.rst b/doc/users/next_whats_new/2019-06-01-AL.rst
@@ -0,0 +1,11 @@
+GridSpec.subplots()
+```````````````````
+
+The `GridSpec` class gained a `~.GridSpec.subplots` method, so that one can
+write ::
+
+    fig.add_gridspec(2, 2, height_ratios=[3, 1]).subplots()
+
+as an alternative to ::
+
+    fig.subplots(2, 2, gridspec_kw={"height_ratios": [3, 1]})
diff --git a/examples/lines_bars_and_markers/linestyles.py b/examples/lines_bars_and_markers/linestyles.py
@@ -66,8 +66,9 @@ def plot_linestyles(ax, linestyles, title):
                     color="blue", fontsize=8, ha="right", family="monospace")
 
 
-fig, (ax0, ax1) = plt.subplots(2, 1, gridspec_kw={'height_ratios': [1, 3]},
-                               figsize=(10, 8))
+ax0, ax1 = (plt.figure(figsize=(10, 8))
+            .add_gridspec(2, 1, height_ratios=[1, 3])
+            .subplots())
 
 plot_linestyles(ax0, linestyle_str[::-1], title='Named linestyles')
 plot_linestyles(ax1, linestyle_tuple[::-1], title='Parametrized linestyles')
diff --git a/examples/subplots_axes_and_figures/subplots_demo.py b/examples/subplots_axes_and_figures/subplots_demo.py
@@ -143,14 +143,16 @@
 # labels of inner Axes are automatically removed by *sharex* and *sharey*.
 # Still there remains an unused empty space between the subplots.
 #
-# The parameter *gridspec_kw* of `.pyplot.subplots` controls the grid
-# properties (see also `.GridSpec`). For example, we can reduce the height
-# between vertical subplots using ``gridspec_kw={'hspace': 0}``.
+# To precisely control the positioning of the subplots, one can explicitly
+# create a `.GridSpec` with `.add_gridspec`, and then call its
+# `~.GridSpec.subplots` method.  For example, we can reduce the height
+# between vertical subplots using ``add_gridspec(hspace=0)``.
 #
 # `.label_outer` is a handy method to remove labels and ticks from subplots
 # that are not at the edge of the grid.
 
-fig, axs = plt.subplots(3, sharex=True, sharey=True, gridspec_kw={'hspace': 0})
+fig = plt.figure()
+axs = fig.add_gridspec(3, hspace=0).subplots(sharex=True, sharey=True)
 fig.suptitle('Sharing both axes')
 axs[0].plot(x, y ** 2)
 axs[1].plot(x, 0.3 * y, 'o')
@@ -164,8 +166,9 @@
 # Apart from ``True`` and ``False``, both *sharex* and *sharey* accept the
 # values 'row' and 'col' to share the values only per row or column.
 
-fig, axs = plt.subplots(2, 2, sharex='col', sharey='row',
-                        gridspec_kw={'hspace': 0, 'wspace': 0})
+fig = plt.figure()
+axs = (fig.add_gridspec(2, 2, hspace=0, wspace=0)
+       .subplots(sharex='col', sharey='row'))
 (ax1, ax2), (ax3, ax4) = axs
 fig.suptitle('Sharing x per column, y per row')
 ax1.plot(x, y)
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1532,68 +1532,11 @@ def subplots(self, nrows=1, ncols=1, sharex=False, sharey=False,
         .Figure.add_subplot
         .pyplot.subplot
         """
-
-        if isinstance(sharex, bool):
-            sharex = "all" if sharex else "none"
-        if isinstance(sharey, bool):
-            sharey = "all" if sharey else "none"
-        # This check was added because it is very easy to type
-        # `subplots(1, 2, 1)` when `subplot(1, 2, 1)` was intended.
-        # In most cases, no error will ever occur, but mysterious behavior
-        # will result because what was intended to be the subplot index is
-        # instead treated as a bool for sharex.
-        if isinstance(sharex, Integral):
-            cbook._warn_external(
-                "sharex argument to subplots() was an integer.  Did you "
-                "intend to use subplot() (without 's')?")
-        cbook._check_in_list(["all", "row", "col", "none"],
-                             sharex=sharex, sharey=sharey)
-        if subplot_kw is None:
-            subplot_kw = {}
         if gridspec_kw is None:
             gridspec_kw = {}
-        # don't mutate kwargs passed by user...
-        subplot_kw = subplot_kw.copy()
-        gridspec_kw = gridspec_kw.copy()
-
-        if self.get_constrained_layout():
-            gs = GridSpec(nrows, ncols, figure=self, **gridspec_kw)
-        else:
-            # this should turn constrained_layout off if we don't want it
-            gs = GridSpec(nrows, ncols, figure=None, **gridspec_kw)
-        self._gridspecs.append(gs)
-
-        # Create array to hold all axes.
-        axarr = np.empty((nrows, ncols), dtype=object)
-        for row in range(nrows):
-            for col in range(ncols):
-                shared_with = {"none": None, "all": axarr[0, 0],
-                               "row": axarr[row, 0], "col": axarr[0, col]}
-                subplot_kw["sharex"] = shared_with[sharex]
-                subplot_kw["sharey"] = shared_with[sharey]
-                axarr[row, col] = self.add_subplot(gs[row, col], **subplot_kw)
-
-        # turn off redundant tick labeling
-        if sharex in ["col", "all"]:
-            # turn off all but the bottom row
-            for ax in axarr[:-1, :].flat:
-                ax.xaxis.set_tick_params(which='both',
-                                         labelbottom=False, labeltop=False)
-                ax.xaxis.offsetText.set_visible(False)
-        if sharey in ["row", "all"]:
-            # turn off all but the first column
-            for ax in axarr[:, 1:].flat:
-                ax.yaxis.set_tick_params(which='both',
-                                         labelleft=False, labelright=False)
-                ax.yaxis.offsetText.set_visible(False)
-
-        if squeeze:
-            # Discarding unneeded dimensions that equal 1.  If we only have one
-            # subplot, just return it instead of a 1-element array.
-            return axarr.item() if axarr.size == 1 else axarr.squeeze()
-        else:
-            # Returned axis array will be always 2-d, even if nrows=ncols=1.
-            return axarr
+        return (self.add_gridspec(nrows, ncols, figure=self, **gridspec_kw)
+                .subplots(sharex=sharex, sharey=sharey, squeeze=squeeze,
+                          subplot_kw=subplot_kw))
 
     def _remove_ax(self, ax):
         def _reset_loc_form(axis):
@@ -2643,17 +2586,17 @@ def align_labels(self, axs=None):
         self.align_xlabels(axs=axs)
         self.align_ylabels(axs=axs)
 
-    def add_gridspec(self, nrows, ncols, **kwargs):
+    def add_gridspec(self, nrows=1, ncols=1, **kwargs):
         """
         Return a `.GridSpec` that has this figure as a parent.  This allows
         complex layout of axes in the figure.
 
         Parameters
         ----------
-        nrows : int
+        nrows : int, default: 1
             Number of rows in grid.
 
-        ncols : int
+        ncols : int, default: 1
             Number or columns in grid.
 
         Returns
diff --git a/lib/matplotlib/gridspec.py b/lib/matplotlib/gridspec.py
@@ -15,6 +15,7 @@
 
 import copy
 import logging
+from numbers import Integral
 
 import numpy as np
 
@@ -316,6 +317,125 @@ def get_subplot_params(self, figure=None):
     def locally_modified_subplot_params(self):
         return [k for k in self._AllowedKeys if getattr(self, k)]
 
+    def subplots(self, sharex=False, sharey=False, squeeze=True,
+                 subplot_kw=None):
+        """
+        Add all subplots specified by this `GridSpec` to its parent figure.
+
+        This utility wrapper makes it convenient to create common layouts of
+        subplots in a single call.
+
+        Parameters
+        ----------
+        sharex, sharey : bool or {'none', 'all', 'row', 'col'}, default: False
+            Controls sharing of properties among x (`sharex`) or y (`sharey`)
+            axes:
+
+                - True or 'all': x- or y-axis will be shared among all
+                  subplots.
+                - False or 'none': each subplot x- or y-axis will be
+                  independent.
+                - 'row': each subplot row will share an x- or y-axis.
+                - 'col': each subplot column will share an x- or y-axis.
+
+            When subplots have a shared x-axis along a column, only the x tick
+            labels of the bottom subplot are created. Similarly, when subplots
+            have a shared y-axis along a row, only the y tick labels of the
+            first column subplot are created. To later turn other subplots'
+            ticklabels on, use `~matplotlib.axes.Axes.tick_params`.
+
+        squeeze : bool, optional, default: True
+            - If True, extra dimensions are squeezed out from the returned
+              array of Axes:
+
+                - if only one subplot is constructed (nrows=ncols=1), the
+                  resulting single Axes object is returned as a scalar.
+                - for Nx1 or 1xM subplots, the returned object is a 1D numpy
+                  object array of Axes objects.
+                - for NxM, subplots with N>1 and M>1 are returned
+                  as a 2D array.
+
+            - If False, no squeezing at all is done: the returned Axes object
+              is always a 2D array containing Axes instances, even if it ends
+              up being 1x1.
+
+        subplot_kw : dict, optional
+            Dict with keywords passed to the
+            :meth:`~matplotlib.figure.Figure.add_subplot` call used to create
+            each subplot.
+
+        Returns
+        -------
+        ax : `~.axes.Axes` object or array of Axes objects.
+            *ax* can be either a single `~matplotlib.axes.Axes` object or
+            an array of Axes objects if more than one subplot was created. The
+            dimensions of the resulting array can be controlled with the
+            squeeze keyword, see above.
+
+        See Also
+        --------
+        .pyplot.subplots
+        .Figure.add_subplot
+        .pyplot.subplot
+        """
+
+        if self.figure is None:
+            raise ValueError("GridSpec.subplots() only works for GridSpecs "
+                             "created with a parent figure")
+
+        if isinstance(sharex, bool):
+            sharex = "all" if sharex else "none"
+        if isinstance(sharey, bool):
+            sharey = "all" if sharey else "none"
+        # This check was added because it is very easy to type
+        # `subplots(1, 2, 1)` when `subplot(1, 2, 1)` was intended.
+        # In most cases, no error will ever occur, but mysterious behavior
+        # will result because what was intended to be the subplot index is
+        # instead treated as a bool for sharex.
+        if isinstance(sharex, Integral):
+            cbook._warn_external(
+                "sharex argument to subplots() was an integer.  Did you "
+                "intend to use subplot() (without 's')?")
+        cbook._check_in_list(["all", "row", "col", "none"],
+                             sharex=sharex, sharey=sharey)
+        if subplot_kw is None:
+            subplot_kw = {}
+        # don't mutate kwargs passed by user...
+        subplot_kw = subplot_kw.copy()
+
+        # Create array to hold all axes.
+        axarr = np.empty((self._nrows, self._ncols), dtype=object)
+        for row in range(self._nrows):
+            for col in range(self._ncols):
+                shared_with = {"none": None, "all": axarr[0, 0],
+                               "row": axarr[row, 0], "col": axarr[0, col]}
+                subplot_kw["sharex"] = shared_with[sharex]
+                subplot_kw["sharey"] = shared_with[sharey]
+                axarr[row, col] = self.figure.add_subplot(
+                    self[row, col], **subplot_kw)
+
+        # turn off redundant tick labeling
+        if sharex in ["col", "all"]:
+            # turn off all but the bottom row
+            for ax in axarr[:-1, :].flat:
+                ax.xaxis.set_tick_params(which='both',
+                                         labelbottom=False, labeltop=False)
+                ax.xaxis.offsetText.set_visible(False)
+        if sharey in ["row", "all"]:
+            # turn off all but the first column
+            for ax in axarr[:, 1:].flat:
+                ax.yaxis.set_tick_params(which='both',
+                                         labelleft=False, labelright=False)
+                ax.yaxis.offsetText.set_visible(False)
+
+        if squeeze:
+            # Discarding unneeded dimensions that equal 1.  If we only have one
+            # subplot, just return it instead of a 1-element array.
+            return axarr.item() if axarr.size == 1 else axarr.squeeze()
+        else:
+            # Returned axis array will be always 2-d, even if nrows=ncols=1.
+            return axarr
+
     def tight_layout(self, figure, renderer=None,
                      pad=1.08, h_pad=None, w_pad=None, rect=None):
         """
