Axes.bar: added error_kw kwarg

efiring · efiring · commit dbf28b44c52c · 2010-06-02T20:41:10.000Z
svn path=/trunk/matplotlib/; revision=8369
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,3 +1,5 @@
+2010-06-02 Add error_kw kwarg to Axes.bar(). - EF
+
 2010-06-01 Fix pcolormesh() and QuadMesh to pass on kwargs as
            appropriate. - RM
 
diff --git a/doc/api/api_changes.rst b/doc/api/api_changes.rst
@@ -10,6 +10,10 @@ list may help describe what changes may be necessary in your code.
 Changes beyond 0.99.x
 =====================
 
+* The :meth:`matplotlib.axes.Axes.bar` method accepts a *error_kw*
+  kwarg; it is a dictionary of kwargs to be passed to the
+  errorbar function.
+
 * The :meth:`matplotlib.axes.Axes.hist` *color* kwarg now accepts
   a sequence of color specs to match a sequence of datasets.
 
diff --git a/examples/pylab_examples/barchart_demo.py b/examples/pylab_examples/barchart_demo.py
@@ -12,11 +12,17 @@
 
 
 plt.subplot(111)
-rects1 = plt.bar(ind, menMeans, width, color='r', yerr=menStd)
+rects1 = plt.bar(ind, menMeans, width,
+                    color='r',
+                    yerr=menStd,
+                    error_kw=dict(elinewidth=6, ecolor='pink'))
 
 womenMeans = (25, 32, 34, 20, 25)
 womenStd =   (3, 5, 2, 3, 3)
-rects2 = plt.bar(ind+width, womenMeans, width, color='y', yerr=womenStd)
+rects2 = plt.bar(ind+width, womenMeans, width,
+                    color='y',
+                    yerr=womenStd,
+                    error_kw=dict(elinewidth=6, ecolor='yellow'))
 
 # add some
 plt.ylabel('Scores')
diff --git a/lib/matplotlib/axes.py b/lib/matplotlib/axes.py
@@ -4288,6 +4288,10 @@ def bar(self, left, height, width=0.8, bottom=None, **kwargs):
           *ecolor*          specifies the color of any errorbar
           *capsize*         (default 3) determines the length in
                             points of the error bar caps
+          *error_kw*        dictionary of kwargs to be passed to
+                            errorbar method. *ecolor* and *capsize*
+                            may be specified here rather than as
+                            independent kwargs.
           *align*           'edge' (default) | 'center'
           *orientation*     'vertical' | 'horizontal'
           *log*             [False|True] False (default) leaves the
@@ -4322,13 +4326,18 @@ def bar(self, left, height, width=0.8, bottom=None, **kwargs):
         color = kwargs.pop('color', None)
         edgecolor = kwargs.pop('edgecolor', None)
         linewidth = kwargs.pop('linewidth', None)
+
         # Because xerr and yerr will be passed to errorbar,
         # most dimension checking and processing will be left
         # to the errorbar method.
         xerr = kwargs.pop('xerr', None)
         yerr = kwargs.pop('yerr', None)
+        error_kw = kwargs.pop('error_kw', dict())
         ecolor = kwargs.pop('ecolor', None)
         capsize = kwargs.pop('capsize', 3)
+        error_kw.setdefault('ecolor', ecolor)
+        error_kw.setdefault('capsize', capsize)
+
         align = kwargs.pop('align', 'edge')
         orientation = kwargs.pop('orientation', 'vertical')
         log = kwargs.pop('log', False)
@@ -4478,7 +4487,7 @@ def make_iterable(x):
             self.errorbar(
                 x, y,
                 yerr=yerr, xerr=xerr,
-                fmt=None, ecolor=ecolor, capsize=capsize)
+                fmt=None, **error_kw)
 
         self.hold(holdstate) # restore previous hold state
 
@@ -4833,17 +4842,17 @@ def errorbar(self, x, y, yerr=None, xerr=None,
             If a scalar number, len(N) array-like object, or an Nx1 array-like
             object, errorbars are drawn +/- value.
 
-            If a rank-1, 2xN numpy array, errorbars are drawn at -row1 and
+            If a sequence of shape 2xN, errorbars are drawn at -row1 and
             +row2
 
           *fmt*: '-'
-            The plot format symbol for *y*. If *fmt* is *None*, just plot the
-            errorbars with no line symbols.  This can be useful for creating a
-            bar plot with errorbars.
+            The plot format symbol. If *fmt* is *None*, only the
+            errorbars are plotted.  This is used for adding
+            errorbars to a bar plot, for example.
 
           *ecolor*: [ None | mpl color ]
-            a matplotlib color arg which gives the color the errorbar lines; if
-            *None*, use the marker color.
+            a matplotlib color arg which gives the color the errorbar lines;
+            if *None*, use the marker color.
 
           *elinewidth*: scalar
             the linewidth of the errorbar lines. If *None*, use the linewidth.
@@ -4862,8 +4871,7 @@ def errorbar(self, x, y, yerr=None, xerr=None,
             type as *xerr* and *yerr*.
 
         All other keyword arguments are passed on to the plot command for the
-        markers, so you can add additional key=value pairs to control the
-        errorbar markers.  For example, this code makes big red squares with
+        markers, For example, this code makes big red squares with
         thick green edges::
 
           x,y,yerr = rand(3,10)
@@ -4878,12 +4886,16 @@ def errorbar(self, x, y, yerr=None, xerr=None,
 
         %(Line2D)s
 
-        Return value is a length 3 tuple.  The first element is the
-        :class:`~matplotlib.lines.Line2D` instance for the *y* symbol
-        lines.  The second element is a list of error bar cap lines,
-        the third element is a list of
-        :class:`~matplotlib.collections.LineCollection` instances for
-        the horizontal and vertical error ranges.
+        Returns (*plotline*, *caplines*, *barlinecols*):
+
+            *plotline*: :class:`~matplotlib.lines.Line2D` instance
+                *x*, *y* plot markers and/or line
+
+            *caplines*: list of error bar cap
+                :class:`~matplotlib.lines.Line2D` instances
+            *barlinecols*: list of
+                :class:`~matplotlib.collections.LineCollection` instances for
+                the horizontal and vertical error ranges.
 
         **Example:**
 

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+2010-06-02 Add error_kw kwarg to Axes.bar(). - EF`
	`2`	`+`
`1`	`3`	`2010-06-01 Fix pcolormesh() and QuadMesh to pass on kwargs as`
`2`	`4`	`appropriate. - RM`
`3`	`5`