DOC: updatye docs for DivergingNorm

jklymak · jklymak · commit 38cb3dc692bd · 2018-10-06T22:37:30.000-07:00
diff --git a/doc/users/next_whats_new/2018-10-08-JMK.rst b/doc/users/next_whats_new/2018-10-08-JMK.rst
@@ -0,0 +1,9 @@
+:orphan:
+
+New DivergingNorm added
+```````````````````````
+
+`colors.DivergingNorm` added to allow a colormap to have unequal data mapping
+into the colormap around a center data value.  See
+:doc:`/gallery/userdemo/colormap_diverging_norm` and
+:doc:`/tutorials/colors/colormapnorms`.
diff --git a/examples/userdemo/colormap_diverging_norm.py b/examples/userdemo/colormap_diverging_norm.py
@@ -0,0 +1,41 @@
+"""
+====================================
+DivergingNorm Colormap Normalization
+====================================
+
+Demonstration of using `.colors.DivergingNorm` to map data onto a colormap
+with a different ramp on either side of a central value (zero in this
+case).
+
+.. note::
+    Non-symmetric mapping of data to color is non-standard
+    practice for quantitative data, and should only be used advisedly.  A
+    practical example is having an ocean/land colormap where the land and
+    ocean data span different ranges.
+
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.colors as colors
+
+N = 100
+X, Y = np.mgrid[-3:3:complex(0, N), -2:2:complex(0, N)]
+Z1 = np.exp(-X**2 - Y**2)
+Z2 = np.exp(-(X - 1)**2 - (Y - 1)**2)
+Z = (Z1 - 0.4 * Z2) * 10000
+
+fig, ax = plt.subplots(2, 1, constrained_layout=True)
+
+pcm = ax[0].pcolormesh(X, Y, Z,
+                       norm=colors.DivergingNorm(vcenter=0.),
+                       vmin=-4000, vmax=10000,
+                       cmap='RdBu_r')
+fig.colorbar(pcm, ax=ax[0], extend='both')
+ax[0].set_title('DivergingNorm', loc='left')
+
+pcm = ax[1].pcolormesh(X, Y, Z, cmap='RdBu_r', vmin=-10000, vmax=10000)
+fig.colorbar(pcm, ax=ax[1], extend='both')
+ax[1].set_title('Linear Norm', loc='left')
+
+plt.show()
diff --git a/examples/userdemo/colormap_normalizations_custom.py b/examples/userdemo/colormap_normalizations_custom.py
@@ -1,25 +1,23 @@
 """
 ==============================
-Colormap Normalizations Custom
+Custom Colormap Normalizations
 ==============================
 
-Demonstration of using norm to map colormaps onto data in non-linear ways.
+Demonstration of using norm to map datra onto colormaps using a user-defined
+normalization.  The norm here is the same as the one provided by
+`.colors.DivergingNorm`; see
+:doc:`/gallery/userdemo/colormap_diverging_norm`.
 """
 
 import numpy as np
 import matplotlib.pyplot as plt
 import matplotlib.colors as colors
 
 N = 100
-'''
-Custom Norm: An example with a customized normalization.  This one
-uses the example above, and normalizes the negative data differently
-from the positive.
-'''
 X, Y = np.mgrid[-3:3:complex(0, N), -2:2:complex(0, N)]
 Z1 = np.exp(-X**2 - Y**2)
 Z2 = np.exp(-(X - 1)**2 - (Y - 1)**2)
-Z = (Z1 - Z2) * 2
+Z = (Z1 - 0.4 * Z2) * 10000
 
 
 # Example of making your own norm.  Also see matplotlib.colors.
diff --git a/lib/matplotlib/colorbar.py b/lib/matplotlib/colorbar.py
@@ -509,8 +509,9 @@ def _use_auto_colorbar_locator(self):
         """
         return (self.boundaries is None
                 and self.values is None
-                and ((type(self.norm) == colors.Normalize)
-                    or (type(self.norm) == colors.LogNorm)))
+                and ((type(self.norm) in [colors.Normalize,
+                                          colors.LogNorm,
+                                          colors.DivergingNorm])))
 
     def update_ticks(self):
         """
@@ -1009,6 +1010,7 @@ def _locate(self, x):
             # as to make the interpolation more accurate.
             b = self.norm(self._boundaries, clip=False).filled()
             xn = self.norm(x, clip=False).filled()
+        b = np.unique(b)
 
         # The rest is linear interpolation with extrapolation at ends.
         ii = np.searchsorted(b, xn)
diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py
@@ -1114,6 +1114,9 @@ def __init__(self, vmin=None, vcenter=None, vmax=None):
 
         Examples
         --------
+
+        See :doc:`/gallery/userdemo/colormap_diverging_norm`.
+
         This maps data value -4000 to 0., 0 to 0.5, and +10000 to 1.0; data
         between is linearly interpolated::
 
diff --git a/tutorials/colors/colormapnorms.py b/tutorials/colors/colormapnorms.py
@@ -198,7 +198,7 @@
 # cases such as masked data)
 #
 # .. note::
-#    This may appear soon as :func:`colors.OffsetNorm`.
+#    This example is the same as `.colors.DivergingNorm`.
 #
 #    As above, non-symmetric mapping of data to color is non-standard
 #    practice for quantitative data, and should only be used advisedly.  A
@@ -209,7 +209,7 @@
 X, Y = np.mgrid[-3:3:complex(0, N), -2:2:complex(0, N)]
 Z1 = np.exp(-X**2 - Y**2)
 Z2 = np.exp(-(X - 1)**2 - (Y - 1)**2)
-Z = (Z1 - Z2) * 2
+Z = (Z1 - 0.4 * Z2) * 10000
 
 
 class MidpointNormalize(colors.Normalize):
@@ -224,13 +224,19 @@ def __call__(self, value, clip=None):
         return np.ma.masked_array(np.interp(value, x, y))
 
 
-fig, ax = plt.subplots(2, 1)
+fig, ax = plt.subplots(2, 1, constrained_layout=True)
 
 pcm = ax[0].pcolormesh(X, Y, Z,
                        norm=MidpointNormalize(midpoint=0.),
+                       vmin=-4000, vmax=10000,
                        cmap='RdBu_r')
 fig.colorbar(pcm, ax=ax[0], extend='both')
+ax[0].set_title('Custom Normalization', loc='left')
 
-pcm = ax[1].pcolormesh(X, Y, Z, cmap='RdBu_r', vmin=-np.max(Z))
+pcm = ax[1].pcolormesh(X, Y, Z, cmap='RdBu_r',
+                       norm=colors.DivergingNorm(vcenter=0.),
+                       vmin=-4000, vmax=10000)
 fig.colorbar(pcm, ax=ax[1], extend='both')
+ax[1].set_title('DivergingNorm Normalization', loc='left')
 fig.show()
+plt.show()
