Merge pull request #6179 from paulkirow/d01f1

tacaswell · tacaswell · commit 0003470def2b · 2016-03-20T18:57:45.000-04:00
ENH: Adds targetfig parameter to the subplot2grid function closes #6105:
diff --git a/doc/users/whats_new/uptade_subplot2grid.rst b/doc/users/whats_new/uptade_subplot2grid.rst
@@ -0,0 +1,13 @@
+New Firgure Parameter for subplot2grid
+--------------------------------------
+
+A ``fig`` parameter now exists for the method :func:`subplot2grid`.  This allows
+for the figure that the subplots will be created in to be specified.  If ``fig``
+is ``None`` (default) then the method will use the current figure retrieved by
+:func:`gcf`.
+
+Example
+```````
+::
+
+    subplot2grid(shape, loc, rowspan=1, colspan=1, fig=myfig)
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -1147,11 +1147,12 @@ def subplots(nrows=1, ncols=1, sharex=False, sharey=False, squeeze=True,
     return fig, axs
 
 
-def subplot2grid(shape, loc, rowspan=1, colspan=1, **kwargs):
+def subplot2grid(shape, loc, rowspan=1, colspan=1, fig=None, **kwargs):
     """
     Create a subplot in a grid.  The grid is specified by *shape*, at
     location of *loc*, spanning *rowspan*, *colspan* cells in each
-    direction.  The index for loc is 0-based. ::
+    direction.  The index for loc is 0-based.  The current figure will
+    be used unless *fig* is specified. ::
 
       subplot2grid(shape, loc, rowspan=1, colspan=1)
 
@@ -1162,7 +1163,9 @@ def subplot2grid(shape, loc, rowspan=1, colspan=1, **kwargs):
       subplot(subplotspec)
     """
 
-    fig = gcf()
+    if fig is None:
+        fig = gcf()
+
     s1, s2 = shape
     subplotspec = GridSpec(s1, s2).new_subplotspec(loc,
                                                    rowspan=rowspan,
