contour: support vmin, vmax kwargs for consistency with pcolor etc.

efiring · efiring · commit f5c85d8d7bce · 2012-08-06T11:16:01.000-10:00
This changeset also simplifies and clarifies the vmin, vmax
explanation and handling for pcolor and pcolormesh.
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,9 +1,17 @@
+2012-08-05 When a norm is passed to contourf, either or both of the
+           vmin, vmax attributes of that norm are now respected.
+           Formerly they were respected only if both were
+           specified. In addition, vmin and/or vmax can now
+           be passed to contourf directly as kwargs. - EF
+
 2012-07-24 Contourf handles the extend kwarg by mapping the extended
            ranges outside the normed 0-1 range so that they are
            handled by colormap colors determined by the set_under
            and set_over methods.  Previously the extended ranges
            were mapped to 0 or 1 so that the "under" and "over"
-           colormap colors were ignored. - EF
+           colormap colors were ignored. This change also increases
+           slightly the color contrast for a given set of contour
+           levels. - EF
 
 2012-06-24 Make use of mathtext in tick labels configurable - DSD
 
diff --git a/lib/matplotlib/axes.py b/lib/matplotlib/axes.py
@@ -3754,7 +3754,7 @@ def vlines(self, x, ymin, ymax, colors='k', linestyles='solid',
                                     linestyles=linestyles, label=label)
         self.add_collection(coll)
         coll.update(kwargs)
-      
+
         if len(x) > 0:
             minx = min( x )
             maxx = max( x )
@@ -6955,16 +6955,18 @@ def pcolor(self, *args, **kwargs):
             A :class:`matplotlib.colors.Colormap` instance. If *None*, use
             rc settings.
 
-          norm: [ *None* | Normalize ]
+          *norm*: [ *None* | Normalize ]
             An :class:`matplotlib.colors.Normalize` instance is used
             to scale luminance data to 0,1. If *None*, defaults to
             :func:`normalize`.
 
           *vmin*/*vmax*: [ *None* | scalar ]
             *vmin* and *vmax* are used in conjunction with *norm* to
-            normalize luminance data.  If either are *None*, the min
-            and max of the color array *C* is used.  If you pass a
-            *norm* instance, *vmin* and *vmax* will be ignored.
+            normalize luminance data.  If either is *None*, it
+            is autoscaled to the respective min or max
+            of the color array *C*.  If not *None*, *vmin* or
+            *vmax* passed in here override any pre-existing values
+            supplied in the *norm* instance.
 
           *shading*: [ 'flat' | 'faceted' ]
             If 'faceted', a black grid is drawn around each rectangle; if
@@ -7121,10 +7123,8 @@ def pcolor(self, *args, **kwargs):
         if norm is not None: assert(isinstance(norm, mcolors.Normalize))
         collection.set_cmap(cmap)
         collection.set_norm(norm)
-        if vmin is not None or vmax is not None:
-            collection.set_clim(vmin, vmax)
-        else:
-            collection.autoscale_None()
+        collection.set_clim(vmin, vmax)
+        collection.autoscale_None()
         self.grid(False)
 
         x = X.compressed()
@@ -7167,9 +7167,11 @@ def pcolormesh(self, *args, **kwargs):
 
           *vmin*/*vmax*: [ *None* | scalar ]
             *vmin* and *vmax* are used in conjunction with *norm* to
-            normalize luminance data.  If either are *None*, the min
-            and max of the color array *C* is used.  If you pass a
-            *norm* instance, *vmin* and *vmax* will be ignored.
+            normalize luminance data.  If either is *None*, it
+            is autoscaled to the respective min or max
+            of the color array *C*.  If not *None*, *vmin* or
+            *vmax* passed in here override any pre-existing values
+            supplied in the *norm* instance.
 
           *shading*: [ 'flat' | 'gouraud' ]
             'flat' indicates a solid color for each quad.  When
@@ -7235,10 +7237,8 @@ def pcolormesh(self, *args, **kwargs):
         if norm is not None: assert(isinstance(norm, mcolors.Normalize))
         collection.set_cmap(cmap)
         collection.set_norm(norm)
-        if vmin is not None or vmax is not None:
-            collection.set_clim(vmin, vmax)
-        else:
-            collection.autoscale_None()
+        collection.set_clim(vmin, vmax)
+        collection.autoscale_None()
 
         self.grid(False)
 
diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py
@@ -742,6 +742,8 @@ def __init__(self, ax, *args, **kwargs):
         cmap = kwargs.get('cmap', None)
         self.colors = kwargs.get('colors', None)
         norm = kwargs.get('norm', None)
+        vmin = kwargs.get('vmin', None)
+        vmax = kwargs.get('vmax', None)
         self.extend = kwargs.get('extend', 'neither')
         self.antialiased = kwargs.get('antialiased', None)
         if self.antialiased is None and self.filled:
@@ -789,7 +791,11 @@ def __init__(self, ax, *args, **kwargs):
         kw = {'cmap': cmap}
         if norm is not None:
             kw['norm'] = norm
-        cm.ScalarMappable.__init__(self, **kw) # sets self.cmap;
+        cm.ScalarMappable.__init__(self, **kw) # sets self.cmap, norm if needed;
+        if vmin is not None:
+            self.norm.vmin = vmin
+        if vmax is not None:
+            self.norm.vmax = vmax
         self._process_colors()
 
         self.allsegs, self.allkinds = self._get_allsegs_and_allkinds()
@@ -1488,6 +1494,12 @@ def _initialize_x_y(self, z):
             scaling data values to colors. If *norm* is *None* and
             *colors* is *None*, the default linear scaling is used.
 
+          *vmin*/*vmax*: [ *None* | scalar ]
+            If not *None*, either or both of these values will be
+            supplied to the :class:`matplotlib.colors.Normalize`
+            instance, overriding the default color scaling based on
+            *levels*.
+
           *levels*: [level0, level1, ..., leveln]
             A list of floating point numbers indicating the level
             curves to draw; eg to draw just the zero contour pass
