DOC: modernize gridspec tutorial

jklymak · jklymak · commit f99590c0aff5 · 2021-11-14T21:41:36.000+01:00
diff --git a/.flake8 b/.flake8
@@ -94,7 +94,6 @@ per-file-ignores =
     tutorials/colors/colormap-manipulation.py: E402
     tutorials/intermediate/artists.py: E402
     tutorials/intermediate/constrainedlayout_guide.py: E402
-    tutorials/intermediate/gridspec.py: E402
     tutorials/intermediate/legend_guide.py: E402
     tutorials/intermediate/tight_layout_guide.py: E402
     tutorials/introductory/customizing.py: E501
diff --git a/doc/users/prev_whats_new/whats_new_1.0.rst b/doc/users/prev_whats_new/whats_new_1.0.rst
@@ -23,7 +23,8 @@ Sophisticated subplot grid layout
 
 Jae-Joon Lee has written :mod:`~matplotlib.gridspec`, a new module for
 doing complex subplot layouts, featuring row and column spans and
-more.  See :doc:`/tutorials/intermediate/gridspec` for a tutorial overview.
+more.  See :doc:`/tutorials/intermediate/arranging_axes` for a tutorial
+overview.
 
 .. figure:: ../../gallery/userdemo/images/sphx_glr_demo_gridspec01_001.png
    :target: ../../gallery/userdemo/demo_gridspec01.html
diff --git a/examples/lines_bars_and_markers/scatter_hist.py b/examples/lines_bars_and_markers/scatter_hist.py
@@ -60,7 +60,7 @@ def scatter_hist(x, y, ax, ax_histx, ax_histy):
 # --------------------------------------------
 #
 # We define a gridspec with unequal width- and height-ratios to achieve desired
-# layout.  Also see the :doc:`/tutorials/intermediate/gridspec` tutorial.
+# layout.  Also see the :doc:`/tutorials/intermediate/arranging_axes` tutorial.
 
 # Start with a square Figure.
 fig = plt.figure(figsize=(6, 6))
diff --git a/examples/subplots_axes_and_figures/gridspec_and_subplots.py b/examples/subplots_axes_and_figures/gridspec_and_subplots.py
@@ -8,7 +8,10 @@
 and then remove the covered axes and fill the gap with a new bigger axes.
 Here we create a layout with the bottom two axes in the last column combined.
 
-See also :doc:`/tutorials/intermediate/gridspec`.
+To start with this layout (rather than removing the overlapping axes) use
+`~.pyplot.subplot_mosaic`.
+
+See also :doc:`/tutorials/intermediate/arranging_axes`.
 """
 
 import matplotlib.pyplot as plt
diff --git a/lib/matplotlib/gridspec.py b/lib/matplotlib/gridspec.py
@@ -5,8 +5,10 @@
 The `GridSpec` specifies the overall grid structure. Individual cells within
 the grid are referenced by `SubplotSpec`\s.
 
-See the tutorial :doc:`/tutorials/intermediate/gridspec` for a comprehensive
-usage guide.
+Often, users need not access this module directly, and can use higher-level
+methods like `~.pyplot.subplots`, `~.pyplot.subplot_mosaic` and
+`~.Figure.subfigures`. See the tutorial
+:doc:`/tutorials/intermediate/arranging_axes` for a guide.
 """
 
 import copy
diff --git a/tutorials/intermediate/arranging_axes.py b/tutorials/intermediate/arranging_axes.py
@@ -0,0 +1,314 @@
+"""
+==========================
+Arranging 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.
+
+How to create grid-shaped combinations of axes:
+
+`~matplotlib.pyplot.subplots`
+    The primary function used to create figures and a grid of axes.  It is
+    similar to `.pyplot.subplot`, but creates and places all axes on the
+    figure at once, and returns an object array with handles for
+    the axes in the grid.  See also `.Figure.subplots`.
+
+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`.
+
+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`:
+
+`~matplotlib.gridspec.GridSpec`
+    Specifies the geometry of the grid that a subplot will be
+    placed. The number of rows and number of columns of the grid
+    need to be set. Optionally, the subplot layout parameters
+    (e.g., left, right, etc.) can be tuned.
+
+`~matplotlib.gridspec.SubplotSpec`
+    Specifies the location of the subplot in the given `.GridSpec`.
+
+An older way to add axes in grids:
+
+`~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.
+
+.. redirect-from:: /tutorials/intermediate/gridspec
+
+"""
+
+import matplotlib.pyplot as plt
+
+import numpy as np
+
+############################################################################
+# High-level methods for making grids
+# ===================================
+#
+# Basic 2x2 grid
+# --------------
+#
+# We can create a basic 2-by-2 grid of axes using
+# :func:`~matplotlib.pyplot.subplots`.  It returns a
+# :class:`~matplotlib.figure.Figure` instance and an array of
+# :class:`~matplotlib.axes.Axes` objects.  The axes objects can
+# be used to access methods to place artists on the axes; here we
+# use `~.Axes.annotate`, but other examples could be `~.Axes.plot`,
+# `~.Axes.pcolormesh`, etc.
+
+fig, axs = plt.subplots(ncols=2, nrows=2, figsize=(4.5, 3.5),
+                        constrained_layout=True)
+for row in range(2):
+    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')
+
+##############################################################################
+# 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:
+
+fig, axs = 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),
+                    xycoords='axes fraction', va='center')
+fig.suptitle('subplot_mosaic')
+
+############################################################################
+# Axes spanning rows or columns in a grid
+# ---------------------------------------
+#
+# Sometimes we want axes to span rows or columns of the grid.
+# There are actually multiple ways to accomplish this, but the most
+# convenient is probably to use `~.pyplot.subplot_mosaic` by repeating one
+# of the keys:
+
+fig, axs = 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),
+                    xycoords='axes fraction', va='center')
+fig.suptitle('subplot_mosaic')
+
+############################################################################
+# See below for the description of how to do the same thing using
+# `~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
+# `~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']],
+                              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),
+                    xycoords='axes fraction', va='center')
+fig.suptitle('subplot_mosaic')
+
+############################################################################
+# Nested axes layouts
+# -------------------
+#
+# Sometimes it is helpful to have two or more grids of axes that
+# may not need to be related to one another.  The most simple way to
+# accomplish this is to use `.Figure.subfigures`.  Note that the alignement
+# of the subfigure layouts is independent with the axes spines in each
+# subfigure having independent positions.  See below for a more verbose
+# way to acheive the same effect with `~.gridspec.GridSpecFromSubplotSpec`.
+
+fig = plt.figure(constrained_layout=True)
+subfigs = fig.subfigures(1, 2, wspace=0.07, width_ratios=[1.5, 1.])
+axs0 = subfigs[0].subplots(2, 2)
+subfigs[0].set_facecolor('0.9')
+subfigs[0].suptitle('subfigs[0]\nLeft side')
+subfigs[0].supxlabel('xlabel for subfigs[0]')
+
+axs1 = subfigs[1].subplots(3, 1)
+subfigs[1].suptitle('subfigs[1]')
+subfigs[1].supylabel('ylabel for subfigs[1]')
+
+############################################################################
+# Low-level and advanced grid methods
+# ===================================
+#
+# `~.pyplot.subplots` and `~.pyplot.subplot_mosaic` provide high-level
+# interfaces to create `~.gridspec.GridSpec` objects and add associated
+# new axes to a figure at given `~.gridspec.SubplotSpec` inside the
+# *GridSpec*.
+#
+# Basic 2x2 grid
+# --------------
+#
+# We can accopmplish a 2x2 grid in the same manner as
+# ``plt.subplots(2, 2)``:
+
+fig = plt.figure(figsize=(4.5, 3.5), constrained_layout=True)
+spec = fig.add_gridspec(ncols=2, nrows=2)
+ax0 = fig.add_subplot(spec[0, 0])
+ax0.annotate('ax0', (0.1, 0.5),  xycoords='axes fraction', va='center')
+ax1 = fig.add_subplot(spec[0, 1])
+ax1.annotate('ax1', (0.1, 0.5),  xycoords='axes fraction', va='center')
+ax2 = fig.add_subplot(spec[1, 0])
+ax2.annotate('ax2', (0.1, 0.5),  xycoords='axes fraction', va='center')
+ax3 = fig.add_subplot(spec[1, 1])
+ax3.annotate('ax3', (0.1, 0.5),  xycoords='axes fraction', va='center')
+fig.suptitle('Manually added subplots using add_gridspec')
+
+#############################################################################
+# Axes spanning rows or grids in a grid
+# -------------------------------------
+#
+# We can index the *spec* array using `NumPy slice syntax
+# <https://numpy.org/doc/stable/reference/arrays.indexing.html>`_
+# and the new axes will span the slice:
+
+fig = plt.figure(figsize=(4.5, 3.5), constrained_layout=True)
+spec = fig.add_gridspec(2, 2)
+ax0 = fig.add_subplot(spec[0, :])
+ax0.annotate('ax0', (0.1, 0.5),  xycoords='axes fraction', va='center')
+ax10 = fig.add_subplot(spec[1, 0])
+ax10.annotate('ax10', (0.1, 0.5),  xycoords='axes fraction', va='center')
+ax11 = fig.add_subplot(spec[1, 1])
+ax11.annotate('ax11', (0.1, 0.5),  xycoords='axes fraction', va='center')
+fig.suptitle('Manually added subplots, spanning a column')
+
+###############################################################################
+# Manual Adjustments to a Gridspec Layout
+# ---------------------------------------
+#
+# When a GridSpec is explicitly used, you can adjust the layout
+# parameters of subplots that are created from the GridSpec.  Note this
+# option is not compatible with ``constrained_layout`` or
+# `.Figure.tight_layout` which both ignore *left* and *right* and adjust
+# 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)
+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, :])
+ax0.annotate('ax0', (0.1, 0.5),  xycoords='axes fraction', va='center')
+ax1 = fig.add_subplot(gs[-1, :-1])
+ax1.annotate('ax1', (0.1, 0.5),  xycoords='axes fraction', va='center')
+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')
+
+###############################################################################
+# Nested layouts with SubPlotSpec
+# ===============================
+#
+# You can create nested layout similar to `~.Figure.subfigures` using
+# `~.gridspec.SubplotSpec.subgridspec`.  Here the axes spines _are_
+# aligned.
+#
+# Note this is also available from the more verbose
+# `.gridspec.GridSpecFromSubplotSpec`.
+
+fig = plt.figure(constrained_layout=True)
+gs0 = fig.add_gridspec(1, 2)
+
+gs00 = gs0[0].subgridspec(2, 2)
+gs01 = gs0[1].subgridspec(3, 1)
+
+for a in range(2):
+    for b in range(2):
+        ax = fig.add_subplot(gs00[a, b])
+        ax.annotate(f'axLeft[{a}, {b}]', (0.1, 0.5), xycoords='axes fraction',
+                    va='center')
+        if a == 1 and b == 1:
+            ax.set_xlabel('xlabel')
+for a in range(3):
+    ax = fig.add_subplot(gs01[a])
+    ax.annotate(f'axRight[{a}]', (0.1, 0.5), xycoords='axes fraction',
+                va='center')
+    if a == 2:
+        ax.set_ylabel('ylabel')
+
+fig.suptitle('nested gridspecs')
+
+###############################################################################
+# Here's a more sophisticated example of nested GridSpec where we put
+# a box around each cell of the outer 4x4 grid, by hiding appropriate
+# spines in each of the inner 3x3 grids.
+
+
+def squiggle_xy(a, b, c, d, i=np.arange(0.0, 2*np.pi, 0.05)):
+    return np.sin(i*a)*np.cos(i*b), np.sin(i*c)*np.cos(i*d)
+
+fig = plt.figure(figsize=(8, 8), constrained_layout=False)
+outer_grid = fig.add_gridspec(4, 4, wspace=0, hspace=0)
+
+for a in range(4):
+    for b in range(4):
+        # gridspec inside gridspec
+        inner_grid = outer_grid[a, b].subgridspec(3, 3, wspace=0, hspace=0)
+        axs = inner_grid.subplots()  # Create all subplots for the inner grid.
+        for (c, d), ax in np.ndenumerate(axs):
+            ax.plot(*squiggle_xy(a + 1, b + 1, c + 1, d + 1))
+            ax.set(xticks=[], yticks=[])
+
+# show only the outside spines
+for ax in fig.get_axes():
+    ss = ax.get_subplotspec()
+    ax.spines.top.set_visible(ss.is_first_row())
+    ax.spines.bottom.set_visible(ss.is_last_row())
+    ax.spines.left.set_visible(ss.is_first_col())
+    ax.spines.right.set_visible(ss.is_last_col())
+
+plt.show()
+
+#############################################################################
+#
+# More reading
+# ============
+#
+#  - More details about :doc:`subplot mosaic </tutorials/provisional/mosaic>`.
+#  - more details about
+#    :doc:`constrained layout
+#    </tutorials/intermediate/constrainedlayout_guide>`, used to align
+#    spacing in most of these examples.
+#
+# .. admonition:: References
+#
+#    The use of the following functions, methods, classes and modules is shown
+#    in this example:
+#
+#    - `matplotlib.pyplot.subplots`
+#    - `matplotlib.pyplot.subplot_mosaic`
+#    - `matplotlib.figure.Figure.add_gridspec`
+#    - `matplotlib.figure.Figure.add_subplot`
+#    - `matplotlib.gridspec.GridSpec`
+#    - `matplotlib.gridspec.SubplotSpec.subgridspec`
+#    - `matplotlib.gridspec.GridSpecFromSubplotSpec`
diff --git a/tutorials/intermediate/gridspec.py b/tutorials/intermediate/gridspec.py
diff --git a/tutorials/intermediate/tight_layout_guide.py b/tutorials/intermediate/tight_layout_guide.py
diff --git a/tutorials/provisional/mosaic.py b/tutorials/provisional/mosaic.py

Original file line number	Diff line number	Diff line change
`@@ -60,7 +60,7 @@ def scatter_hist(x, y, ax, ax_histx, ax_histy):`
`60`	`60`	`# --------------------------------------------`
`61`	`61`	`#`
`62`	`62`	`# We define a gridspec with unequal width- and height-ratios to achieve desired`
`63`		-# layout. Also see the :doc:`/tutorials/intermediate/gridspec` tutorial.
	`63`	+# layout. Also see the :doc:`/tutorials/intermediate/arranging_axes` tutorial.
`64`	`64`
`65`	`65`	`# Start with a square Figure.`
`66`	`66`	`fig = plt.figure(figsize=(6, 6))`