addressing comments

choldgraf · choldgraf · commit 5b448ccc5513 · 2017-10-14T21:41:46.000-07:00
diff --git a/examples/images_contours_and_fields/image_transparency_blend.py b/examples/images_contours_and_fields/image_transparency_blend.py
@@ -1,24 +1,22 @@
 """
-=============================================
-Blend transparency with color with 2-D images
-=============================================
+===========================================
+Blend transparency with color in 2-D images
+===========================================
 
 Blend transparency with color to highlight parts of data with imshow.
 
 A common use for :func:`matplotlib.pyplot.imshow` is to plot a 2-D statistical
-map. In this case, it's common to visualize the statistic of choice (e.g.,
-a t-statistic) alongisde another value of interest (e.g., the p-value for that
-statistic). One way to do this is to map the p-value onto the transparency of
-the image such that data with "significant" values are highlighted.
-
-This example demonstrates how you can achieve this effect using
-:class:`matplotlib.colors.Normalize. Note that it is not possible to directly
-pass alpha values to :func:`matplotlib.pyplot.imshow`.
+map. While ``imshow`` makes it easy to visualize a 2-D matrix as an image,
+it doesn't easily let you add transparency to the output. For example, one can
+plot a statistic (such as a t-statistic) and color the transparency of
+each pixel according to its p-value. This example demonstrates how you can
+achieve this effect using :class:`matplotlib.colors.Normalize`. Note that it is
+not possible to directly pass alpha values to :func:`matplotlib.pyplot.imshow`.
 
 First we will generate some data, in this case, we'll create two 2-D "blobs"
 in a 2-D grid. One blob will be positive, and the other negative.
 """
-# sphinx_gallery_thumbnail_number = 2
+# sphinx_gallery_thumbnail_number = 3
 import numpy as np
 from scipy.stats import multivariate_normal
 import matplotlib.pyplot as plt
@@ -31,33 +29,68 @@
 grid = np.array(np.meshgrid(xx, yy))
 grid = grid.transpose(2, 1, 0)
 
-# Generate the blobs
+# Generate the blobs. The range of the values is roughly -.0002 to .0002
 means_high = [20, 50]
 means_low = [50, 60]
 cov = [[500, 0], [0, 800]]
 gauss_high = multivariate_normal.pdf(grid, means_high, cov)
 gauss_low = -1 * multivariate_normal.pdf(grid, means_low, cov)
 weights = gauss_high + gauss_low
 
-# We'll plot these blobs using only ``imshow``.
-vmax = np.abs(weights).max() * 1.5
+# We'll also create a grey background into which the pixels will fade
+greys = np.ones(weights.shape + (3,)) * 70
+
+# First we'll plot these blobs using only ``imshow``.
+vmax = np.abs(weights).max()
 vmin = -vmax
 cmap = plt.cm.RdYlBu
+
 fig, ax = plt.subplots()
+ax.imshow(greys)
 ax.imshow(weights, extent=(xmin, xmax, ymin, ymax), cmap=cmap)
 ax.set_axis_off()
 
-################################################################################
+###############################################################################
 # Blending in transparency
 # ========================
 #
-# Below, we'll recreate the same plot, but this time we'll blend in
-# transparency with the image so that the extreme values are highlighted.
-# We'll also add in contour lines to highlight the image values.
+# The simplest way to include transparency when plotting data with
+# :func:`matplotlib.pyplot.imshow` is to convert the 2-D data array to a
+# 3-D image array of rgba values. This can be done with
+# :class:`matplotlib.colors.Normalize`. For example, we'll create a gradient
+# moving from left to right below.
+
+# Create an alpha channel of linearly increasing values moving to the right.
+alphas = np.ones(weights.shape)
+alphas[:, 30:] = np.linspace(1, 0, 70)
+
+# Normalize the colors b/w 0 and 1, we'll then pass an MxNx4 array to imshow
+colors = Normalize(vmin, vmax, clip=True)(weights)
+colors = cmap(colors)
+
+# Now set the alpha channel to the one we created above
+colors[..., -1] = alphas
+
+# Create the figure and image
+# Note that the absolute values may be slightly different
+fig, ax = plt.subplots()
+ax.imshow(greys)
+ax.imshow(colors, extent=(xmin, xmax, ymin, ymax))
+ax.set_axis_off()
+
+###############################################################################
+# Using transparency to highlight values with high amplitude
+# ==========================================================
+#
+# Finally, we'll recreate the same plot, but this time we'll use transparency
+# to highlight the extreme values in the data. This is often used to highlight
+# data points with smaller p-values. We'll also add in contour lines to
+# highlight the image values.
 
 # Create an alpha channel based on weight values
+# Any value whose absolute value is > .0001 will have zero transparency
 alphas = Normalize(0, .0001, clip=True)(np.abs(weights))
-alphas = np.clip(alphas, .4, 1)
+alphas = np.clip(alphas, .4, 1)  # alpha value clipped at the bottom at .4
 
 # Normalize the colors b/w 0 and 1, we'll then pass an MxNx4 array to imshow
 colors = Normalize(vmin, vmax)(weights)
@@ -69,6 +102,7 @@
 # Create the figure and image
 # Note that the absolute values may be slightly different
 fig, ax = plt.subplots()
+ax.imshow(greys)
 ax.imshow(colors, extent=(xmin, xmax, ymin, ymax))
 
 # Add contour lines to further highlight different levels.
