Add SubplotSpec.add_subplot.

anntzer · anntzer · commit eb3dd25d7fb6 · 2019-01-24T20:55:48.000+01:00
Now that the preferred(?) method of creating GridSpecs attaches the
GridSpec to a given figure (figure.add_gridspec), calling
`fig.add_subplot(gs[...])` effectively specifies the figure information
twice.  Hence, allow one to do
```
gs = fig.add_gridspec(2, 2)
gs[0, 0].add_subplot()
```
as a synonym for
```
gs = fig.add_gridspec(2, 2)
fig.add_subplot(gs[0, 0])
```

Ideally, this should ultimately allow one to deprecate the somewhat
unwieldy subplot2grid, replacing
```
plt.subplot2grid((3, 3), (0, 0))
plt.subplot2grid((3, 3), (1, 1), rowspan=2, colspan=2)
```
by
```
plt.figure().add_grispec(3, 3)[0, 0].add_subplot()
plt.figure().add_grispec(3, 3)[1:, 1:].add_subplot()
```
or, after implementing a plt.add_gridspec() that operates on gcf(),
```
gs = plt.add_gridspec(3, 3)
gs[0, 0].add_subplot()
gs[1:, 1:].add_subplot()
```

A similar API change would be to make GridSpec.tight_layout() lose its
`figure` argument (or rather, it could become optional).
diff --git a/doc/users/next_whats_new/2018-01-24-AL-subplotspec-add_subplot.rst b/doc/users/next_whats_new/2018-01-24-AL-subplotspec-add_subplot.rst
@@ -0,0 +1,8 @@
+GridSpec items can now add subplots to their parent Figure directly
+```````````````````````````````````````````````````````````````````
+
+`SubplotSpec` gained an ``add_subplot`` method, which allows one to write ::
+
+   fig = plt.figure()
+   gs = fig.add_gridspec(2, 2)
+   gs[0, 0].add_subplot()  # instead of `fig.add_subplot(gs[0, 0])`
diff --git a/lib/matplotlib/gridspec.py b/lib/matplotlib/gridspec.py
@@ -371,6 +371,10 @@ def __init__(self, nrows, ncols,
                     name=subspeclb.name + '.gridspec' + layoutbox.seq_id(),
                     artist=self)
 
+    @property
+    def figure(self):
+        return self.get_topmost_subplotspec().gridspec.figure
+
     def get_subplot_params(self, figure=None):
         """Return a dictionary of subplot layout parameters.
         """
@@ -542,3 +546,23 @@ def subgridspec(self, nrows, ncols, **kwargs):
         """
 
         return GridSpecFromSubplotSpec(nrows, ncols, self, **kwargs)
+
+    def add_subplot(self, **kwargs):
+        """
+        Add the subplot specified by *self* to the parent figure.
+
+        Note that the parent `GridSpec` must have its ``.parent`` attribute set
+        for this method to work; otherwise, a ValueError is raised.
+
+        Keyword arguments are forwarded to `Figure.add_subplot`.
+
+        Example
+        -------
+
+            gs = plt.figure().add_gridspec(2, 2)
+            ax = gs[0, 0].add_subplot()
+        """
+        if self._gridspec.figure is None:
+            raise ValueError("add_subplot() only works for GridSpecs created "
+                             "with a parent Figure")
+        self._gridspec.figure.add_subplot(self, **kwargs)
diff --git a/lib/matplotlib/tests/test_tightlayout.py b/lib/matplotlib/tests/test_tightlayout.py
@@ -107,10 +107,10 @@ def test_tight_layout6():
 
         gs1.tight_layout(fig, rect=[0, 0, 0.5, 1])
 
-        gs2 = gridspec.GridSpec(3, 1)
+        gs2 = fig.add_gridspec(3, 1)
 
         for ss in gs2:
-            ax = fig.add_subplot(ss)
+            ax = ss.add_subplot()
             example_plot(ax)
             ax.set_title("")
             ax.set_xlabel("")
diff --git a/tutorials/intermediate/gridspec.py b/tutorials/intermediate/gridspec.py
@@ -49,18 +49,17 @@
 # For a simple use case such as this, :mod:`~matplotlib.gridspec` is
 # perhaps overly verbose.
 # You have to create the figure and :class:`~matplotlib.gridspec.GridSpec`
-# instance separately, then pass elements of gridspec instance to the
-# :func:`~matplotlib.figure.Figure.add_subplot` method to create the axes
-# objects.
+# instance separately, then call the `~SubplotSpec.add_subplot` method of
+# elements of gridspec instance to create the axes objects.
 # The elements of the gridspec are accessed in generally the same manner as
 # numpy arrays.
 
 fig2 = plt.figure(constrained_layout=True)
 spec2 = gridspec.GridSpec(ncols=2, nrows=2, figure=fig2)
-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])
+f2_ax1 = spec2[0, 0].add_subplot()
+f2_ax2 = spec2[0, 1].add_subplot()
+f2_ax3 = spec2[1, 0].add_subplot()
+f2_ax4 = spec2[1, 1].add_subplot()
 
 #############################################################################
 # The power of gridspec comes in being able to create subplots that span
@@ -74,15 +73,15 @@
 
 fig3 = plt.figure(constrained_layout=True)
 gs = fig3.add_gridspec(3, 3)
-f3_ax1 = fig3.add_subplot(gs[0, :])
+f3_ax1 = gs[0, :].add_subplot()
 f3_ax1.set_title('gs[0, :]')
-f3_ax2 = fig3.add_subplot(gs[1, :-1])
+f3_ax2 = gs[1, :-1].add_subplot()
 f3_ax2.set_title('gs[1, :-1]')
-f3_ax3 = fig3.add_subplot(gs[1:, -1])
+f3_ax3 = gs[1:, -1].add_subplot()
 f3_ax3.set_title('gs[1:, -1]')
-f3_ax4 = fig3.add_subplot(gs[-1, 0])
+f3_ax4 = gs[-1, 0].add_subplot()
 f3_ax4.set_title('gs[-1, 0]')
-f3_ax5 = fig3.add_subplot(gs[-1, -2])
+f3_ax5 = gs[-1, -2].add_subplot()
 f3_ax5.set_title('gs[-1, -2]')
 
 #############################################################################
@@ -99,11 +98,11 @@
 anno_opts = dict(xy=(0.5, 0.5), xycoords='axes fraction',
                  va='center', ha='center')
 
-f4_ax1 = fig4.add_subplot(spec4[0, 0])
+f4_ax1 = spec4[0, 0].add_subplot()
 f4_ax1.annotate('GridSpec[0, 0]', **anno_opts)
-fig4.add_subplot(spec4[0, 1]).annotate('GridSpec[0, 1:]', **anno_opts)
-fig4.add_subplot(spec4[1, 0]).annotate('GridSpec[1:, 0]', **anno_opts)
-fig4.add_subplot(spec4[1, 1]).annotate('GridSpec[1:, 1:]', **anno_opts)
+spec4[0, 1].add_subplot().annotate('GridSpec[0, 1:]', **anno_opts)
+spec4[1, 0].add_subplot().annotate('GridSpec[1:, 0]', **anno_opts)
+spec4[1, 1].add_subplot().annotate('GridSpec[1:, 1:]', **anno_opts)
 
 ############################################################################
 # Another option is to use the ``width_ratios`` and ``height_ratios``
@@ -121,7 +120,7 @@
                           height_ratios=heights)
 for row in range(3):
     for col in range(3):
-        ax = fig5.add_subplot(spec5[row, col])
+        ax = spec5[row, col].add_subplot()
         label = 'Width: {}\nHeight: {}'.format(widths[col], heights[row])
         ax.annotate(label, (0.1, 0.5), xycoords='axes fraction', va='center')
 
@@ -154,7 +153,7 @@
 # remove the underlying axes
 for ax in f7_axs[1:, -1]:
     ax.remove()
-axbig = fig7.add_subplot(gs[1:, -1])
+axbig = gs[1:, -1].add_subplot()
 axbig.annotate('Big Axes \nGridSpec[1:, -1]', (0.1, 0.5),
                xycoords='axes fraction', va='center')
 
@@ -172,9 +171,9 @@
 
 fig8 = plt.figure(constrained_layout=False)
 gs1 = fig8.add_gridspec(nrows=3, ncols=3, left=0.05, right=0.48, wspace=0.05)
-f8_ax1 = fig8.add_subplot(gs1[:-1, :])
-f8_ax2 = fig8.add_subplot(gs1[-1, :-1])
-f8_ax3 = fig8.add_subplot(gs1[-1, -1])
+f8_ax1 = gs1[:-1, :].add_subplot()
+f8_ax2 = gs1[-1, :-1].add_subplot()
+f8_ax3 = gs1[-1, -1].add_subplot()
 
 ###############################################################################
 # This is similar to :func:`~matplotlib.pyplot.subplots_adjust`, but it only
@@ -185,15 +184,15 @@
 fig9 = plt.figure(constrained_layout=False)
 gs1 = fig9.add_gridspec(nrows=3, ncols=3, left=0.05, right=0.48,
                         wspace=0.05)
-f9_ax1 = fig9.add_subplot(gs1[:-1, :])
-f9_ax2 = fig9.add_subplot(gs1[-1, :-1])
-f9_ax3 = fig9.add_subplot(gs1[-1, -1])
+f9_ax1 = gs1[:-1, :].add_subplot()
+f9_ax2 = gs1[-1, :-1].add_subplot()
+f9_ax3 = gs1[-1, -1].add_subplot()
 
 gs2 = fig9.add_gridspec(nrows=3, ncols=3, left=0.55, right=0.98,
                         hspace=0.05)
-f9_ax4 = fig9.add_subplot(gs2[:, :-1])
-f9_ax5 = fig9.add_subplot(gs2[:-1, -1])
-f9_ax6 = fig9.add_subplot(gs2[-1, -1])
+f9_ax4 = gs2[:, :-1].add_subplot()
+f9_ax5 = gs2[:-1, -1].add_subplot()
+f9_ax6 = gs2[-1, -1].add_subplot()
 
 ###############################################################################
 # GridSpec using SubplotSpec
@@ -214,8 +213,8 @@
 
 for a in range(2):
     for b in range(3):
-        fig10.add_subplot(gs00[a, b])
-        fig10.add_subplot(gs01[b, a])
+        gs00[a, b].add_subplot()
+        gs01[b, a].add_subplot()
 
 ###############################################################################
 # A Complex Nested GridSpec using SubplotSpec
@@ -276,7 +275,7 @@ def squiggle_xy(a, b, c, d, i=np.arange(0.0, 2*np.pi, 0.05)):
 
 matplotlib.pyplot.subplots
 matplotlib.figure.Figure.add_gridspec
-matplotlib.figure.Figure.add_subplot
 matplotlib.gridspec.GridSpec
+matplotlib.gridspec.SubplotSpec.add_subplot
 matplotlib.gridspec.SubplotSpec.subgridspec
 matplotlib.gridspec.GridSpecFromSubplotSpec
