contour, contourf return ContourSet object; colorbar uses it

svn path=/trunk/matplotlib/; revision=1788

Author: efiring

API_CHANGES

@@ -1,6 +1,35 @@
+
+    Changed the internal structure of contour.py to a more OO style.
+    Calls to contour or contourf in axes.py or pylab.py now return
+    a ContourSet object which contains references to the
+    LineCollections or PolyCollections created by the call,
+    as well as the configuration variables that were used.
+    The ContourSet object is a "mappable" if a colormap was used.
+
+    Added a clip_ends kwarg to contourf. From the docstring:
+             * clip_ends = True
+               If False, the limits for color scaling are set to the
+               minimum and maximum contour levels.
+               True (default) clips the scaling limits.  Example:
+               if the contour boundaries are V = [-100, 2, 1, 0, 1, 2, 100],
+               then the scaling limits will be [-100, 100] if clip_ends
+               is False, and [-3, 3] if clip_ends is True.
+
+    Changed Figure.colorbar():
+        kw argument order changed;
+        if mappable arg is a non-filled ContourSet, colorbar() shows
+                lines instead of polygons.
+        if mappable arg is a filled ContourSet with clip_ends=True,
+                the endpoints are not labelled, so as to give the
+                correct impression of open-endedness.
+
+    Changed LineCollection.get_linewidths to get_linewidth, for
+    consistency.
+
+
 API Changes in matplotlib-0.84
 
-    Unified argument handling between hlines and vlines.  Both now 
+    Unified argument handling between hlines and vlines.  Both now
     take optionally a fmt argument (as in plot) and a keyword args
     that can be passed onto Line2D.
 
@@ -32,13 +61,13 @@ API Changes in matplotlib-0.83
 
       from backends import pylab_setup
       new_figure_manager, draw_if_interactive, show = pylab_setup()
-  
+
   - Moved Figure.get_width_height() to FigureCanvasBase. It now
     returns int instead of float.
 
 API Changes in matplotlib-0.82
 
-  - toolbar import change in GTKAgg, GTKCairo and WXAgg 
+  - toolbar import change in GTKAgg, GTKCairo and WXAgg
 
   - Added subplot config tool to GTK* backends -- note you must now
     import the NavigationToolbar2 from your backend of choice rather
@@ -47,7 +76,7 @@ API Changes in matplotlib-0.82
     wx backend -- see examples/embedding_in_wxagg.py
 
 
-  - hist bin change 
+  - hist bin change
 
       Sean Richards notes there was a problem in the way we created
       the binning for histogram, which made the last bin
@@ -63,7 +92,7 @@ API Changes in matplotlib-0.82
         each bin? (i.e. each value should be the lower bound of a
         bin). To provide the correct bins for hist would it not be
         something like
- 
+
         def bins(xmin, xmax, N):
           if N==1: return xmax
           dx = (xmax-xmin)/N # instead of N-1
@@ -159,7 +188,7 @@ API CHANGES in matplotlib-0.72
     consistency with set/get introspection mechanism,
 
   - pylab figure now defaults to num=None, which creates a new figure
-    with a guaranteed unique number 
+    with a guaranteed unique number
 
   - contour method syntax changed - now it is matlab compatible
 
@@ -181,7 +210,7 @@ API CHANGES in matplotlib-0.72
      do not want this behavior, use fig.add_subplot or the axes
      command
 
-API CHANGES in matplotlib-0.71   
+API CHANGES in matplotlib-0.71
 
    Significant numerix namespace changes, introduced to resolve
    namespace clashes between python built-ins and mlab names.
@@ -261,7 +290,7 @@ API CHANGES in matplotlib-0.63
 
   Most of the date tick locators have a different meaning in their
   constructors.  In the prior implementation, the first argument was a
-  base and multiples of the base were ticked.  Eg 
+  base and multiples of the base were ticked.  Eg
 
     HourLocator(5)  # old: tick every 5 minutes
 
@@ -278,7 +307,7 @@ API CHANGES in matplotlib-0.63
   that years are not recurrent.
 
 
-  Financial functions: 
+  Financial functions:
 
     matplotlib.finance.quotes_historical_yahoo(ticker, date1, date2)
 
@@ -300,7 +329,7 @@ API CHANGES in matplotlib-0.60
 ColormapJet and Grayscale are deprecated.  For backwards
 compatibility, they can be obtained either by doing
 
-  from matplotlib.cm import ColormapJet 
+  from matplotlib.cm import ColormapJet
 
 or
 
@@ -355,15 +384,15 @@ available on PolyCollections, eg you can say
   c.set_facecolor('r')
   c.set_alpha(0.5)
 
-or 
+or
 
   c = scatter(blah, blah)
   set(c, 'linewidth', 1.0, 'facecolor', 'r', 'alpha', 0.5)
 
 
 Because the collection is a single object, you no longer need to loop
 over the return value of scatter or pcolor to set properties for the
-entire list. 
+entire list.
 
 If you want the different elements of a collection to vary on a
 property, eg to have different line widths, see matplotlib.collections
@@ -411,7 +440,7 @@ Axes creation
       f = Figure(figsize=(5,4), dpi=100)
       a = f.add_subplot(111)
 
-    That is, add_axis no longer exists and is replaced by 
+    That is, add_axis no longer exists and is replaced by
 
       add_axes(rect, axisbg=defaultcolor, frameon=True)
       add_subplot(num, axisbg=defaultcolor, frameon=True)
@@ -423,12 +452,12 @@ Artist methods
   to draw
 
 Bounding boxes
---------------  
+--------------
 
    matplotlib.transforms.Bound2D is replaced by
    matplotlib.transforms.Bbox.  If you want to construct a bbox from
    left, bottom, width, height (the signature for Bound2D), use
-   matplotlib.transforms.lbwh_to_bbox, as in 
+   matplotlib.transforms.lbwh_to_bbox, as in
 
     bbox = clickBBox = lbwh_to_bbox(left, bottom, width, height)
 
@@ -466,7 +495,7 @@ Object constructors
         l =  Line2D(dpi, bbox, x, y,
                     color = color,
                     transx = transx,
-                    transy = transy,	
+                    transy = transy,
                     )
 
   now all you need is
@@ -502,7 +531,7 @@ Transformations
 
    * because they operate on x and y together, they can do the entire
      transformation in one loop.  Earlier I did something along the
-     lines of 
+     lines of
 
        xt = sx*func(x) + tx
        yt = sy*func(y) + ty
@@ -520,8 +549,8 @@ Transformations
   Likewise, if you are using the artist bounding boxes to pick items
   on the canvas with the GUI, the bbox methods are somewhat
   different.  You will need to see the updated
-  examples/object_picker.py. 
- 
+  examples/object_picker.py.
+
   See unit/transforms_unit.py for many examples using the new
   transformations.
 
@@ -559,12 +588,12 @@ API changes at 0.50
 
 Migrating code:
 
-  Matlab interface: 
+  Matlab interface:
 
     The only API change for those using the matlab interface is in how
     you call figure redraws for dynamically updating figures.  In the
     old API, you did
-   
+
       fig.draw()
 
     In the new API, you do
@@ -594,23 +623,23 @@ Migrating code:
     FigureCanvas, not a Figure.  The examples embedding_in_gtk.py,
     embedding_in_gtk2.py, and mpl_with_glade.py all reflect the new
     API so use these as a guide.
- 
-    All prior calls to 
+
+    All prior calls to
 
      figure.draw()  and
-     figure.print_figure(args) 
+     figure.print_figure(args)
 
     should now be
- 
+
      canvas.draw()  and
-     canvas.print_figure(args) 
+     canvas.print_figure(args)
 
     Apologies for the inconvenience.  This refactorization brings
     significant more freedom in developing matplotlib and should bring
     better plotting capabilities, so I hope the inconvenience is worth
     it.
 
-  
+
 
 API changes at 0.42
 
@@ -628,7 +657,7 @@ API changes at 0.42
     backend_gtk for an example.
 
   * Text._get_xy_display renamed Text.get_xy_display
-  
+
   * Artist set_renderer and wash_brushes methods removed
 
   * Moved Legend class from matplotlib.axes into matplotlib.legend
@@ -646,7 +675,7 @@ API changes at 0.42
     matplotlib.matlab.get_current_fig_manager to allow user access to
     the GUI window attribute, eg figManager.window for GTK and
     figManager.frame for wx
-  
+
 
 
 
@@ -661,7 +690,7 @@ API changes at 0.40
     * the clip_gc method is removed.  Artists now clip themselves with
       their box
     * added _clipOn boolean attribute.  If True, gc clip to bbox.
-    
+
 - AxisTextBase
     * Initialized with a transx, transy which are Transform instances
     * set_drawing_area removed
@@ -685,7 +714,7 @@ API changes at 0.40
     * removed figbg attribute
     * added fig instance to __init__
     * resizing is handled by figure call to resize.
-     
+
 - Subplot
     * added fig instance to __init__
 

CHANGELOG

@@ -1,5 +1,13 @@
 New entries should be added at the top
 
+2005-09-25 contour.py modified to use a single ContourSet class
+           that handles filled contours, line contours, and labels;
+           added keyword arg (clip_ends) to contourf.
+           Colorbar modified to work with new ContourSet object;
+           if the ContourSet has lines rather than polygons, the
+           colorbar will follow suit. Fixed a bug introduced in
+           0.84, in which contourf(...,colors=...) was broken - EF
+
 2005-09-14 Added a new 'resize_event' which triggers a callback with a
            backend_bases.ResizeEvent object - JDH
 

boilerplate.py

@@ -92,9 +92,9 @@ def %(func)s(*args, **kwargs):
     )
 
 cmappable = {
-    'clabel' : 'if ret.mappable is not None: gci._current = ret.mappable',
-    'contour' : 'if ret[1].mappable is not None: gci._current = ret[1].mappable',
-    'contourf': 'if ret[1].mappable is not None: gci._current = ret[1].mappable',
+    #'clabel' : 'if ret.mappable is not None: gci._current = ret.mappable',
+    'contour' : 'if ret._A is not None: gci._current = ret',
+    'contourf': 'if ret._A is not None: gci._current = ret',
     'scatter' : 'gci._current = ret',
     'pcolor'  : 'gci._current = ret',
     'imshow'  : 'gci._current = ret',

examples/contour_demo.py

@@ -7,6 +7,8 @@
 '''
 from pylab import *
 
+rcParams['tick.direction'] = 'out'
+
 delta = 0.025
 x = arange(-3.0, 3.0, delta)
 y = arange(-2.0, 2.0, delta)
@@ -23,27 +25,29 @@
 # over the line segments of the contour, removing the lines beneath
 # the label
 figure()
-levels, colls = contour(X, Y, Z)
-clabel(colls, inline=1, fontsize=10)
+CS = contour(X, Y, Z)
+clabel(CS, inline=1, fontsize=10)
 title('Simplest default with labels')
 
 
-# You can force all the contours to be the same color
+# You can force all the contours to be the same color.
+# Use colors = 'k' to make negative contours dashed;
+# use colors = ('k',) to leave all contours solid.
 figure()
-levels, colls = contour(X, Y, Z, 6,
-                        colors=('k',)
-                        )
-clabel(colls, levels, fontsize=9, inline=1)
+CS = contour(X, Y, Z, 6,
+             colors='k', # or ('k',) for all solid
+             )
+clabel(CS, fontsize=9, inline=1)
 title('Single color')
 
 
 # And you can manually specify the colors of the contour
 figure()
-levels, colls = contour(X, Y, Z, 6,
-                        linewidths=arange(.5, 4, .5),
-                        colors=('r', 'green', 'blue', (1,1,0), '#afeeee', 0.5)
-                        )
-clabel(colls, levels, fontsize=9, inline=1)
+CS = contour(X, Y, Z, 6,
+             linewidths=arange(.5, 4, .5),
+             colors=('r', 'green', 'blue', (1,1,0), '#afeeee', 0.5)
+             )
+clabel(CS, fontsize=9, inline=1)
 title('Crazy lines')
 
 
@@ -52,20 +56,30 @@
 figure()
 im = imshow(Z, interpolation='bilinear', origin='lower',
             cmap=cm.gray, extent=(-3,3,-2,2))
-levels, colls = contour(Z, arange(-1.2,1.6,0.2),
-                        origin='lower',
-                        linewidths=2,
-                        extent=(-3,3,-2,2))
+levels = arange(-1.2, 1.6, 0.2)
+CS = contour(Z, levels,
+             origin='lower',
+             linewidths=2,
+             extent=(-3,3,-2,2))
+
+#Thicken the zero contour.
+zc = CS.collections[6]
+setp(zc, linewidth=4)
 
-clabel(colls, levels,
+clabel(CS, levels[1::2],  # label every second level
        inline=1,
        fmt='%1.1f',
-       fontsize=10)
+       fontsize=14)
 
-colorbar()  # make a colorbar for the contour lines
+colorbar(CS)  # make a colorbar for the contour lines
 title('Lines with colorbar')
 hot()  # Now change the colormap for the contour lines and colorbar
+flag()
 
+# We can still add a colorbar for the image, too.
+colorbar(im, orientation='horizontal')
+# We could manipulate the colorbar axes sizes for better
+# appearance, but we'll leave that for a later demo.
 
 savefig('contour_demo')
 show()