moved fill_between to axes/pyplot method

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

Author: jdh2358

boilerplate.py

@@ -64,6 +64,7 @@ def %(func)s(*args, **kwargs):
     'csd',
     'errorbar',
     'fill',
+    'fill_between',
     'hexbin',
     'hist',
     'hlines',

doc/_templates/index.html

@@ -409,6 +409,19 @@ <h3>Plotting commands</h3> <br/>
       </td>
 
     </tr>
+
+    <tr>
+      <th align="left">
+        <a href="api/pyplot_api.html#matplotlib.pyplot.fill_between">fill_between</a>
+
+      </th>
+
+      <td align="left">
+        make filled polygons between two curves
+      </td>
+
+    </tr>
+
     <tr>
       <th align="left">
         <a href="api/pyplot_api.html#matplotlib.pyplot.findobj">findobj</a>

examples/api/fill_where_demo.py

@@ -17,7 +17,7 @@
 fig = plt.figure()
 ax = fig.add_subplot(111)
 ax.set_title('using fill_between_where')
-ax.plot(t, s1, t, s2)
+ax.plot(t, s1, t, s2, color='black')
 ax.axhline(0, color='black', lw=2)
 
 collection = collections.PolyCollection.fill_between_where(
@@ -32,7 +32,7 @@
 fig = plt.figure()
 ax = fig.add_subplot(111)
 ax.set_title('using span_where')
-ax.plot(t, s1, '-')
+ax.plot(t, s1, , color='black')
 ax.axhline(0, color='black', lw=2)
 
 collection = collections.BrokenBarHCollection.span_where(

examples/api/span_regions.py

@@ -0,0 +1,38 @@
+"""
+Illustrate some helper functions for shading regions where a logical
+mask is True
+
+See :meth:`matplotlib.collections.BrokenBarHCollection.span_where`
+"""
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.collections as collections
+
+
+t = np.arange(0.0, 2, 0.01)
+s1 = np.sin(2*np.pi*t)
+s2 = 1.2*np.sin(4*np.pi*t)
+
+
+fig = plt.figure()
+ax = fig.add_subplot(111)
+ax.set_title('using span_where')
+ax.plot(t, s1, color='black')
+ax.axhline(0, color='black', lw=2)
+
+collection = collections.BrokenBarHCollection.span_where(
+	   t, ymin=0, ymax=1, where=s1>0, facecolor='green', alpha=0.5)
+ax.add_collection(collection)
+
+collection = collections.BrokenBarHCollection.span_where(
+	   t, ymin=-1, ymax=0, where=s1<0, facecolor='red', alpha=0.5)
+ax.add_collection(collection)
+
+
+
+plt.show()
+
+
+
+
+

examples/pylab_examples/fill_between.py

@@ -3,27 +3,31 @@
 from pylab import figure, show
 import numpy as np
 
-x = np.arange(0, 2, 0.01)
+x = np.arange(0.0, 2, 0.01)
 y1 = np.sin(2*np.pi*x)
-y2 = np.sin(4*np.pi*x) + 2
+y2 = 1.2*np.sin(4*np.pi*x)
 
 fig = figure()
-ax = fig.add_subplot(311)
-ax2 = fig.add_subplot(312)
-ax3 = fig.add_subplot(313)
+ax1 = fig.add_subplot(311)
+ax2 = fig.add_subplot(312, sharex=ax1)
+ax3 = fig.add_subplot(313, sharex=ax1)
 
+ax1.fill_between(x, 0, y1)
+ax1.set_ylabel('between y1 and 0')
 
-xs, ys = mlab.poly_between(x, 0, y1)
-ax.fill(xs, ys)
-ax.set_ylabel('between y1 and 0')
-
-xs, ys = mlab.poly_between(x, y1, 1)
-ax2.fill(xs, ys)
+ax2.fill_between(x, y1, 1)
 ax2.set_ylabel('between y1 and 1')
 
-xs, ys = mlab.poly_between(x, y1, y2)
-ax3.fill(xs, ys)
+ax3.fill_between(x, y1, y2)
 ax3.set_ylabel('between y1 and y2')
 ax3.set_xlabel('x')
+
+fig = figure()
+ax = fig.add_subplot(111)
+ax1.plot(x, y1, x, y2, color='black')
+ax.fill_between(x, y1, y2, where=y2>y1, facecolor='green')
+ax.fill_between(x, y1, y2, where=y2<=y1, facecolor='red')
+ax.set_title('fill between where')
+
 show()
 

lib/matplotlib/axes.py

@@ -1302,6 +1302,7 @@ def add_collection(self, collection, autolim=True):
         if autolim:
             if collection._paths and len(collection._paths):
                 self.update_datalim(collection.get_datalim(self.transData))
+
         collection._remove_method = lambda h: self.collections.remove(h)
 
     def add_line(self, line):
@@ -5456,11 +5457,7 @@ def fill(self, *args, **kwargs):
         supports are supported by the fill format string.
 
         If you would like to fill below a curve, eg. shade a region
-        between 0 and *y* along *x*, use
-        :func:`~matplotlib.pylab.poly_between`, eg.::
-
-          xs, ys = poly_between(x, 0, y)
-          axes.fill(xs, ys, facecolor='red', alpha=0.5)
+        between 0 and *y* along *x*, use :meth:`fill_between`
 
         The *closed* kwarg will close the polygon when *True* (default).
 
@@ -5472,9 +5469,6 @@ def fill(self, *args, **kwargs):
 
         .. plot:: mpl_examples/pylab_examples/fill_demo.py
 
-        .. seealso::
-            :file:`examples/pylab_examples/fill_between.py`:
-                For more examples.
         """
         if not self._hold: self.cla()
 
@@ -5486,6 +5480,92 @@ def fill(self, *args, **kwargs):
         return patches
     fill.__doc__ = cbook.dedent(fill.__doc__) % martist.kwdocd
 
+    def fill_between(self, x, y1, y2=0, where=None, **kwargs):
+        """
+        call signature::
+
+          fill_between(x, y1, y2=0, where=None, **kwargs)
+
+        Create a :class:`~matplotlib.collectionsPolyCollection`
+        filling the regions between *y1* and *y2* where
+        ``where==True``
+
+        *x*
+          an N length np array of the x data
+
+        *y1*
+          an N length scalar or np array of the x data
+
+        *y2*
+          an N length scalar or np array of the x data
+
+        *where*
+           if None, default to fill between everywhere.  If not None,
+           it is a a N length numpy boolean array and the fill will
+           only happen over the regions where ``where==True``
+
+        *kwargs*
+          keyword args passed on to the :class:`PolyCollection`
+
+        .. seealso::
+            :file:`examples/pylab_examples/fill_between.py`:
+                For more examples.
+
+        kwargs control the Polygon properties:
+
+        %(PolyCollection)s
+
+        """
+        x = np.asarray(x)
+	if not cbook.iterable(y1):
+	    y1 = np.ones_like(x)*y1
+
+	if not cbook.iterable(y2):
+	    y2 = np.ones_like(x)*y2
+
+	if where is None:
+	    where = np.ones(len(x), np.bool)
+
+        y1 = np.asarray(y1)
+        y2 = np.asarray(y2)
+        where = np.asarray(where)
+        assert( (len(x)==len(y1)) and (len(x)==len(y2)) and len(x)==len(where))
+
+        polys = []
+        for ind0, ind1 in mlab.contiguous_regions(where):
+            theseverts = []
+            xslice = x[ind0:ind1]
+            y1slice = y1[ind0:ind1]
+            y2slice = y2[ind0:ind1]
+
+            if not len(xslice):
+                continue
+
+            N = len(xslice)
+            X = np.zeros((2*N+2, 2), np.float)
+
+            # the purpose of the next two lines is for when y2 is a
+            # scalar like 0 and we want the fill to go all the way
+            # down to 0 even if none of the y1 sample points do
+            X[0] = xslice[0], y2slice[0]
+            X[N+1] = xslice[-1], y2slice[-1]
+
+            X[1:N+1,0] = xslice
+            X[1:N+1,1] = y1slice
+            X[N+2:,0] = xslice[::-1]
+            X[N+2:,1] = y2slice[::-1]
+
+            polys.append(X)
+
+        collection = mcoll.PolyCollection(polys, **kwargs)
+
+        self.update_datalim_numerix(x[where], y1[where])
+        self.update_datalim_numerix(x[where], y2[where])
+        self.add_collection(collection)
+        self.autoscale_view()
+        return collection
+    fill_between.__doc__ = cbook.dedent(fill_between.__doc__) % martist.kwdocd
+
     #### plotting z(x,y): imshow, pcolor and relatives, contour
 
     def imshow(self, X, cmap=None, norm=None, aspect=None,

lib/matplotlib/collections.py

@@ -673,66 +673,6 @@ def draw(self, renderer):
         return Collection.draw(self, renderer)
 
 
-    @staticmethod
-    def fill_between_where(x, y1, y2, where, **kwargs):
-        """
-        Create a :class:`PolyCollection` filling the regions between *y*
-        and *yboundary7* where ``where==True``
-
-
-        *x*
-          an N length np array of the x data
-
-        *y1*
-          an N length scalar or np array of the x data
-
-        *y2*
-          an N length scalar or np array of the x data
-
-        *where*
-          an N length numpy boolean array
-
-        *kwargs*
-          keyword args passed on to the :class:`PolyCollection`
-
-        """
-	if not cbook.iterable(y1):
-	    y1 = np.ones_like(x)*y1
-
-	if not cbook.iterable(y2):
-	    y2 = np.ones_like(x)*y2
-
-        assert( (len(x)==len(y1)) and (len(x)==len(y2)) )
-
-        polys = []
-        for ind0, ind1 in mlab.contiguous_regions(where):
-            theseverts = []
-            xslice = x[ind0:ind1]
-            y1slice = y1[ind0:ind1]
-            y2slice = y2[ind0:ind1]
-
-            if not len(xslice):
-                continue
-
-            N = len(xslice)
-            X = np.zeros((2*N+2, 2), np.float)
-
-            # the purpose of the next two lines is for when y2 is a
-            # scalar like 0 and we want the fill to go all the way
-            # down to 0 even if none of the y1 sample points do
-            X[0] = xslice[0], y2slice[0]
-            X[N+1] = xslice[-1], y2slice[-1]
-
-            X[1:N+1,0] = xslice
-            X[1:N+1,1] = y1slice
-            X[N+2:,0] = xslice[::-1]
-            X[N+2:,1] = y2slice[::-1]
-
-            polys.append(X)
-
-        collection = PolyCollection(polys, **kwargs)
-        return collection
-
 class BrokenBarHCollection(PolyCollection):
     """
     A collection of horizontal bars spanning *yrange* with a sequence of