DOC: changes on review

jklymak · jklymak · commit 63054c274ec9 · 2021-11-15T10:32:50.000+01:00
diff --git a/tutorials/intermediate/arranging_axes.py b/tutorials/intermediate/arranging_axes.py
@@ -1,16 +1,20 @@
 """
-==========================
-Arranging Axes in a Figure
-==========================
+===================================
+Arranging multiple Axes in a Figure
+===================================
 
 Often more than one axes is wanted on a figure at a time, and usually
 we want to organize those axes into a regular grid.  Matplotlib has a
 variety of tools for working with grids of axes that have evolved over
 the history of the library.  Here we will discuss the tools we think
-users should use most often, and then dicuss some of the older tools,
-and the tools that underpin how axes are organized.
+users should use most often, the tools that underpin how axes are organized,
+and mention some of the older tools.
 
-How to create grid-shaped combinations of axes:
+Overview
+========
+
+Create grid-shaped combinations of axes
+---------------------------------------
 
 `~matplotlib.pyplot.subplots`
     The primary function used to create figures and a grid of axes.  It is
@@ -21,19 +25,22 @@
 or
 
 `~matplotlib.pyplot.subplot_mosaic`
-    A more flexible function used to create figures and a grid of axes,
-    with the added flexibility that some of the axes can span rows or
-    columns, and that the axes are returned in a labelled dictionary instead
-    of an array.  See also `.Figure.subplot_mosaic`.
+    A simple way to create figures and a grid of axes, with the added
+    flexibility that axes can also span rows or columns. The axes
+    are returned in a labelled dictionary instead of an array.  See also
+    `.Figure.subplot_mosaic` and :doc:`/tutorials/provisional/mosaic`.
 
 Sometimes it is natural to have more than one distinct group of axes grids,
 in which case Matplotlib has the concept of `~.figure.SubFigure`:
 
 `~matplotlib.figure.SubFigure`
     A virtual figure within a figure.
 
-Underlying these is the concept of a `~.gridspec.GridSpec` and
-`~.SubplotSpec`:
+Underlying tools
+----------------
+
+Underlying these are the concept of a `~.gridspec.GridSpec` and
+a `~.SubplotSpec`:
 
 `~matplotlib.gridspec.GridSpec`
     Specifies the geometry of the grid that a subplot will be
@@ -44,12 +51,21 @@
 `~matplotlib.gridspec.SubplotSpec`
     Specifies the location of the subplot in the given `.GridSpec`.
 
-An older way to add axes in grids:
+Adding single axes at a time
+----------------------------
+
+Many tutorials and resources on the web add axes one at a time.  We do not
+cover that usage here in detail, as it is generally less elegant and flexible,
+though sometimes useful for interactive work.
+
+`~matplotlib.pyplot.subplot` or `.Figure.add_subplot`
+    Adds a single subplot on a figure, with 1-based indexing (inherited from
+    Matlab).  Columns and rows can be spanned by specifying a range of grid
+    cells.
 
 `~matplotlib.pyplot.subplot2grid`
-    A helper function that is similar to `.pyplot.subplot`,
-    but uses 0-based indexing and let subplot to occupy multiple cells.
-    This function is not covered in this tutorial.
+    Similar to `.pyplot.subplot`, but uses 0-based indexing and two-d python
+    slicing to choose cells.
 
 .. redirect-from:: /tutorials/intermediate/gridspec
 
@@ -80,22 +96,22 @@
     for col in range(2):
         axs[row, col].annotate(f'axs[{row}, {col}]', (0.1, 0.5),
                                xycoords='axes fraction', va='center')
-fig.suptitle('subplots')
+fig.suptitle('plt.subplots()')
 
 ##############################################################################
 # The same effect can be achieved with `~.pyplot.subplot_mosaic`,
 # but the return type is a dictionary instead of an array, where the user
 # can give the keys useful meanings.  Here we provide two lists, each list
 # representing a row, and each element in the list a key representing the
-# column.  Note that keys can be any dictionary key, but we typically use
-# strings:
+# column.
 
-fig, axs = plt.subplot_mosaic([['upleft', 'upright'], ['loleft', 'loright']],
+fig, axd = plt.subplot_mosaic([['upleft', 'upright'],
+                               ['loleft', 'loright']],
                               figsize=(4.5, 3.5), constrained_layout=True)
-for k in axs.keys():
-    axs[k].annotate(f'axs["{k}"]', (0.1, 0.5),
+for k in axd.keys():
+    axd[k].annotate(f'axd["{k}"]', (0.1, 0.5),
                     xycoords='axes fraction', va='center')
-fig.suptitle('subplot_mosaic')
+fig.suptitle('plt.subplot_mosaic()')
 
 ############################################################################
 # Axes spanning rows or columns in a grid
@@ -106,35 +122,37 @@
 # convenient is probably to use `~.pyplot.subplot_mosaic` by repeating one
 # of the keys:
 
-fig, axs = plt.subplot_mosaic([['upleft', 'right'], ['loleft', 'right']],
+fig, axd = plt.subplot_mosaic([['upleft', 'right'],
+                               ['loleft', 'right']],
                               figsize=(4.5, 3.5), constrained_layout=True)
-for k in axs.keys():
-    axs[k].annotate(f'axs["{k}"]', (0.1, 0.5),
+for k in axd.keys():
+    axd[k].annotate(f'axd["{k}"]', (0.1, 0.5),
                     xycoords='axes fraction', va='center')
-fig.suptitle('subplot_mosaic')
+fig.suptitle('plt.subplot_mosaic()')
 
 ############################################################################
 # See below for the description of how to do the same thing using
-# `~matplotlib.gridspec.GridSpec` or ~matplotlib.pyplot.subplot2grid`.
+# `~matplotlib.gridspec.GridSpec` or `~matplotlib.pyplot.subplot2grid`.
 #
 # Variable widths or heights in a grid
 # ------------------------------------
 #
 # Both `~.pyplot.subplots` and `~.pyplot.subplot_mosaic` allow the rows
 # in the grid to be different heights, and the columns to be different
 # widths using the *gridspec_kw* keyword argument.
-# Any parameter accepted by :class:`~matplotlib.gridspec.GridSpec` can
-# be passed to `~matplotlib.pyplot.subplots` and
+# Spacing parameters accepted by :class:`~matplotlib.gridspec.GridSpec`
+# can be passed to `~matplotlib.pyplot.subplots` and
 # `~matplotlib.pyplot.subplot_mosaic`:
 
 gs_kw = dict(width_ratios=[1, 2.2], height_ratios=[1, 2])
-fig, axs = plt.subplot_mosaic([['upleft', 'right'], ['loleft', 'right']],
+fig, axd = plt.subplot_mosaic([['upleft', 'right'],
+                               ['loleft', 'right']],
                               gridspec_kw=gs_kw, figsize=(4.5, 3.5),
                               constrained_layout=True)
-for k in axs.keys():
-    axs[k].annotate(f'axs["{k}"]', (0.1, 0.5),
+for k in axd.keys():
+    axd[k].annotate(f'axd["{k}"]', (0.1, 0.5),
                     xycoords='axes fraction', va='center')
-fig.suptitle('subplot_mosaic')
+fig.suptitle('plt.subplot_mosaic()')
 
 ############################################################################
 # Nested axes layouts
@@ -158,6 +176,24 @@
 subfigs[1].suptitle('subfigs[1]')
 subfigs[1].supylabel('ylabel for subfigs[1]')
 
+############################################################################
+# It is also possible to nest axes using `~.pyplot.subplot_mosaic` using
+# nested lists.  This method does not use subfigures, like above, so lacks
+# the ability to add per-subfigure ``suptitle`` and ``supxlabel``, etc.
+# Rather it is a conveneince wrapper around the `~.SubplotSpec.subgridspec`
+# method described below.
+
+inner = [['innerA'],
+         ['innerB']]
+outer = [['upleft',  inner],
+          ['lowleft', 'lowright']]
+
+fig, axd = plt.subplot_mosaic(outer, constrained_layout=True)
+for k in axd.keys():
+    axd[k].annotate(f'axd["{k}"]', (0.1, 0.5),
+                    xycoords='axes fraction', va='center')
+plt.show()
+
 ############################################################################
 # Low-level and advanced grid methods
 # ===================================
@@ -214,7 +250,7 @@
 # subplot sizes to fill the figure.  Usually such manual placement
 # requires iterations to make the axes tick labels not overlap the axes.
 
-fig = plt.figure(constrained_layout=False)
+fig = plt.figure(constrained_layout=False, facecolor='0.9')
 gs = fig.add_gridspec(nrows=3, ncols=3, left=0.05, right=0.75,
                       hspace=0.1, wspace=0.05)
 ax0 = fig.add_subplot(gs[:-1, :])
@@ -224,9 +260,9 @@
 ax2 = fig.add_subplot(gs[-1, -1])
 ax2.annotate('ax2', (0.1, 0.5),  xycoords='axes fraction', va='center')
 fig.suptitle('Manual gridspec with right=0.75')
-
+plt.show()
 ###############################################################################
-# Nested layouts with SubPlotSpec
+# Nested layouts with SubplotSpec
 # ===============================
 #
 # You can create nested layout similar to `~.Figure.subfigures` using
