Merge pull request #13775 from ImportanceOfBeingErnest/doc-scatter-hist-example

tacaswell · web-flow · commit 90f6a3587c68 · 2019-09-01T15:47:48.000-04:00
DOC: Scatter Hist example update
diff --git a/.flake8 b/.flake8
@@ -71,6 +71,7 @@ per-file-ignores =
 
     examples/animation/frame_grabbing_sgskip.py: E402
     examples/axes_grid1/inset_locator_demo.py: E402
+    examples/axes_grid1/scatter_hist_locatable_axes.py: E401, E402
     examples/axisartist/demo_curvelinear_grid.py: E402
     examples/color/color_by_yvalue.py: E402
     examples/color/color_cycle_default.py: E402
@@ -128,6 +129,7 @@ per-file-ignores =
     examples/lines_bars_and_markers/filled_step.py: E402
     examples/lines_bars_and_markers/horizontal_barchart_distribution.py: E402
     examples/lines_bars_and_markers/joinstyle.py: E402
+    examples/lines_bars_and_markers/scatter_hist.py: E402
     examples/lines_bars_and_markers/scatter_piecharts.py: E402
     examples/lines_bars_and_markers/scatter_with_legend.py: E402
     examples/lines_bars_and_markers/span_regions.py: E402
diff --git a/examples/axes_grid1/scatter_hist_locatable_axes.py b/examples/axes_grid1/scatter_hist_locatable_axes.py
@@ -1,54 +1,80 @@
 """
-============
-Scatter Hist
-============
+==================================
+Scatter Histogram (Locatable Axes)
+==================================
 
+Show the marginal distributions of a scatter as histograms at the sides of
+the plot.
+
+For a nice alignment of the main axes with the marginals, the axes positions
+are defined by a ``Divider``, produced via `.make_axes_locatable`.
+
+An alternative method to produce a similar figure is shown in the
+:doc:`/gallery/lines_bars_and_markers/scatter_hist` example. The advantage of
+the locatable axes method shown below is that the marginal axes follow the
+fixed aspect ratio of the main axes.
 """
+
 import numpy as np
 import matplotlib.pyplot as plt
 from mpl_toolkits.axes_grid1 import make_axes_locatable
 
 # Fixing random state for reproducibility
 np.random.seed(19680801)
 
-
 # the random data
 x = np.random.randn(1000)
 y = np.random.randn(1000)
 
 
-fig, axScatter = plt.subplots(figsize=(5.5, 5.5))
+fig, ax = plt.subplots(figsize=(5.5, 5.5))
 
 # the scatter plot:
-axScatter.scatter(x, y)
-axScatter.set_aspect(1.)
+ax.scatter(x, y)
+
+# Set aspect of the main axes.
+ax.set_aspect(1.)
 
 # create new axes on the right and on the top of the current axes
-# The first argument of the new_vertical(new_horizontal) method is
-# the height (width) of the axes to be created in inches.
-divider = make_axes_locatable(axScatter)
-axHistx = divider.append_axes("top", 1.2, pad=0.1, sharex=axScatter)
-axHisty = divider.append_axes("right", 1.2, pad=0.1, sharey=axScatter)
+divider = make_axes_locatable(ax)
+# below height and pad are in inches
+ax_histx = divider.append_axes("top", 1.2, pad=0.1, sharex=ax)
+ax_histy = divider.append_axes("right", 1.2, pad=0.1, sharey=ax)
 
 # make some labels invisible
-axHistx.xaxis.set_tick_params(labelbottom=False)
-axHisty.yaxis.set_tick_params(labelleft=False)
+ax_histx.xaxis.set_tick_params(labelbottom=False)
+ax_histy.yaxis.set_tick_params(labelleft=False)
 
 # now determine nice limits by hand:
 binwidth = 0.25
 xymax = max(np.max(np.abs(x)), np.max(np.abs(y)))
 lim = (int(xymax/binwidth) + 1)*binwidth
 
 bins = np.arange(-lim, lim + binwidth, binwidth)
-axHistx.hist(x, bins=bins)
-axHisty.hist(y, bins=bins, orientation='horizontal')
+ax_histx.hist(x, bins=bins)
+ax_histy.hist(y, bins=bins, orientation='horizontal')
 
-# the xaxis of axHistx and yaxis of axHisty are shared with axScatter,
+# the xaxis of ax_histx and yaxis of ax_histy are shared with ax,
 # thus there is no need to manually adjust the xlim and ylim of these
 # axis.
 
-axHistx.set_yticks([0, 50, 100])
-
-axHisty.set_xticks([0, 50, 100])
+ax_histx.set_yticks([0, 50, 100])
+ax_histy.set_xticks([0, 50, 100])
 
 plt.show()
+
+#############################################################################
+#
+# ------------
+#
+# References
+# """"""""""
+#
+# The use of the following functions, methods and classes is shown
+# in this example:
+
+import matplotlib, mpl_toolkits
+mpl_toolkits.axes_grid1.axes_divider.make_axes_locatable
+matplotlib.axes.Axes.set_aspect
+matplotlib.axes.Axes.scatter
+matplotlib.axes.Axes.hist
diff --git a/examples/lines_bars_and_markers/scatter_hist.py b/examples/lines_bars_and_markers/scatter_hist.py
@@ -3,18 +3,62 @@
 Scatter plot with histograms
 ============================
 
-Create a scatter plot with histograms to its sides.
+Show the marginal distributions of a scatter as histograms at the sides of
+the plot.
+
+For a nice alignment of the main axes with the marginals, two options are shown
+below.
+
+* the axes positions are defined in terms of rectangles in figure coordinates
+* the axes positions are defined via a gridspec
+
+An alternative method to produce a similar figure using the ``axes_grid1``
+toolkit is shown in the
+:doc:`/gallery/axes_grid1/scatter_hist_locatable_axes` example.
+
+Let us first define a function that takes x and y data as input, as well
+as three axes, the main axes for the scatter, and two marginal axes. It will
+then create the scatter and histograms inside the provided axes.
 """
+
 import numpy as np
 import matplotlib.pyplot as plt
 
 # Fixing random state for reproducibility
 np.random.seed(19680801)
 
-# the random data
+# some random data
 x = np.random.randn(1000)
 y = np.random.randn(1000)
 
+
+def scatter_hist(x, y, ax, ax_histx, ax_histy):
+    # no labels
+    ax_histx.tick_params(axis="x", labelbottom=False)
+    ax_histy.tick_params(axis="y", labelleft=False)
+
+    # the scatter plot:
+    ax.scatter(x, y)
+
+    # now determine nice limits by hand:
+    binwidth = 0.25
+    xymax = max(np.max(np.abs(x)), np.max(np.abs(y)))
+    lim = (int(xymax/binwidth) + 1) * binwidth
+
+    bins = np.arange(-lim, lim + binwidth, binwidth)
+    ax_histx.hist(x, bins=bins)
+    ax_histy.hist(y, bins=bins, orientation='horizontal')
+
+
+#############################################################################
+#
+# Axes in figure coordinates
+# --------------------------
+#
+# To define the axes positions, `.Figure.add_axes` is provided with a rectangle
+# ``[left, bottom, width, height]`` in figure coordinates. The marginal axes
+# share one dimension with the main axes.
+
 # definitions for the axes
 left, width = 0.1, 0.65
 bottom, height = 0.1, 0.65
@@ -25,30 +69,61 @@
 rect_histx = [left, bottom + height + spacing, width, 0.2]
 rect_histy = [left + width + spacing, bottom, 0.2, height]
 
-# start with a rectangular Figure
-plt.figure(figsize=(8, 8))
+# start with a square Figure
+fig = plt.figure(figsize=(8, 8))
+
+ax = fig.add_axes(rect_scatter)
+ax_histx = fig.add_axes(rect_histx, sharex=ax)
+ax_histy = fig.add_axes(rect_histy, sharey=ax)
+
+# use the previously defined function
+scatter_hist(x, y, ax, ax_histx, ax_histy)
+
+plt.show()
+
 
-ax_scatter = plt.axes(rect_scatter)
-ax_scatter.tick_params(direction='in', top=True, right=True)
-ax_histx = plt.axes(rect_histx)
-ax_histx.tick_params(direction='in', labelbottom=False)
-ax_histy = plt.axes(rect_histy)
-ax_histy.tick_params(direction='in', labelleft=False)
+#############################################################################
+#
+# Using a gridspec
+# ----------------
+#
+# We may equally define a gridspec with unequal width- and height-ratios to
+# achieve desired layout. Also see the :doc:`/tutorials/intermediate/gridspec`
+# tutorial.
 
-# the scatter plot:
-ax_scatter.scatter(x, y)
+# start with a square Figure
+fig = plt.figure(figsize=(8, 8))
 
-# now determine nice limits by hand:
-binwidth = 0.25
-lim = np.ceil(np.abs([x, y]).max() / binwidth) * binwidth
-ax_scatter.set_xlim((-lim, lim))
-ax_scatter.set_ylim((-lim, lim))
+# Add a gridspec with two rows and two columns and a ratio of 2 to 7 between
+# the size of the marginal axes and the main axes in both directions.
+# Also adjust the subplot parameters for a square plot.
+gs = fig.add_gridspec(2, 2,  width_ratios=(7, 2), height_ratios=(2, 7),
+                      left=0.1, right=0.9, bottom=0.1, top=0.9,
+                      wspace=0.05, hspace=0.05)
 
-bins = np.arange(-lim, lim + binwidth, binwidth)
-ax_histx.hist(x, bins=bins)
-ax_histy.hist(y, bins=bins, orientation='horizontal')
+ax = fig.add_subplot(gs[1, 0])
+ax_histx = fig.add_subplot(gs[0, 0], sharex=ax)
+ax_histy = fig.add_subplot(gs[1, 1], sharey=ax)
 
-ax_histx.set_xlim(ax_scatter.get_xlim())
-ax_histy.set_ylim(ax_scatter.get_ylim())
+# use the previously defined function
+scatter_hist(x, y, ax, ax_histx, ax_histy)
 
 plt.show()
+
+
+#############################################################################
+#
+# ------------
+#
+# References
+# """"""""""
+#
+# The use of the following functions, methods and classes is shown
+# in this example:
+
+import matplotlib
+matplotlib.figure.Figure.add_axes
+matplotlib.figure.Figure.add_subplot
+matplotlib.figure.Figure.add_gridspec
+matplotlib.axes.Axes.scatter
+matplotlib.axes.Axes.hist
diff --git a/tutorials/toolkits/axes_grid.py b/tutorials/toolkits/axes_grid.py
@@ -3,21 +3,22 @@
 Overview of axes_grid1 toolkit
 ==============================
 
-Controlling the layout of plots with the axes_grid toolkit.
+Controlling the layout of plots with the
+:mod:`mpl_toolkits.axes_grid1` toolkit.
 
 .. _axes_grid1_users-guide-index:
 
 
 What is axes_grid1 toolkit?
 ===========================
 
-*axes_grid1* is a collection of helper classes to ease displaying
-(multiple) images with matplotlib.  In matplotlib, the axes location
+:mod:`mpl_toolkits.axes_grid1` is a collection of helper classes to ease
+displaying (multiple) images with matplotlib. In matplotlib, the axes location
 (and size) is specified in the normalized figure coordinates, which
 may not be ideal for displaying images that needs to have a given
 aspect ratio.  For example, it helps if you have a colorbar whose
 height always matches that of the image.  `ImageGrid`_, `RGB Axes`_ and
-`AxesDivider`_ are helper classes that deals with adjusting the
+`AxesDivider`_ are helper classes that deal with adjusting the
 location of (multiple) Axes.  They provides a framework to adjust the
 position of multiple axes at the drawing time. `ParasiteAxes`_
 provides twinx(or twiny)-like features so that you can plot different
@@ -119,7 +120,7 @@
  *aspect*
   By default (False), widths and heights of axes in the grid are
   scaled independently. If True, they are scaled according to their
-  data limits (similar to aspect parameter in mpl).
+  data limits (similar to aspect parameter in Matplotlib).
 
  *share_all*
   if True, xaxis and yaxis of all axes are shared.
@@ -161,19 +162,19 @@
 -----------------
 
 Behind the scene, the ImageGrid class and the RGBAxes class utilize the
-AxesDivider class, whose role is to calculate the location of the axes
-at drawing time. While a more about the AxesDivider is (will be)
-explained in (yet to be written) AxesDividerGuide, direct use of the
-AxesDivider class will not be necessary for most users.  The
-axes_divider module provides a helper function make_axes_locatable,
-which can be useful. It takes a existing axes instance and create a
-divider for it. ::
+`~.axes_grid1.axes_divider.AxesDivider` class, whose role is to calculate the
+location of the axes at drawing time. Direct use of the
+AxesDivider class will not be necessary for most users. The
+axes_divider module provides a helper function
+`~.axes_grid1.axes_divider.make_axes_locatable`, which can be useful.
+It takes a existing axes instance and create a divider for it. ::
 
   ax = subplot(1, 1, 1)
   divider = make_axes_locatable(ax)
 
-*make_axes_locatable* returns an instance of the AxesLocator class,
-derived from the Locator. It provides *append_axes* method that
+*make_axes_locatable* returns an instance of the
+`~.axes_grid1.axes_divider.AxesDivider` class. It provides an
+`~.AxesDivider.append_axes` method that
 creates a new axes on the given side of ("top", "right", "bottom" and
 "left") of the original axes.
 
@@ -193,7 +194,7 @@
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The :doc:`/gallery/lines_bars_and_markers/scatter_hist` example can be
-rewritten using *make_axes_locatable*::
+rewritten using `~.axes_grid1.axes_divider.make_axes_locatable`::
 
     axScatter = subplot(111)
     axScatter.scatter(x, y)
@@ -219,10 +220,11 @@
 
    Scatter Hist
 
-The scatter_hist using the AxesDivider has some advantage over the
-original scatter_hist.py in mpl. For example, you can set the aspect
-ratio of the scatter plot, even with the x-axis or y-axis is shared
-accordingly.
+The :doc:`/gallery/axes_grid1/scatter_hist_locatable_axes` using the
+AxesDivider has some advantage over the
+original :doc:`/gallery/lines_bars_and_markers/scatter_hist` in Matplotlib.
+For example, you can set the aspect ratio of the scatter plot, even with the
+x-axis or y-axis is shared accordingly.
 
 
 ParasiteAxes
@@ -297,7 +299,7 @@
 ---------------
 
 It's a collection of artists whose location is anchored to the (axes)
-bbox, like the legend. It is derived from *OffsetBox* in mpl, and
+bbox, like the legend. It is derived from *OffsetBox* in Matplotlib, and
 artist need to be drawn in the canvas coordinate. But, there is a
 limited support for an arbitrary transform. For example, the ellipse
 in the example below will have width and height in the data
@@ -391,8 +393,8 @@
 AxesDivider
 ===========
 
-The `~.axes_grid1.axes_divider` module provides helper classes to adjust the
-axes positions of a set of images at drawing time.
+The :mod:`mpl_toolkits.axes_grid1.axes_divider` module provides helper classes
+to adjust the axes positions of a set of images at drawing time.
 
 * :mod:`~mpl_toolkits.axes_grid1.axes_size` provides a class of
   units that are used to determine the size of each axes. For example,
