Add SubplotSpec.add_subplot.

anntzer · anntzer · commit 164d0bb06bf3 · 2019-02-02T19:19:38.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")
+        return 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("")
