FIX: rename subfigure

jklymak · jklymak · commit 9f6e0e65b481 · 2020-09-21T15:58:21.000-07:00
diff --git a/examples/subplots_axes_and_figures/gridspec_nested.py b/examples/subplots_axes_and_figures/gridspec_nested.py
@@ -7,7 +7,7 @@
 set the position for a nested grid of subplots.
 
 Note that the same functionality can be achieved more directly with
-`~.figure.PanelBase.subpanels`:
+`~.figure.FigureBase.subfigures`:
 :doc:`nested gridspecs</gallery/subplots_axes_and_figures/subpanels>`,
 
 """
diff --git a/examples/subplots_axes_and_figures/subpanels.py b/examples/subplots_axes_and_figures/subpanels.py
@@ -1,20 +1,20 @@
 """
-================
-Figure subpanels
-================
+=================
+Figure subfigures
+=================
 
 Sometimes it is desirable to have a figure with two different layouts in it.
 This can be achieved with
 :doc:`nested gridspecs</gallery/subplots_axes_and_figures/gridspec_nested>`,
 but having a virtual figure with its own artists is helpful, so
-Matplotlib also has "subpanels", accessed by calling
-`matplotlib.figure.Figure.add_subpanel` in a way that is analagous to
-`matplotlib.figure.Figure.add_subplot`, or `matplotlib.figure.Figure.subpanels`
-to make an array of subpanels.  Note that subpanels can also have their own
-child subpanels.
+Matplotlib also has "subfigures", accessed by calling
+`matplotlib.figure.Figure.add_subfigure` in a way that is analagous to
+`matplotlib.figure.Figure.add_subplot`, or
+`matplotlib.figure.Figure.subfigures` to make an array of subfigures.  Note
+that subfigures can also have their own child subfigures.
 
 .. note::
-    ``subpanel`` is new in v3.4, and the API is still provisional.
+    ``subfigure`` is new in v3.4, and the API is still provisional.
 
 """
 import matplotlib.pyplot as plt
@@ -32,25 +32,25 @@ def example_plot(ax, fontsize=12, hide_labels=False):
 
 # gridspec inside gridspec
 fig = plt.figure(constrained_layout=True, figsize=(10, 4))
-subpanels = fig.subpanels(1, 2, wspace=0.07)
+subfigs = fig.subfigures(1, 2, wspace=0.07)
 
-axsLeft = subpanels[0].subplots(1, 2, sharey=True)
-subpanels[0].set_facecolor('0.75')
+axsLeft = subfigs[0].subplots(1, 2, sharey=True)
+subfigs[0].set_facecolor('0.75')
 for ax in axsLeft:
     pc = example_plot(ax)
-subpanels[0].suptitle('Left plots', fontsize='x-large')
-subpanels[0].colorbar(pc, shrink=0.6, ax=axsLeft, location='bottom')
+subfigs[0].suptitle('Left plots', fontsize='x-large')
+subfigs[0].colorbar(pc, shrink=0.6, ax=axsLeft, location='bottom')
 
-axsRight = subpanels[1].subplots(3, 1, sharex=True)
+axsRight = subfigs[1].subplots(3, 1, sharex=True)
 for nn, ax in enumerate(axsRight):
     pc = example_plot(ax, hide_labels=True)
     if nn == 2:
         ax.set_xlabel('xlabel')
     if nn == 1:
         ax.set_ylabel('ylabel')
-subpanels[1].set_facecolor('0.85')
-subpanels[1].colorbar(pc, shrink=0.6, ax=axsRight)
-subpanels[1].suptitle('Right plots', fontsize='x-large')
+subfigs[1].set_facecolor('0.85')
+subfigs[1].colorbar(pc, shrink=0.6, ax=axsRight)
+subfigs[1].suptitle('Right plots', fontsize='x-large')
 
 fig.suptitle('Figure suptitle', fontsize='xx-large')
 
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -3,11 +3,11 @@
 
 `Figure`
     Top level `~matplotlib.artist.Artist`, which holds all plot elements.
-    Many methods are implimented in `PanelBase`.
+    Many methods are implimented in `FigureBase`.
 
-`SubPanel`
+`SubFigure`
     A logical figure inside a figure, usually added to a figure (or parent
-    `SubPanel`) with `Figure.add_subpanel` or `Figure.subpanels` methods
+    `SubFigure`) with `Figure.add_subfigure` or `Figure.subfigures` methods
     (provisional API v3.4).
 
 `SubplotParams`
@@ -219,9 +219,9 @@ def update(self, left=None, bottom=None, right=None, top=None,
             self.hspace = hspace
 
 
-class PanelBase(Artist):
+class FigureBase(Artist):
     """
-    Base class for `.figure.Figure` and `.figure.SubPanel` containing the
+    Base class for `.figure.Figure` and `.figure.SubFigure` containing the
     methods that add artists to the figure or panel, create axes, etc.
     """
     def __init__(self):
@@ -1408,26 +1408,26 @@ def add_gridspec(self, nrows=1, ncols=1, **kwargs):
         self._gridspecs.append(gs)
         return gs
 
-    def subpanels(self, nrows=1, ncols=1, squeeze=True,
+    def subfigures(self, nrows=1, ncols=1, squeeze=True,
                   wspace=None, hspace=None,
                   width_ratios=None, height_ratios=None,
                   **kwargs):
         """
-        Add a subpanel to this figure or subpanel.  A subpanel has the same
+        Add a subfigure to this figure or subfigure.  A subfigure has the same
         artist methods as a figure, and is logically the same as a figure.
 
         Parameters
         ----------
         nrows, ncols : int, default: 1
-            Number of rows/columns of the subpanel grid.
+            Number of rows/columns of the subfigure grid.
 
         squeeze : boolean, default: True
             If True, extra dimensions are squeezed out from the returned
-            array of subpanels.
+            array of subfigures.
 
         wspace, hspace : float, default: None
-            The amount of width/height reserved for space between subpanels,
-            expressed as a fraction of the average subpanel width.
+            The amount of width/height reserved for space between subfigures,
+            expressed as a fraction of the average subfigure width.
             If not given, the values will be inferred from a figure or
             rcParams when necessary.
 
@@ -1449,20 +1449,20 @@ def subpanels(self, nrows=1, ncols=1, squeeze=True,
         sfarr = np.empty((nrows, ncols), dtype=object)
         for i in range(ncols):
             for j in range(nrows):
-                sfarr[j, i] = self.add_subpanel(gs[j, i], **kwargs)
+                sfarr[j, i] = self.add_subfigure(gs[j, i], **kwargs)
 
         if squeeze:
             # Discarding unneeded dimensions that equal 1.  If we only have one
-            # subpanel, just return it instead of a 1-element array.
+            # subfigure, just return it instead of a 1-element array.
             return sfarr.item() if sfarr.size == 1 else sfarr.squeeze()
         else:
             # Returned axis array will be always 2-d, even if nrows=ncols=1.
             return sfarr
 
         return sfarr
 
-    def add_subpanel(self, subplotspec, **kwargs):
-        sf = SubPanel(subplotspec, self, **kwargs)
+    def add_subfigure(self, subplotspec, **kwargs):
+        sf = SubFigure(subplotspec, self, **kwargs)
         self.panels += [sf]
         return sf
 
@@ -1887,21 +1887,21 @@ def _set_artist_props(self, a):
         a.set_transform(self.transPanel)
 
 
-class SubPanel(PanelBase):
+class SubFigure(FigureBase):
     """
-    Logical panel that can be placed in a figure typically using
-    `.Figure.add_subpanel` or `.SubPanel.add_subpanel`, or
-    `.SubPanel.subpanels`.  A panel has the same methods as a figure
+    Logical figure that can be placed inside a figure typically using
+    `.Figure.add_subfigure` or `.SubFigure.add_subfigure`, or
+    `.SubFigure.subfigures`.  A panel has the same methods as a figure
     except for those particularly tied to the size or dpi of the figure, and
     is confined to a prescribed region of the figure.  For example the
-    following puts two subpanels side-by-side::
+    following puts two subfigures side-by-side::
 
         fig = plt.figure()
-        spanels = fig.subpanels(1, 2)
-        axsL = spanels[0].subplots(1, 2)
-        axsR = spanels[0].subplots(2, 1)
+        sfigs = fig.subfigures(1, 2)
+        axsL = sfigs[0].subplots(1, 2)
+        axsR = sfigs[0].subplots(2, 1)
 
-    See :doc:`/gallery/subplots_axes_and_figures/subpanels`
+    See :doc:`/gallery/subplots_axes_and_figures/subfigures`
     """
 
     def __init__(self, subplotspec, parent, *,
@@ -1913,11 +1913,11 @@ def __init__(self, subplotspec, parent, *,
         Parameters
         ----------
         subplotspec : `.gridspec.SubplotSpec`
-            defines the region in a parent gridspec where the subpanel will
+            defines the region in a parent gridspec where the subfigure will
             be placed
 
-        parent : `.figure.Figure` or `.figure.SubPanel`
-            Figure or subpanel that contains the SubPanel.  SubPanels
+        parent : `.figure.Figure` or `.figure.SubFigure`
+            Figure or subfigure that contains the SubFigure.  SubFigures
             can be nested.
 
         facecolor : default: :rc:`figure.facecolor`
@@ -1945,7 +1945,7 @@ def __init__(self, subplotspec, parent, *,
         self._subplotspec = subplotspec
         self._parent = parent
         self.figure = parent.figure
-        # subpanels use the parent axstack
+        # subfigures use the parent axstack
         self._axstack = parent._axstack
         self.subplotpars = parent.subplotpars
         self.dpi_scale_trans = parent.dpi_scale_trans
@@ -2040,7 +2040,7 @@ def init_layoutgrid(self):
 
     def get_axes(self):
         """
-        Return a list of axes in the SubPanel. You can access and modify the
+        Return a list of axes in the SubFigure. You can access and modify the
         axes in the Figure through this list.
         """
         return self._localaxes.as_list()
@@ -2049,8 +2049,8 @@ def get_axes(self):
         List of axes in the Figure.  You can access and modify the axes
         in the Figure through this list.
 
-        Do not modify the list itself. Instead, use "`~.SubPanel.add_axes`,
-        `~.SubPanel.add_subplot` or `~.SubPanel.delaxes` to add or remove an
+        Do not modify the list itself. Instead, use "`~.SubFigure.add_axes`,
+        `~.SubFigure.add_subplot` or `~.SubFigure.delaxes` to add or remove an
         axes.
         """)
 
@@ -2074,7 +2074,7 @@ def draw(self, renderer):
             self.stale = False
 
 
-class Figure(PanelBase):
+class Figure(FigureBase):
     """
     The top level container for all the plot elements.
 
@@ -2215,7 +2215,7 @@ def __init__(self,
         self._cachedRenderer = None
 
         self.set_constrained_layout(constrained_layout)
-        # stub for subpanels:
+        # stub for subfigures:
         self.panels = []
 
         # groupers to keep track of x and y labels we want to align.
diff --git a/lib/matplotlib/tests/baseline_images/test_figure/test_subfigure.png b/lib/matplotlib/tests/baseline_images/test_figure/test_subfigure.png
diff --git a/lib/matplotlib/tests/baseline_images/test_figure/test_subfigure_ss.png b/lib/matplotlib/tests/baseline_images/test_figure/test_subfigure_ss.png
diff --git a/lib/matplotlib/tests/test_figure.py b/lib/matplotlib/tests/test_figure.py
@@ -799,13 +799,13 @@ def test_reused_gridspec():
     assert gs1 == gs3
 
 
-@image_comparison(['test_subpanel.png'], style='mpl20',
+@image_comparison(['test_subfigure.png'], style='mpl20',
                   savefig_kwarg={'facecolor': 'teal'},
                   remove_text=False)
-def test_subpanel():
+def test_subfigure():
     np.random.seed(19680808)
     fig = plt.figure(constrained_layout=True)
-    sub = fig.subpanels(1, 2)
+    sub = fig.subfigures(1, 2)
 
     axs = sub[0].subplots(2, 2)
     for ax in axs.flat:
@@ -822,15 +822,15 @@ def test_subpanel():
     fig.suptitle('Figure suptitle', fontsize='xx-large')
 
 
-@image_comparison(['test_subpanel_ss.png'], style='mpl20',
+@image_comparison(['test_subfigure_ss.png'], style='mpl20',
                   savefig_kwarg={'facecolor': 'teal'},
                   remove_text=False)
-def test_subpanel_ss():
+def test_subfigure_ss():
     np.random.seed(19680808)
     fig = plt.figure(constrained_layout=True)
     gs = fig.add_gridspec(1, 2)
 
-    sub = fig.add_subpanel(gs[0], facecolor='pink')
+    sub = fig.add_subfigure(gs[0], facecolor='pink')
 
     axs = sub.subplots(2, 2)
     for ax in axs.flat:
diff --git a/tutorials/advanced/transforms_tutorial.py b/tutorials/advanced/transforms_tutorial.py
@@ -29,11 +29,11 @@
 |                |                             |is bottom left of the axes, and    |
 |                |                             |(1, 1) is top right of the axes.   |
 +----------------+-----------------------------+-----------------------------------+
-|"subpanel"      |``subpanel.transPanel``      |The coordinate system of the       |
-|                |                             |`.SubPanel`; (0, 0) is bottom left |
-|                |                             |of the subpanel, and (1, 1) is top |
-|                |                             |right of the subpanel.  If a       |
-|                |                             |figure has no subpanels, this is   |
+|"subfigure"     |``subfigure.transPanel``     |The coordinate system of the       |
+|                |                             |`.SubFigure`; (0, 0) is bottom left|
+|                |                             |of the subfigure, and (1, 1) is top|
+|                |                             |right of the subfigure.  If a      |
+|                |                             |figure has no subfigures, this is  |
 |                |                             |the same as ``transFigure``.       |
 +----------------+-----------------------------+-----------------------------------+
 |"figure"        |``fig.transFigure``          |The coordinate system of the       |
